Blave Agent
Turn trading ideas into tested strategies and live deterministic execution with Claude Code or Codex.
- Source repo
- Blave-TW/blave-agent
- Stars
- ★ 46
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 87/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free tier plus a paid hosted plan
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A macOS-based solo quant who wants Claude Code or Codex to turn a natural-language single-asset idea into code and a backtest.
- Not a fit if
- Teams needing the desktop app on Linux or Windows
- Traders requiring desktop orders to continue after the app quits
- Users needing desktop auto-trading for portfolio strategies
- Source review
- 87/100 · Good
What does this agent do, and when should you use it?
Blave Agent is a macOS quant workspace whose Electron desktop shell lives in `shell/`. It connects to a user's Claude Code or Codex installation, or to usage-billed Blave AI, and lets the agent research an idea, write strategy code, run backtests, and prepare it for deployment. The shared `lib/` layer covers data access, backtesting, Monte Carlo permutation testing, parameter scans, rolling walk-forward analysis, reports, charts, and exchange account and order helpers. Live execution keeps the LLM out of the order loop: scheduled deterministic code produces targets and `manager/reconciler.py` moves the account toward them, while `state/HALT` blocks new exposure. Users can run it locally through the macOS app or pay for a dedicated cloud machine accessed through the web workspace, Telegram, or SSH. The local software is free, but users may still need their own AI subscription, data access, and trading accounts, and its statistical checks do not guarantee future returns.
After a user describes an idea, the workspace classifies it as Type A, B, or C. Type A covers one fixed symbol and interval with a long, short, or flat position; Type C covers scheduled rebalancing of a multi-symbol weight vector; both require backtests. Screeners, grids, arbitrage, alerts, and one-off execution fall under Type B and do not require a backtest. The agent writes strategy files under strategies/ and runs the backtest chain through components such as lib/runner.py; Type A runs an MCPT through lib/validation.py by default, lib/param_scan.py searches for robust parameter plateaus, lib/walk_forward.py measures out-of-sample behavior, and lib/quality_check.py flags a zero fee. Versioned Type A and C strategies are marked “Live · file changed” when live code no longer matches the tested version, although the flag does not stop execution. For live runs, scheduled deterministic strategy code feeds target positions to manager/reconciler.py; state/HALT prevents new exposure while allowing closes and stops. Every order attempt is written to state/audit.jsonl, and the system queries the exchange before reporting that an order was placed. The desktop supports tested order libraries for Binance, OKX, BingX, Gate.io, and Bybit, plus keyless paper trading through lib/account_paper.py and lib/order_paper.py.
- A macOS-based solo quant who wants Claude Code or Codex to turn a natural-language single-asset idea into code and a backtest.
- A research team evaluating whether apparent performance survives MCPT, parameter-plateau analysis, and rolling out-of-sample tests.
- A crypto trader who wants to paper trade before connecting a Binance, BingX, OKX, Gate.io, or Bybit account.
- A Taiwan-equity researcher using free daily bars sourced directly from TWSE and TPEx in the desktop app.
- A user who needs strategies to continue while their computer is off and is willing to use Blave's paid dedicated cloud machine.
- A developer testing scheduled multi-asset rebalancing, while accepting that Type C portfolios cannot yet be auto-traded from the desktop app.
How do you install or deploy this agent?
Running from source requires macOS 13 or later, Node.js 22.12 or later with npm, and python3 on PATH. Install and sign in to Claude Code or Codex, or have a Blave account available. Run:
git clone https://github.com/Blave-TW/blave-agent.git
cd blave-agent/shell
npm install
npm startOn first launch, select your own Claude Code/Codex installation or Blave AI. Source installs use the system python3 to create a virtual environment; the packaged app bundles Python 3.12. A universal Apple Silicon and Intel macOS build is also available from GitHub Releases. To force the English interface, run:
BLAVE_LANG=en npm startHow do you use this agent?
Choose the agent provider during first launch. Using your own Claude Code or Codex requires no Blave account; the desktop app launches the CLI and leaves its credentials under that product's control. Blave AI instead requires a Blave login and is billed by usage. Enter a concrete strategy request such as:
Backtest BTCUSDT on the 4h chart: long when the 20-period SMA crosses above the 60-period SMA, flat when it crosses back below. Use a 0.05% fee per side.For a portfolio workflow, try:
Build a portfolio of BTC, ETH and SOL with equal weights, rebalanced weekly, and backtest it.For live trading, connect a supported venue through Auto trading › Connect an exchange in the desktop app; do not paste a key into chat. Grant read and trade permissions only, never withdrawal permission. Funding and resuming trading must be performed by the user through the Auto trading page. The built-in paper venue requires no keys. Desktop orders are sent only while Blave is running, and reopening the application leaves trading paused until the user presses Start trading.
What are this agent's strengths and limitations?
- Type A backtests run an MCPT and record a p-value by default, with parameter-plateau scanning and rolling walk-forward analysis available alongside it.
- Live schedules execute deterministic code without an LLM in the order loop, and
state/HALTblocks new exposure at the order-library level. - The workspace detects when versioned live strategy code differs from the version that was backtested.
- It includes tested order libraries for five crypto exchanges, a keyless paper venue, and templates for adding other brokers.
- The local path supports either Claude Code or Codex, while Apache-2.0 permits commercial use, modification, and redistribution.
- The desktop application requires macOS 13 or later; the Capital Futures integration is separately limited to a Windows workspace.
- Desktop orders stop when the application quits, and trading must be manually restarted after reopening it.
- Type C portfolio strategies cannot currently be auto-traded from the desktop app.
- Free local data is limited; Blave indicators, Taiwan intraday and flow data, futures, and the macro calendar require a Blave account with data access.
- Always-on cloud machines, Blave market data, and the Blave LLM proxy are paid services outside this repository.
How does this agent compare with similar options?
With a user's own Claude Code or Codex, the desktop app only launches the CLI, requires no Blave account, and adds no Blave AI charge; the user remains responsible for their existing AI subscription or service costs. Blave AI is the built-in alternative and requires a Blave account with usage-based billing. Local desktop operation is free and keeps workspace credentials on the user's machine, but orders run only while the app is open. The paid cloud-machine option runs continuously and can be reached through the web workspace, Telegram, or SSH.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Blave Agent This agent | 87 · Good | Desktop appFreemium | ★ 46 | today | Python | Codex · Claude Code |
| Lumibot Trading Framework | 57 · Major gaps | Library / SDKFree + model costs | ★ 2.1k | 1d ago | Python | Codex · Claude Code |
| Vibe-Trading | 64 · Some gaps | CLIFree + model costs | ★ 34k | today | Python | OpenAI API · Claude API |
| PRISM-INSIGHT | 49 · Major gaps | CLIFree + model costs | ★ 767 | 1d ago | Python | ChatGPT · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence shows read-and-trade-only key guidance, withdrawal-enabled-key rejection where venue APIs expose the flag, and explicit user control over funding, resuming trading, and ambiguous account-identity decisions. The kill switch, audit log, restart pause, order read-back, update backups, and atomic replacement provide substantial control over external effects and recovery. Storage locations and data sources are disclosed, while LICENSE and NOTICE establish attribution. Deductions apply because the agent can read plaintext workspace .env files, cloud use permits secrets to be pasted into chat, and Gate.io cannot expose the withdrawal flag. Dependency controls include lockfile use, download hashes, read-only workflow permissions, and release gates, but the supplied evidence does not establish exact pinning or ongoing vulnerability review for every Python and npm dependency. No red-line behavior is evidenced.
The README, offline contract tests, and release workflow are broadly consistent about account-identity safeguards, fail-to-HALT behavior, data adapters, version checks, and artifact verification. Tests require missing IDs, endpoint errors, and malformed states to fail visibly, while workflow failures include actionable messages. Deductions apply because this static review has test source but no execution results, and the core implementations and complete dependency manifests are not supplied. Availability also depends on exchanges, public data endpoints, system Python, AI CLIs, and optional paid Blave services that the repository cannot itself guarantee.
The material clearly separates fixed-symbol, portfolio, and miscellaneous tasks, specifies which require backtests, and documents boundaries for desktop, source, cloud, paper trading, and multiple venues. Classification and safety triggers are precise, including account changes, resume behavior, HALT conditions, and unsupported intervals. Deductions apply because the principal desktop path requires macOS 13+, the Capital integration is Windows-workspace-only, desktop portfolio auto-trading is unavailable, and other broker integrations rely on explicitly untested templates.
The README provides quick-start instructions, a repository map, reading order, examples, test commands, contribution guidance, safety limits, release procedures, and a detailed update contract. The full Apache-2.0 license, trademark boundary, date-based workspace version, runtime changelog, and desktop semantic version are identified. Known limitations are unusually explicit. Deductions apply because legacy openclaw filenames, API paths, and hostnames weaken naming stability. Maintenance is connected to the copyright holder, repository-owner approvals, issues/PRs, and release processes, but the publisher is registry-unverified and no named individual maintainer or support commitment is supplied.
Outputs are designed to be directly usable strategies and reports with p-values, parameter plateaus, walk-forward results, charts, live-code drift indicators, and audit records. Compared with a generic coding agent, trading-type contracts, overfitting brakes, deterministic scheduled execution, and account safeguards provide clear marginal value. Deductions apply because practical use may still require a Claude Code or Codex subscription, paid Blave data or cloud service, exchange accounts, and nontrivial setup. Live trading can also impose losses far beyond the software cost, so cost-benefit remains scenario-dependent.
Major claims usually point to named files, modules, tests, version records, or workflow stages. The text distinguishes real-account-tested venues from untested templates, historical backtests from future performance, and repository code from paid services. Supplied tests partially corroborate account-identity and Binance-data behavior, while the workflow corroborates release controls. Deductions apply because most claims about backtests, order handling, key rejection, and live-code consistency remain README claims in the supplied record; the relevant core implementations, test outputs, CI results, and independent sources are absent, limiting cross-source corroboration.
- Before live use, create a dedicated API key with read and trade permissions only, no withdrawal permission, and preferably an IP allowlist; Gate.io permissions require manual inspection.
- Do not paste credentials into chat. Rotate any key that was pasted, and protect the workspace .env, chat history, and state directory.
- Begin with paper trading or an isolated low-value account, and manually verify HALT, restart-pausing, account-change confirmation, and close-position paths.
- Do not treat README statements about real-account verification or the presence of test source as reproduced results. Run the relevant tests at the pinned revision and inspect the core order implementations.
- The Windows production workflow currently refuses installers lacking a valid SignPath signature; test-track artifacts may explicitly be unsigned and should not be distributed as trusted production updates.
FAQ
Is local use free?
Where are exchange keys stored, and which permissions are required?
~/Blave/workspace/.env on the Mac. A cloud workspace stores them on the user's dedicated machine, while keys bound through the web page are encrypted by Blave. Keys should have read and trade permissions only, never withdrawal; Gate.io does not expose the withdrawal flag, so users must verify it themselves.Can the agent fund an account or resume trading?
Do the validation tools guarantee profitable live results?
Can it connect to an exchange or broker not listed?
lib/account_TEMPLATE.py and lib/order_TEMPLATE.py, but Blave has not tested those custom integrations, so the adopter must validate them.