# Keel Agent Instructions

Keel is an agent-native research environment for Hyperliquid systematic trading.
Use Keel through the `keel-trade` package, which provides one `keel` CLI and one
stdio MCP command.

Provenance:
- PyPI: `keel-trade` (https://pypi.org/project/keel-trade/)
- Public source: https://github.com/keel-trade/keel-trade (MIT)
- Official MCP Registry: `io.github.keel-trade/keel-trade`
- Product page: https://usekeel.io/keel-mcp

## Install

Two install paths. Use whichever matches the user's setup.

### Claude Desktop — one-click `.mcpb` bundle

Download the cross-platform bundle and drag it onto Claude Desktop:

```
https://github.com/keel-trade/keel-trade/releases/latest/download/keel-trade-latest.mcpb
```

Single bundle for macOS, Windows, and Linux. Requires system Python 3.11+;
first launch pip-installs runtime deps to `~/.keel/mcpb-lib/py3.X/` (~10-30s),
subsequent launches are instant.

### Terminal — pipx / uv (Claude Code, Codex, Cursor, Windsurf, …)

```bash
pipx install keel-trade
```

`uv tool install keel-trade` also works.

Then register `keel mcp serve` with the user's MCP host. Use the host's native
setup; do not assume Claude Code unless you are running inside Claude Code.

Claude Code:

```bash
claude mcp add keel -- keel mcp serve
```

Codex:

```bash
codex mcp add keel -- keel mcp serve
```

Generic MCP clients, Cursor, and Windsurf:

```text
command: keel
args: ["mcp", "serve"]
```

Agent hosts launch `keel mcp serve` as a child process and communicate over
stdin/stdout. Users do not need to run a daemon, open a port, or start a
separate local service.

## First Workflow

1. Call `keel_status`.
2. If unauthenticated, call `keel_auth_login`.
3. For strategy creation, load the `strategy-creation` MCP prompt first.
4. Search components with `keel_components_search`.
5. Batch-fetch exact schemas with `keel_components_detail_batch`.
6. Compose and validate with `keel_strategy_compose`.
7. Run evidence with `keel_backtest_run`.
8. If the run is still active, poll with `keel_backtest_watch`.
9. Summarize with `keel_backtest_summarize`.
10. Create a public link only when requested, via `keel_share_create`.

Current MCP tools are direct `keel_*` tools. Do not invent wrapper or meta-tool
names; use the active `tools/list` schemas.

## Proactive Defaults

Many tools accept zero or minimal arguments — just run them. Do not ask the
user for inputs that have sensible defaults.

- `keel_backtest_run(strategy_id=...)` — `start_date` defaults to 2024-08-15
  (earliest cached HL data), `end_date` to today's UTC date. Mention the dates
  used in the reply so the user can narrow if they want.
- `keel_live_monitor()` — called bare, returns the portfolio summary across
  all live deployments. Use this for "how are my deployments doing?".
- `keel_help()` — called bare, returns the list of bundled knowledge topics.
  Use this when the user asks a general "how does X work?" question.
- `keel_strategy_search()`, `keel_accounts_list()`, `keel_audit_list_last()`
  — sensible default limits, just call them.

After a successful `keel_backtest_run`, call `keel_backtest_summarize` with the
returned `backtest_id` automatically to enrich the reply. Do not ask the user
"do you want the full metrics?" first — they almost always do.

## Current MCP Tool Names

Always loaded:

- `keel_status`
- `keel_auth_login`
- `keel_auth_logout`
- `keel_doctor`
- `keel_help`

Read-only and research:

- `keel_components_search`
- `keel_components_compose_help` (single known component schema/detail)
- `keel_components_detail_batch` (several component schemas before composing)
- `keel_strategy_search`
- `keel_strategy_get`
- `keel_strategy_compose`
- `keel_strategy_checkout`
- `keel_strategy_status`
- `keel_strategy_push`
- `keel_strategy_pull`
- `keel_strategy_log`
- `keel_strategy_diff`
- `keel_strategy_fork`
- `keel_strategy_restore`
- `keel_strategy_discard`
- `keel_strategy_delete`
- `keel_strategy_memory_read`
- `keel_strategy_memory_write`
- `keel_strategy_workspaces`
- `keel_backtest_run`
- `keel_backtest_watch`
- `keel_backtest_summarize`
- `keel_accounts_list`
- `keel_share_create`
- `keel_audit_list_last`

Live read is included by default:

- `keel_live_monitor`

Live write is opt-in with
`KEEL_TOOLSETS=always,read-only,backtest,share,live-read,live-write`:

- `keel_live_deploy`
- `keel_live_control`

## MCP Prompts

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

## Resources

- `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/user`
- `keel://context/project`
- `keel://context/strategy/{strategy_id}`

## CLI Equivalents

```bash
keel status --format json
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 --format json
keel backtest watch <run_id> --format json
keel backtest summarize <run_id> --format json
```

If a command is not shown by `keel --help`, do not call it. For current
workflows, prefer compose, watch, summarize, monitor, and control commands shown
above.

`keel backtest run` has sensible defaults: `--start-date` defaults to
2024-08-15 (earliest cached Hyperliquid data) and `--end-date` to today's UTC
date. Just run with the strategy id and report the dates used in the reply.

## Live Safety

Do not deploy unless the user explicitly asks. Use `keel_live_deploy` with
`preview=true` first, show the preview, ask for confirmation, then execute with
`preview=false` and the returned `confirmation_token` (10-minute TTL).

Actual deploy has three prerequisites the agent cannot bypass:

1. **OAuth `live` scope** — call `keel_auth_login(scope='live')` to re-auth
   with the live checkbox pre-selected. The agent can initiate this.
2. **HL account authorized** — sign an EIP-712 wallet challenge at
   `https://app.usekeel.io/accounts`. **Web-only; the agent cannot do this.**
   If `keel_accounts_list()` returns no accounts, tell the user to open the
   accounts page in their browser to connect one.
3. **Local arming** — run `keel arm live set --account <account_id>` in the
   user's terminal. **The agent cannot do this for them** (deliberate second
   lock against agent-driven catastrophe). If `keel_live_deploy` errors with
   `live_trading_disarmed`, surface the exact command to the user and wait.

Local arming is not a sizing or risk cap. It means this machine may perform
live actions for that account until expiry (7-day default TTL).

`keel_live_monitor` includes `freshness` metadata. Use it to distinguish
on-demand Hyperliquid position snapshots from backend-recorded portfolio,
trade, order, execution, funding, stats, equity, and P&L views.