virattt/ai-hedge-fund: an LLM investor team you run from the terminal

What virattt/ai-hedge-fund actually is

The README opens with a plain statement: this is a proof of concept for an AI-powered hedge fund, built to explore whether AI can make trading decisions, and it is for educational purposes only. The same paragraph repeats that it is not intended for real trading or investment. A second note is easy to miss and matters more than the disclaimer: the system does not actually make any trades. So the output of a run is a decision record, not an order.

The intended user is someone who wants to inspect the decision layer rather than the plumbing. The pyproject.toml description calls it "an LLM-powered hedge fund: LLM investor agents and quant alpha models you can build, backtest, and run from your terminal." That is the scope. You get a terminal app, a set of agents, a backtester, and a saved configuration called a mandate. You do not get a broker connection, an order router, or a risk system that touches a live account.

The project is being rebuilt. The README points at VISION.md and ROADMAP.md and describes the direction as a persistent, always-on fund treated as a first-class entity you can backtest, paper-trade, and opt-in run live, with the investor agents reimagined as pluggable, backtestable alpha models. Read that as a warning about interface stability, not as a feature list. Anything you build against the current alpha model surface may need rework.

The mandate, the tickers flag, and how a run is wired

The central design decision is the separation between a desk and its instruments. The README states that a mandate is the desk (strategies, staff, risk, capital, cadence) and never names tickers, while --tickers says what to point it at for that run. That is a clean boundary. It means the same mandate can be evaluated on different universes without editing the file, which is what makes the backtest path meaningful.

Funds you build interactively are saved as mandate files in ~/.hedge-fund/mandates/. The non-interactive path takes one of those files and runs a single fund cycle. The full cycle record prints to stdout as JSON, and a short human summary goes to stderr. That split is deliberate and useful: you can pipe stdout into a file or a parser and still read the summary in your terminal.

Data comes from two external sources. A Financial Datasets API key supplies prices, fundamentals, and earnings. One LLM API key supplies the LLM-powered alpha models. The supported providers listed in the README are Anthropic, OpenAI, DeepSeek, Google, xAI, and Kimi, and the .env.example file lists the matching variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, GOOGLE_API_KEY, XAI_API_KEY, and MOONSHOT_API_KEY. The dependency list in pyproject.toml mirrors those six with langchain-anthropic, langchain-openai, langchain-deepseek, langchain-google-genai, and langchain-xai packages, plus pandas, numpy, scipy, matplotlib, textual, and rich.

The backtest path reuses the mandate rather than a separate configuration. The README says the mandate is backtested over history at its rebalance cadence, which means cadence lives in the mandate and the backtester reads it from there. There is no documented way to override cadence for a single backtest run.

Installing aihf and running your first cycle

The README gives three install routes and treats them as equivalent: pipx install aihf, uv tool install aihf, or pip install aihf into an environment of your choice. The package name is aihf, which is also the console script declared in pyproject.toml as aihf = "hedge_fund.run:main". Python is pinned to ^3.11.

pipx install aihf

After that, the command aihf works from any directory. Run it with no arguments and you get the interactive terminal app, which is where you build a fund: pick stocks, strategies, and a rebalance cadence, or backtest a saved fund and watch its equity curve draw against its benchmark.

aihf

Keys are not configured up front. The README states that the app asks for keys the first time it needs them and saves them to ~/.hedge-fund/.env. The .env.example file confirms this and adds one detail worth knowing: keys exported in your shell always win over the saved file. If you prefer to set them yourself, copy .env.example and fill in a Financial Datasets key plus one LLM key.

FINANCIAL_DATASETS_API_KEY=your-financial-datasets-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key

For a non-interactive run, point the CLI at a saved mandate and supply the tickers for that run. The cycle record prints as JSON on stdout and a summary on stderr.

aihf ~/.hedge-fund/mandates/example.yaml --tickers AAPL,MSFT

To evaluate the same mandate over history, add --backtest. The README gives this exact form.

aihf ~/.hedge-fund/mandates/example.yaml --tickers AAPL,MSFT --backtest

