Keel Agent SDK

Keel is an agent-native research environment for Hyperliquid systematic trading. The Python package provides one keel CLI and one stdio MCP command. Both surfaces bind to the same outcome-tool registry.

This file is the package README and agent instruction entry point. Keep it short, current, and operational. Do not add command inventories unless they are checked against the outcome registry.

Choosing a Surface

The default surface is the hosted remote MCP. This package is the other way to connect — the keel CLI and the local stdio MCP server (also shipped as the Claude Desktop .mcpb bundle) — for terminals, scripts, CI, and file-based workspaces. The hosted endpoint has no live-write tools at all; this package loads them only on an explicit KEEL_TOOLSETS opt-in (see Live Trading Safety). Running a strategy with real capital happens in the Keel web app.

• Hosted endpoint (default) — https://mcp.usekeel.io/mcp: one endpoint, a 29-tool research/backtest/read surface, nothing to install. Paste the URL into Claude, ChatGPT or any remote-MCP client and sign in or sign up when prompted; Claude Code: claude mcp add --transport http keel https://mcp.usekeel.io/mcp; Codex: codex mcp add keel --url https://mcp.usekeel.io/mcp. The agent builds, tests and reads. When you want to run a strategy on your account, it hands it to the Keel app and you take it from there. Per-client steps: https://usekeel.io/agents

Install

pipx install keel-trade
claude mcp add keel -- keel mcp serve

uv tool install keel-trade also works. Agent hosts launch the MCP command as a stdio child process:

keel mcp serve

First Contact

When an agent starts with Keel:

1. Call keel_account_status.
2. If authenticated is false, call keel_auth_login.
3. Read workflow_routes from keel_account_status before choosing lower-level tools.
4. For strategy creation or substantial edits, load the strategy-creation prompt before composing source.
5. Search components with keel_components_search.
6. Fetch exact component schemas with keel_components_get_many.
7. Compose or validate DSL with keel_strategy_compose.
8. Run evidence with keel_backtest_run.
9. If the run is still active, watch it with keel_backtest_watch.
10. Summarize evidence with keel_backtest_summarize.
11. Share only when the user explicitly asks, via keel_share_create.

Do not invent Keel commands. If unsure, call keel_help, inspect tools/list, or run keel --help.

Authentication

Preferred agent path:

keel_account_status -> keel_auth_login -> retry original tool

keel_auth_login opens the OAuth browser flow, captures the loopback redirect, and stores credentials in ~/.keel/config.yaml. The CLI uses the same state:

keel auth login

Headless environments can use:

keel auth login --key <token>

Live-trading consent is requested explicitly:

keel_auth_login(scope="live")

or:

keel auth login --scope live

Recommended Strategy Workflow

Use prompts for workflow, resources for context, tools for actions, and URLs for human handoff.

strategy-creation prompt
keel_components_search(keyword="momentum")
keel_components_get_many(names=["ROC", "ForecastScaler", "..."])
keel_strategy_compose(source_file="strategy.py", dry_run=true)
keel_strategy_compose(source_file="strategy.py", name="momentum-baseline")
keel_backtest_run(strategy_id="str_...", start_date="2025-01-01")
keel_backtest_watch(backtest_id="bt_...")
keel_backtest_summarize(backtest_id="bt_...")

CLI equivalents:

keel components search momentum --format json
keel components describe-batch ROC ForecastScaler --format json
keel strategy compose --source-file strategy.py --dry-run --format json
keel strategy compose --source-file strategy.py --name momentum-baseline --format json
keel backtest run str_abc123 --start-date 2025-01-01 --format json
keel backtest watch bt_abc123 --format json
keel backtest summarize bt_abc123 --format json

For checked-out local strategy work:

keel project init
keel strategy checkout str_abc123
keel strategy status str_abc123
keel strategy push str_abc123 -m "describe the change"
keel backtest run str_abc123 --auto-push --start-date 2025-01-01
keel strategy log str_abc123
keel strategy restore str_abc123 --ref 3

Backtests run server-side strategy versions. Local edits that are ahead are pushed automatically before the run (write-through default; pass auto_push=false / --no-auto-push to opt out). end_date / --end-date is optional and defaults to today's UTC date.

State Model & Sync (read this once)

