AxonX

🧠 What is AxonX?

AxonX is an agent-native harness for quantitative research. Agents develop research plugins, execute experiments, and inspect the same parameters, logs, dependencies and artifacts as researchers.

You define the question; the Agent implements it; AxonX manages execution and evidence. Use CLI, HTTP, MCP or Studio. The reference plugins adapt Microsoft Qlib's Alpha158 baseline with configurable factors and portfolio policies.

Quick start · Plugins · Case study · Documentation · Try Playground

Related MCP server: OpenFinClaw CLI

✨ Why AxonX?

• Develop with Agents: use the AxonX Skill, source tools and live Task schemas.

• Keep traceable experiments: typed inputs/outputs, process identity, logs and versioned artifact references.

• Inspect in Studio: Task control, workspace previews, research charts and strategy comparisons.

📰 Latest Updates

• 0.3.0 released: supports inheritable configuration, unified Task execution, and scheduled Tasks that continue across service restarts.

• Alpha158 experiments: risk factors and rank retention improved Top20 net annualized returns by +1.36 pp and +24.70 pp over the adapted baseline. See results and evidence limits.

• Studio Playground: explore Tasks and charts with simulated data. Try it online.

🚀 Quick start

This checkout is AxonX 0.3.1. Requires Python 3.12+ on macOS or Linux. Studio is an optional, independently released package.

1. Install and start

Install from pip:

pip install 'axonx[studio]'

Or install the backend and Studio from source:

git clone https://github.com/FlowLLM-AI/AxonX.git
cd AxonX
pip install -e ./axonx_studio -e '.[studio]'
npm --prefix axonx_studio ci
npm --prefix axonx_studio run build

The source install uses editable packages. Building Studio requires Node.js 22.13+ (22.x), 24.x or 26+; rebuild after frontend changes.

Then start the service:

export AXONX_SERVICE_TOKEN='replace-with-your-service-token'
axonx app --service.host 127.0.0.1

Defaults: port 1024, workspace .axonx, service/CLI logs logs/. Use example.env for optional settings; CLI startup loads the nearest .env from the launch directory or its parents, preserving existing environment values. Keep this terminal open and use another with the same Python environment and token.

For custom settings, save a YAML file such as axonx.local.yaml:

extends: default
workspace_dir: .axonx
service:
  host: 127.0.0.1

Start it with axonx app --config ./axonx.local.yaml. Custom configs inherit the bundled service, components and Jobs only with extends: default; mappings merge, while lists and scalars replace. Installed plugins can also provide named configs. See configuration.

2. Run Demo and open Studio

axonx get_task_def --task demo
axonx exec --task demo --task-name quickstart --x 2 --y 3
axonx status --task-id 'base#demo#quickstart' --detail full

exec waits and returns business output (result=5) plus the Task exit code. Demo needs no market data or model credentials. Open http://127.0.0.1:1024/ and enter the token in Settings → Local service token.

axonx --help shows offline usage; axonx help queries the running service's Jobs. Execution settings use explicit CLI options → service get_config → built-in defaults. The CLI falls back only when the service connection is unavailable; authentication and service errors are reported. Task-specific parameters come from get_task_def.

Keep the Task ID and metadata started_at. Use different instance names to preserve experiments: same-name reruns replace current records and outputs, retaining persistent/. See Task management.

3. Develop with an Agent

For the reference research plugins, use the source checkout above (or clone the repository if you installed from pip). From the repository root, install into the execution service's Python environment:

axonx plugin install -e ./plugins/qlib_a158
axonx restart_service

Research plugins are installed from source. Install Alpha158 first, then factor or strategy as needed; the two extensions do not depend on each other. Restart persistent services after code changes; reinstall after dependency or entry-point changes. Wait for the service to be ready before querying definitions.

Provide the checkout, file/command tools and AxonX Skill. Install the Skill from main with GitHub CLI (--agent claude-code for Claude Code):

gh skill install FlowLLM-AI/AxonX axonx --agent codex --scope user --pin main

Install AxonX and the research plugins as described above, then choose an access path:

• External Agent: the host manages model credentials. Use CLI or Streamable HTTP MCP at http://127.0.0.1:1024/mcp with Authorization: Bearer <token>. See MCP integration.

• Built-in Agent: set the following model environment, restart the service, and open Studio → Agent. Configure its cwd for the checkout; see Agent configuration.

CLAUDE_CODE_API_KEY=your-model-api-key
CLAUDE_CODE_BASE_URL=https://api.anthropic.com
CLAUDE_CODE_MODEL_NAME=your-model-name

Give the Agent a concrete objective, for example:

Read the AxonX Skill and Alpha158 implementation. Develop a separate plugin to test residual volatility and downside risk. Fix data, training settings, costs and evaluation windows; use only signal-time information. Test the code, run experiments, and report Task IDs, RankIC, net returns, drawdown and limitations. Reserve an independent confirmation window.

Prepare historical data and AXONX_TUSHARE_TOKEN before following the research workflow.

🧩 From Qlib Alpha158 to research plugins

The main chain is ETL → Train → Predict → Backtest, with optional factor analysis from ETL. qlib_a158_research composes these stages; leaf Tasks can reuse compatible upstream artifacts.

Other research methods use the same Task and plugin contracts. The baseline adapts Qlib's data, labels, training and trading assumptions; see differences from original Qlib.

📊 Alpha158 improvement case

This recorded experiment adds two risk features, then applies a rank-retention policy to the factor-model predictions:

Training: [20150101,20230101); evaluation: 20230103–20261008 (909 market dates). Buy/sell fees: 0.05% / 0.15%. The strategy uses a 3-day minimum holding period and a 20% replacement count cap per side; initial construction is exempt.

Evidence limits: no independent confirmation window; base/factor feature_fraction differs (0.9/1.0), so results do not isolate the added factors. All backtests report incomplete_market_data, use same-close fill proxies and include a partial 2026. These results do not establish outperformance over original Qlib.

Full settings, reproduction commands and historical Task provenance.

🛠️ CLI and remote execution

Set the destination token and keep the same target for execution and observation:

export AXONX_TARGET_TOKEN='replace-with-target-token'
axonx exec --task demo --task-name remote-check --x 2 --y 3 --target node-b:1024
axonx status --task-id 'base#demo#remote-check' --detail full --target node-b:1024

Replace the example address. --target uses AXONX_TARGET_TOKEN; default local calls use AXONX_SERVICE_TOKEN. Remote paths belong to the target. Deploy local plugins by build → upload → install location → clean path → restart/verify; see plugin management.

Studio uses backend-configured targets; AXONX_TARGET populates the bundled remote config and does not select a CLI destination by itself. See remote machines. Service restarts stop service-owned manual commands and preserve daemon-owned scheduled Tasks; schedules accept local axonx exec --task NAME commands. See service updates.

📚 Documentation

English documentation · 中文文档

💬 Contributing

Contributions to the framework, plugins, experiments and documentation are welcome. See CONTRIBUTING.md for setup and checks, or GitHub issues for bugs and proposals.

⚖️ License

Apache License 2.0.