If you want to work from source instead, the development section is short: clone the repository, run poetry install, then poetry run aihf, with poetry run pytest hedge_fund for the test suite.

Where the design gets thin

The README does not document rollback, and there is no stated way to resume or replay a partially completed cycle. The JSON cycle record on stdout is the only artifact the README describes, so if a run fails midway you are reading that output rather than a checkpoint.

The LLM dependency is a real constraint, not a footnote. Every LLM-powered alpha model needs a provider key, and the output of a run depends on which provider and model you point it at. Nothing in the README describes a deterministic mode, a cached response layer, or a way to pin model versions. Two runs of the same mandate over the same tickers can differ because the model behind the agent differs. That is fine for studying agent behaviour and poor for reproducing a specific result.

The backtester inherits the same problem. Backtesting an LLM-driven strategy is not the same exercise as backtesting a rule-based one, because the historical decision path is generated at run time. The README describes the backtest mechanic (rebalance cadence, equity curve against a benchmark) but says nothing about how the LLM component is handled across historical dates. Treat backtest output as an illustration of the harness, not as evidence about returns.

Finally, the README states plainly that the system does not actually make any trades. If your goal is automated execution, this is the wrong tool and no amount of configuration changes that.

How this differs from a rules-based backtesting framework

A conventional backtesting library such as backtrader or vectorbt takes a strategy you write as code and runs it over a price series. The decision logic is fixed and deterministic; the library's job is to feed bars, apply fills, and report statistics. Reproducing a result is trivial because the inputs and the rules are the only variables.

virattt/ai-hedge-fund inverts that. The strategy is partly a set of LLM personas, so the decision logic is not fixed code but a model call with a prompt, and the mandate file describes the desk rather than the rules. The framework's job is closer to orchestration: gather fundamentals and prices from Financial Datasets, hand them to agents, collect the resulting decisions, and record the cycle as JSON. The backtest exists to show the shape of a strategy's behaviour at a given rebalance cadence, not to certify a return series.

That difference has a practical consequence. With backtrader you debug a strategy by reading your own code. Here you debug by reading the cycle record and inspecting what the agents were given. The README's stdout/stderr split exists for exactly that reason, and it is the part of the design that holds up best.

Maintenance, packaging, and the licence

The repository is not archived, and the last push was on 2026-08-07, which is recent. The release history shows three versions in the weeks before that push: ai-hedge-fund 2.0.2 on 2026-07-30, hedge-fund 2.1.0 on 2026-08-04, and aihf 2.2.0 on 2026-08-07. The distribution name changed across those releases, which matches the pyproject.toml name of aihf at version 2.2.0. If you pinned an older package name, expect to reinstall under the new one.

Upgrade cost is dominated by the rebuild described in VISION.md and ROADMAP.md rather than by dependency churn. The README frames the investor agents as being reimagined as pluggable, backtestable alpha models. Any custom agent or mandate you write against the current surface is the thing most likely to need rework, so keep your own code thin and let the mandate file carry configuration.

The licence is MIT, declared in pyproject.toml and in the LICENSE file. MIT is permissive: it allows use, modification, and redistribution with the copyright notice and permission notice retained. It also means the author provides the software without warranty, which lines up with the README's own liability disclaimer. That is a description of what the licence text says, not legal advice; if you plan to redistribute a modified version, read the LICENSE file yourself.

Editorial conclusion

Adopt it if you want to study how LLM agents and quant signals can be assembled into a mandate you can backtest, and if you are comfortable with a proof of concept that the README says does not make trades. Do not adopt it as an execution system for real capital, and do not expect the mandate format or the alpha model interface to be stable while the rebuild described in VISION.md and ROADMAP.md is in progress. Before you commit time, verify three things: that you can obtain a Financial Datasets API key, that one of the six supported LLM providers is acceptable to you, and that the current aihf 2.2.0 CLI still matches the mandate and backtest flow shown in the README, since the package was renamed from hedge-fund to aihf within the last month of releases.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes