Vibe-Research: A Local Trading Research Agent That Keeps the Agent Off by Default

What Problem It Solves and Who It Is For

Vibe-Research addresses a narrow but real pain: doing multi-step investment research across A-shares, US stocks, and HK stocks without pasting your portfolio into a cloud service. The README describes it as a local financial research workbench. The intended user is someone who already pays for an AI coding assistant subscription, such as Codex, Claude Code, or WorkBuddy, and wants to reuse that subscription for stock analysis. The tool is not for people who want a fully automated trading bot. It is for a retail investor or a solo analyst who wants a structured process: daily market reviews, news screening, sector tracking, individual stock deep dives, and a local record of research reports. The key differentiator is that the Agent is opt-in, not always on. You start in ordinary chat mode, and only when you need web lookups or multi-step research do you flip the Agent switch. That design choice matters because it means you can use the tool for quick questions without paying for tool calls or burning through your model quota.

How It Works: Layered Runtimes and a Five-Tool MCP Limit

Under the hood, Vibe-Research is not a single engine. It is a layer that sits on top of three different AI runtimes: OpenAI Codex Harness, Claude Code, and Tencent's CodeBuddy CLI. The README says that in Agent mode, the tool maintains context, calls tools, advances tasks, handles failures, and saves the research process. For six-phase research, it closes the runtime's built-in tools and exposes only five controlled MCP tools. That means the AI cannot wander off to arbitrary functions; it can only use the data and calculation tools that Vibe-Research provides. The output of a six-phase study is a set of files: `report.md`, `evidence.json`, `calculations.json`, `conflicts.json`, `manifest.json`, and `viewer.html`. The `calculations.json` file stores the input, function, and a computation DAG for every derived number. The `conflicts.json` file records cross-source disagreements rather than silently picking one. If any key data point is unavailable, the status becomes `incomplete` or `failed`, and the tool does not fill in old values or guesses. That is a strong integrity feature, but it also means you may get a failed run if a data source is down.

Getting It Running: Commands, Environment Checks, and the TypeScript Trap

The quick start is straightforward for a developer. You clone the repository, run a setup script, then a start script. On macOS or Linux, the commands are `git clone https://github.com/simonlin1212/Vibe-Research.git vibe-research-agent`, `cd vibe-research-agent`, `scripts/setup`, and `scripts/start`. On Windows, you use `scripts\setup-windows.cmd` and `scripts\start.cmd`. The setup script creates a `.venv`, installs Node and Python dependencies, initializes a private product directory, and runs a health check. The start script checks installation state and port availability, starts both the local API and the browser UI, and only then opens `http://127.0.0.1:5930`. There is no global Codex installation needed; the harness is installed as a dependency. The README warns about a specific environment issue: Node.js must be built with TypeScript support. You can check with `node -p process.features.typescript`, which should output `strip` or `transform`. If you are on a Linux distribution that packages Node without that feature, you will see errors like `ERR_UNKNOWN_FILE_EXTENSION ".ts"` or `ERR_NO_TYPESCRIPT`. The fix is to use the official Node.js build, not a distro package. That is a concrete, avoidable setup failure.

Connecting AI: Subscriptions, APIs, and the Opt-In Agent Switch

After starting the app, the first screen asks you to connect an AI source. You have three subscription options: Codex, Claude Code, and WorkBuddy/CodeBuddy. You can also enter a model API key under 'other access methods'. The README says the settings page detects the CLI, version, and login status in real time. Once connected, the Agent switch in the top-left corner is off by default. In ordinary chat mode, the tool does not call any tools or do web searches. In Agent mode, it can search the web, read pages, fetch data, and perform calculations. The distinction matters for cost and privacy. Subscription-based ordinary chat uses the native subscription or Responses channel without tools. For six-phase research, the tool uses phase-specific MCP tools and isolates user configuration, automatic memory, and session persistence. One important caveat: the README states that subscription ordinary chat still requires the corresponding client to be running, and it does not promise fixed response times. That means if you use Claude Code, you must have the Claude Code CLI installed and logged in. It is not a fully managed service.

A Genuine Limitation: Data Gaps, Incomplete Runs, and the Mac Client Removal

The most honest limitation is in the project's own design: if any key data is unavailable, the research status becomes `incomplete` or `failed`. That is better than fabricating numbers, but it means you cannot rely on the tool for time-sensitive decisions when a data source is temporarily down. The README also notes that the current source version v1.2.0 has removed the Mac client that existed in v1.1.0. The project now only maintains source code plus a local browser workbench. If you were using the old Mac client, your data is not automatically migrated to the source workspace, and the README explicitly tells you not to delete `~/.vibe-research-desktop`. That is a real migration cost for existing users. Another limitation is that the project is essentially a solo developer's effort, with a note in the README saying the author is looking for a job. That does not mean the code is bad, but it does mean long-term maintenance is uncertain. There is no mention of a company or a team behind it.

A Real Alternative: Using a General-Purpose Agent with Your Own Scripts

Instead of adopting Vibe-Research, you could build a similar workflow using the underlying Codex Harness or Claude Code directly. The difference is that Vibe-Research provides a pre-built financial data layer, a research SOP, deterministic calculations, evidence validation, and a compliance boundary. If you go with a general-purpose agent, you must write your own scripts to pull A-share announcements, calculate valuation metrics, and store evidence. You also have to design your own prompt chain for the six-phase research. The advantage of the DIY route is full control and no dependency on a niche project. The disadvantage is time. The README claims that Vibe-Research unifies these layers so ordinary users do not need to understand Harness, scripts, or routing patterns. That is a valid trade-off: you trade setup complexity for a structured, auditable research process. A commercial alternative like Bloomberg Terminal or Wind offers more reliable data but is not open source and does not integrate with your own AI subscription.

Maintenance and Upgrade Cost, and License Implications

The project is licensed under MIT, which means you can modify and redistribute it freely, including for commercial use, as long as you preserve the copyright notice. That is a permissive license, but it also means there is no warranty or support obligation. The README references a CHANGELOG and a `docs/source-delivery.md` file, which suggests that the author documents breaking changes. For example, the transition from v1.1.0 to v1.2.0 removed the Mac client and changed the delivery model. That is a pattern you should expect: the project may change its packaging or features between releases. Upgrade cost is moderate if you follow the source-based workflow. The README says that if you already have a source copy, you should back up your data, update the code, and run `setup` again; you do not need to re-clone. However, old Mac client data will not migrate automatically. The setup script also runs a health check, which can catch environment issues before you start. For a solo developer, the maintenance burden is on you to track upstream changes, but the MIT license gives you the freedom to fork and maintain your own version if the author stops.

Editorial conclusion

Adopt Vibe-Research if you are an individual investor focused on A-shares, US, or HK equities, you already have a Codex, Claude Code, or WorkBuddy subscription, and you want a local tool that keeps the Agent off until you need it. Do not adopt it if you expect a production-grade, fully supported financial platform, if you need reliable mobile or Mac client support (the Mac client was removed in v1.2.0), or if you cannot accept that the project is essentially a solo developer's work-in-progress. Before adopting, verify that your Node.js build supports TypeScript (run `node -p process.features.typescript` and expect `strip` or `transform`), confirm your Python version is 3.11 or newer, and read the `docs/source-delivery.md` to understand what was removed and how old desktop data is handled. The project's own boundary section likely lists missing features, so check that file before committing time.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. simonlin1212/Vibe-Research on GitHub