# Vibe-Research: a local A-share, US and HK stock research workbench driven by your own agent > Vibe-Research is a TypeScript and Python workbench that runs on 127.0.0.1:5930, keeps the agent switched off until you turn it on, and records every number in a six-stage A-share research run back to a source file. It is built for people who already pay for Codex, Claude Code or WorkBuddy and want their research trail kept locally. **simonlin1212/Vibe-Research** — Vibe-Research: Your Personal Trading Research Agent · A股/美股/港股 的个人投研 Agent：每日复盘、资讯雷达、个股数据、板块中心、我的持仓、研究记录、回测。Vibe-Research 把数据和功能配齐，由你自己的 Agent 驱动投资研究。基于开源的 Codex Harness 打造。 - Repository: https://github.com/simonlin1212/Vibe-Research - Website: https://viberesearch.wiki - Stars: 2,599 · Forks: 531 - Language: TypeScript - License: MIT - Published: 2026-09-09 · Updated: 2026-09-09 · Language: en - Canonical page: https://hysenlabs.com/projects/simonlin1212-vibe-research ## What Vibe-Research solves for the A-share, US and HK stock researcher Most retail research tooling splits into two unsatisfying halves. A data terminal gives you numbers with no reasoning attached, and a chat window gives you reasoning with no numbers attached. Vibe-Research tries to sit in the middle: a local browser workbench at 127.0.0.1:5930 that holds the data modules (daily review, news radar, sector centre, holdings, watchlist) and hands the reasoning to an agent you already pay for. The README is explicit about the audience. It is a personal research workbench, not a trading system. The five entry points on the home screen are daily review, news radar, industry signals, sector centre and single-stock research. Holdings and watchlists accept A-share, US and HK tickers, and the backtest module is deliberately narrow: it only offers an agent conversation entry, asks follow-up questions when the information is insufficient, and calls a real backtest tool once the inputs are complete. The interesting design decision is that the agent is off by default. The README describes an opt-in switch next to the AI source in the top left, mirrored in the settings page. Plain conversation keeps the chat log but starts no tools and keeps no agent task memory. Turning the switch on gives the agent local data access, calculations and the research tools. That boundary matters if you want a translation or a quick lookup without spawning a multi-step research run. ## How the Codex Harness, Claude Code and WorkBuddy runtimes are wired together Vibe-Research does not ship its own model. It is a layer above three subscription runtimes. Codex subscriptions are carried by the OpenAI Codex Harness, Claude.ai subscriptions by a local Claude Code agent, and WorkBuddy / CodeBuddy accounts by Tencent's official CodeBuddy Code CLI. The repository pins the harness version in codex-version.json, and the README states the current development branch locks and has verified 0.153.4 locally, so users do not install a global Codex. On top of those runtimes the project stacks financial data, a research SOP, deterministic calculation, evidence checking and compliance boundaries. The six-stage A-share research flow (company profile, financials, consensus expectations, valuation, risk, report) runs through five controlled MCP tools. The README states that during research stages the runtimes' built-in tools are disabled and only those five tools are exposed, and that the system will not silently fall back to Codex. The output of a run is a directory rather than a paragraph. report.md holds the final report, evidence.json keeps each piece of evidence with source, data period and the original quotation, calculations.json records the inputs, functions and calculation DAG behind derived numbers, conflicts.json records cross-source conflicts without silently picking a winner, manifest.json records model, version, stage, status, recall and the run manifest, and viewer.html renders evidence and report in a browser. If a key figure cannot be obtained, the README says the status becomes incomplete or failed rather than filling the gap with a stale value or a guess. That is the strongest claim in the repository and also the one that shapes everything else: a research run can legitimately end without an answer. ## Installing Vibe-Research from source and running the first research query There is no installer for the current source version. The README states v1.2.0 withdraws the Mac client and maintains only the source tree plus the local browser workbench, so the path is clone, setup, start. You need Node.js 22.18 or newer (24 LTS recommended), Python 3.11 or newer (3.12 verified), and Git. Windows runs natively without WSL. On Windows, the setup and start scripts are batch files. setup-windows.cmd creates the .venv, installs Node and Python dependencies, initialises the private directories and runs a health check. start.cmd brings up the local API and the browser UI, then opens http://127.0.0.1:5930. ```bat git clone https://github.com/simonlin1212/Vibe-Research.git vibe-research-agent cd vibe-research-agent scripts\setup-windows.cmd scripts\start.cmd ``` On macOS and Linux the equivalent scripts have no extension. The README notes that scripts/start checks the install state and the port, starts both ends, and only opens the browser once both are confirmed usable, so you do not need two terminals and you do not need a global Codex. ```bash git clone https://github.com/simonlin1212/Vibe-Research.git vibe-research-agent cd vibe-research-agent scripts/setup scripts/start ``` Before running npm test, check the Node build. The README states that Node must be a build with TypeScript support enabled, so node -p process.features.typescript should print strip or transform. Distribution-packaged Node on some Linux distributions disables this and fails with ERR_UNKNOWN_FILE_EXTENSION ".ts" or ERR_NO_TYPESCRIPT. npm test performs this check first and prints the same hint. ```bash node -p process.features.typescript ``` After the browser opens, the first screen shows the chat box and, if nothing is connected, an AI connection dialog. Already-logged-in Codex, Claude Code or WorkBuddy accounts can be tested and saved from the corresponding entry; the other entry opens settings for API configuration. A new connection defaults to agent off. To run research rather than chat, flip the switch in the top left, then use one of the five entry points. Screenshots in the repository were taken on an isolated workspace with no positions, research files or credentials. ## Where Vibe-Research is the wrong tool The clearest limitation is packaging. The README states the current source version does not provide a new installer, that the Mac client is withdrawn for now, and that the existing v1.1.0 release and historical installers remain as historical versions. If you want a double-clickable desktop app, this is not it right now. Anyone upgrading from the old Mac client should also read the source delivery note, because the README says old client data is not migrated into the source workspace automatically and warns against deleting or committing ~/.vibe-research-desktop. The second boundary is scope. The backtest module is an agent conversation, not a strategy IDE. It asks for missing information before calling the real backtest tool. If you want to write and sweep parameterised strategies in code, that workflow is not described here. The third is operational. Subscription-based plain conversation still requires the corresponding client to be running, and the README explicitly does not promise a fixed response time. Research runs can be aborted, but the README is careful: issuing a stop request does not mean the background process has stopped, and the page distinguishes a stop request, a stop confirmation and a failure state that cannot be confirmed. Refreshing the page lets you keep watching the status, and completed stages are preserved. Finally, holdings import is draft-only. Screenshots or tables are transcribed into a draft that a human must check before saving; selected image or table content is sent to the current AI source, so the README tells you to remove unrelated sensitive information before submitting. Temporary transcription files are cleaned up on success, failure or cancellation, but that cleanup is local only and says nothing about what the model provider retains. ## How Vibe-Research differs from running a raw Codex or Claude Code session The obvious alternative is to open Codex or Claude Code directly and point it at your own data. You would get the same underlying model and, in the Codex case, the same harness. What you would not get is the layer Vibe-Research adds: the five controlled MCP tools, the six-stage A-share SOP, deterministic calculation with a recorded DAG, evidence files with source and data period, and a conflicts file that refuses to resolve disagreements silently. In a raw session those artefacts either do not exist or depend on you prompting for them every time. The trade-off runs the other way too. A raw session has no opinion about what a research run should look like. Vibe-Research does, and that opinion is encoded in stages and tool restrictions. The README notes that during research stages the runtimes' built-in tools are disabled. That is the point of the design, and it is also a constraint: if your question falls outside the six-stage flow, the workbench may be a worse fit than a plain agent window. The plain conversation mode is the escape hatch, and it is the default. A second alternative is a hosted research product, which removes the Node, Python and .venv setup entirely. The difference in approach is where the data lives. Vibe-Research runs the page on your machine and keeps the research records locally; the README frames this as not uploading private research to a website. The cost is that you own the runtime, the port and the upgrade path. ## Licence, maintenance and what upgrading actually costs The repository is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the extent of what the repository states; it is not legal advice and the LICENSE file is the authority. The maintenance signal is recent. The last push was on 2026-09-09, and the repository is not archived. Recent releases run from v1.0.3 on 2026-09-02 through v1.0.4 on 2026-09-05 to v1.1.0 on 2026-09-07. The README carries a source badge for v1.2.0 while the newest published release is v1.1.0, which matches the stated arrangement: source moves ahead, installers stay behind. Upgrade cost is not zero, and the README is honest about it. If you already have a source copy, back up your data first, then update the code and run setup again rather than re-cloning. The pinned agent engine moves with the project: v1.0.4 shipped Codex 0.149.0 and the current source line uses 0.153.4, so a jump across several versions pulls in a new harness. The changelog is the place to check before upgrading, and the v1.0.4 note about fixing failures with a global MCP configuration is a reminder that local MCP setups can interact badly with the connection test. ## Conclusion Adopt Vibe-Research if you already hold a Codex, Claude Code or WorkBuddy subscription, you follow A-share, US or HK names, and you want the agent off by default with a local evidence chain behind every report. Do not adopt it if you want a hosted service, a packaged desktop installer (the Mac client was withdrawn in v1.2.0), or unattended trading: the backtest module only exposes an agent conversation entry and the README states it asks follow-up questions when information is missing. Verify first that your Node build reports strip or transform for process.features.typescript, that Python 3.11 or newer is available for the .venv, and that you are willing to keep ~/.vibe-research-desktop rather than treat it as disposable. ## FAQ ### What is Vibe-Research? It is a local financial research workbench for A-share, US and HK stocks, running in your browser at 127.0.0.1:5930. It connects to a Codex, Claude Code or WorkBuddy subscription (or a model API) and adds financial data, a research SOP, deterministic calculation and evidence checking on top of that runtime. The agent is off by default and turned on from the top-left switch. ### Is Vibe-Research safe to use with my own account? The README states that subscription adapters reuse the corresponding logged-in account, and that during research stages user configuration, automatic memory and session persistence are isolated while only five controlled MCP tools are exposed. Holdings import sends the selected image or table content to the current AI source, so the README tells you to remove unrelated sensitive information before submitting. Temporary transcription files are cleaned up locally on success, failure or cancellation. ### Can Vibe-Research run backtests on my own strategies? The backtest module only provides an agent conversation entry. According to the README, it asks follow-up questions when information is insufficient and calls a real backtest tool once the inputs are complete. There is no described workflow for writing or sweeping strategies in code. ### Does Vibe-Research provide a desktop installer? Not for the current source version. The README states v1.2.0 withdraws the Mac client and maintains only the source tree plus the local browser workbench, and that no new installer is provided for this update. The v1.1.0 release and historical installers remain on GitHub as historical versions. ## Sources - [License: MIT](https://github.com/simonlin1212/Vibe-Research/blob/main/LICENSE) - [Project website](https://viberesearch.wiki) - [README](https://github.com/simonlin1212/Vibe-Research/blob/main/README.md) - [Releases](https://github.com/simonlin1212/Vibe-Research/releases) - [simonlin1212/Vibe-Research on GitHub](https://github.com/simonlin1212/Vibe-Research) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/simonlin1212-vibe-research