Server HEAD is the single source of truth for strategy source. Every runnable action — backtest, deploy, share — resolves against a server commit, never a local file. The local workspace (keel_strategy_checkout) is a working copy: convenient, disposable, always reconcilable.

• Write-through by default. keel_backtest_run and the keel_live_deploy preview push unpushed local edits automatically (generated commit message, or pass push_message) and pin to the pushed commit, so you always run what you actually have. Opt out with auto_push=false — then a locally-ahead strategy raises local_ahead instead of silently testing old server code.
• Pull-through on server-side edits. keel_strategy_compose updates a same-machine checkout in the same operation (workspace_sync in the response). Edits made elsewhere (web editor, another machine, hosted MCP) are detected by hash on the next local tool touch; keel_strategy_status then says exactly one thing to do (keel_strategy_pull).
• Conflicts never resolve silently. A true conflict (local edited AND server moved) stops any push/pull/backtest/deploy with a sync_conflict envelope carrying three-way context (base_hash, local_hash, server_hash, server_last_modified, server_modified_via) and exactly three recovery options: pull_force (take server, lose local), manual merge via keel_strategy_diff, or pinning an explicit commit_id on the blocked action. There is no auto-merge and no force-push recommendation, ever.
• Commits carry surface attribution. keel_strategy_history shows modified_via per commit ("modified via claude.ai, 2h ago") so multi-surface work stays legible.
• Remote/hosted MCP is file-free: no workspace tools, inline source only; web and chat write the server directly.

Current MCP Tools

MCP tools are callable by canonical keel_* names. KEEL_TOOLSETS filters the MCP surface only; the CLI command tree is generated independently. For the exact generated schema/annotation/CLI mapping, see packages/keel-trade/docs/tool-reference.md.

Always loaded:

• keel_auth_login
• keel_auth_logout
• keel_connection_check
• keel_feedback
• keel_help
• keel_account_status

Read-only:

• keel_accounts_list
• keel_audit_list_last
• keel_components_search
• keel_components_get (single known component schema/detail)
• keel_components_get_many (several component schemas before composing)
• keel_library_list
• keel_library_get
• keel_app_link
• keel_strategy_readiness
• keel_plan_usage
• keel_strategy_get
• keel_strategy_search
• keel_strategy_diff
• keel_strategy_history
• keel_strategy_notes_read
• keel_strategy_workspaces

Research and backtest:

• keel_strategy_compose
• keel_strategy_checkout
• keel_strategy_delete
• keel_strategy_discard
• keel_strategy_fork
• keel_strategy_notes_add
• keel_strategy_pull
• keel_strategy_push
• keel_strategy_restore
• keel_strategy_status
• keel_library_fork
• keel_backtest_run
• keel_backtest_watch
• keel_backtest_summarize
• keel_backtest_compare
• keel_backtest_positions (one run's positions, each entry to exit: a summary by default, one page per asset / start–end scope; CLI keel backtest positions, alias keel backtest trades)

Sharing:

• keel_share_create

Live read, loaded by default:

• keel_live_monitor (12 views; view='executions' takes expand_orders and execution_run_id)
• keel_deployments_list
• keel_live_receipt (one EPISODE's sealed receipt — a multi-episode run has one per episode and no single run-level receipt)
• keel_live_quality
• keel_accounts_safety (execution HALT state; operator-gated, and its refusal is not an auth problem)

Live write, loaded only when KEEL_TOOLSETS includes live-write:

• keel_live_deploy
• keel_live_control
• keel_live_update

Default MCP toolsets are always,read-only,backtest,share,live-read. Opt into live write tools only when the user is explicitly working on live deployment or control:

export KEEL_TOOLSETS=read-only,backtest,share,live-read,live-write

KEEL_TOOLSETS=live remains a deprecated compatibility alias for live-read,live-write; new configs should use the explicit split.

MCP Prompts

These prompts are bundled as MCP prompts under the keel-skill tag and are also used as workflow guidance in other Keel agent contexts:

• strategy-creation
• strategy-fork-and-iterate
• backtest-and-analyze
• overfit-check
• deploy-and-monitor
• portfolio-review
• component-discovery
• recover-from-error

Use strategy-creation before a first keel_strategy_compose call in a session. Use backtest-and-analyze before interpreting backtest results. Use recover-from-error when a tool repeatedly fails.

MCP Resources

Use resources for read-only context that should not be recomputed through tool calls:

• keel://components/catalog
• keel://components/{name}/schema
• keel://strategy/{strategy_id}/source
• keel://strategy/{strategy_id}/lockfile
• keel://backtest/{backtest_id}/results
• keel://backtest/latest
• keel://strategy/{strategy_id}/backtest/latest
• keel://dsl/reference/{topic}
• keel://knowledge/{section}
• keel://context/strategy/{strategy_id}

Local server only (stdio MCP / .mcpb; not on the hosted endpoint, where the server's filesystem is not yours):

• keel://context/user — ~/.keel/context.md
• keel://context/project — keel.md or the ## Keel block of CLAUDE.md in the server's working directory

Live Trading Safety

Live trading is opt-in and should be treated as a release gate, not a normal research action. Going live is a human action in the Keel web app.

Required posture:

1. Do not deploy unless the user explicitly asks.
2. Load deploy-and-monitor.
3. Call keel_live_deploy(strategy_id=...). It places no orders and picks no account: it returns code=handoff_required with an action_url into the web deploy flow, where the human selects or connects the account, reviews the server-computed sizing, accepts the risk, and goes live. Relay the action_url in prose; do not try to deploy in the terminal.
4. To check on the handoff, call it again with intent_token (the handoff's resume.token) and preview=true: a pure status poll returning pending, completed (with the deployment_id) or expired.
5. Monitor immediately with keel_live_monitor.

keel_live_monitor returns a freshness block. Read it before summarizing live data: view="positions" is an on-demand Hyperliquid snapshot, while portfolio/history views come from Keel backend records and can lag the live dashboard stream.

CLI arming is local-machine authorization:

keel arm live set --account acct_...

Local arming is not a sizing or risk cap. It means this machine is allowed to perform live actions for that account until expiry.

keel_live_control (pause, resume, stop, trigger) requires local arming. The preview=true -> confirmation_token -> preview=false sequence belongs only to the direct=true operator escape hatch, which is inert unless the operator sets KEEL_ALLOW_DIRECT_DEPLOY and is refused on any hosted surface; that path also needs live OAuth scope and local arming. It is not the way to go live.

CLI Contract

All outcome commands support:

--format json|table|tsv|human

Agents should prefer --format json. Human progress should not be parsed from stdout; parse stable JSON fields such as hero_url, resource_uri, share_url, summary_metrics, backtest_id, and strategy_id.

Agent mode is enabled by KEEL_AGENT_MODE=true, common agent environment variables, or non-TTY stdout. KEEL_AGENT_MODE=false forces human defaults and is the script/CI opt-out.

Destructive CLI commands require --yes in agent mode. Agents should add it only after the user has confirmed the action. If omitted, the CLI returns a structured cli_confirmation_required error explaining what to ask the user.

Current CLI Shape

Outcome-backed CLI commands use the same nouns as MCP tools:

keel status
keel doctor
keel help <topic>
keel components search <keyword>
keel components compose-help <name>
keel components describe-batch <name1> <name2>
keel strategy search
keel strategy get <strategy_id>
keel strategy compose
keel strategy checkout <strategy_id>
keel strategy status <strategy_id>
keel strategy push <strategy_id> -m "message"
keel strategy pull <strategy_id>
keel strategy log <strategy_id>
keel strategy restore <strategy_id> --ref <ref>
keel backtest run <strategy_id> --start-date YYYY-MM-DD [--end-date YYYY-MM-DD]
keel backtest watch <backtest_id>
keel backtest summarize <backtest_id>
keel share create <target_id> --yes
keel accounts list
keel live deploy <strategy_id>
keel live deploy <strategy_id> --intent-token <token>
keel live monitor <deployment_id>
keel live control <deployment_id> --action pause|resume|stop|trigger --yes
keel audit list-last

CLI-only operational commands include:

keel auth login
keel auth status
keel auth whoami
keel auth logout
keel mcp serve
keel project init
keel context show --layer user|project
keel arm live set --account <account_id>
keel arm status
keel arm disarm

What Not To Do

• Do not use the removed meta-tool pattern from older docs. Current MCP tools are direct keel_* tools.
• Do not use old commands that are absent from keel --help and the current CLI shape above.
• Do not claim backtest results without a keel_backtest_run result or keel_backtest_summarize evidence.
• Do not create public share links unless the user asks.
• Do not live deploy, pause, resume, stop, or trigger without explicit user confirmation.