# APE

**APE is an assistant that does multi-step jobs for you** — research, triage, validation — with budgets, receipts, and guardrails built in. Technically, it's an agent that lives inside the Model Context Protocol: instead of a host model chaining thin tools one call at a time, you invoke one tool (`ape_agent_run`) and an entire reasoning loop runs inside the server.

## Start here (5 minutes, no experience needed)

**What you need:**
- **Node.js 22.5 or newer** (free download from nodejs.org — pick the LTS version).
  - *On Windows:* if `npm i -g` gives a permission error, either run the terminal **as Administrator**, or avoid the issue entirely by installing Node via a version manager (`winget install fnm`, then `fnm install --lts`). Do not change permissions on system folders.
- **A way to talk to it** — an AI app you already use (Claude, OpenCode, Codex, Cursor, VS Code) *or* just a web browser.
- **Model access** — usually automatic: APE borrows the AI access your host app already has, so there's typically no new API key. Standalone use may need one key (Anthropic or OpenAI) — APE tells you if so.

**Install, then start the visual tour:**

```bash
npm i -g ape-mcp
ape               # ASCII banner → guided onboarding → menu (needs a terminal)
```

> npm note (2026-10-25): `npm i -g ape-mcp` currently installs 1.1.2, the latest published release. Version 1.2.0 is tagged in this repo, but its npm publish is still waiting on owner approval, so it is not on npm yet. For 1.2.0, install from source (see [Install](docs/install.md)) until the publish lands.

Prefer scripted commands? `ape-mcp doctor`, `ape-mcp run …`, and `ape-mcp --http` work as before — `ape` with arguments behaves exactly like `ape-mcp`. `ape-mcp tui` opens the same terminal UI as `ape` from inside scripts and menus.


**Run your first job.** Pick a *profile* (which specialist) and write one *objective* sentence:

| Profile | What it does |
|---|---|
| `repo-triage` | Sorts out software issues, recalls past decisions, proposes a plan |
| `research-verify` | Researches a question on the web, double-checks before answering |
| `persona-validate` | Tests an experience the way different users would |

More specialists ship bundled (`deep-researcher`, `code-reviewer`, `triage-lead`, `planner`, `supervisor`) — see "Bundled specialists" in [Profiles](docs/profiles.md), and multi-agent compositions in [Patterns](docs/patterns.md).

Example objective: *"Verify: Wikipedia is free."* You'll get back a **run ID** (like `run-a1b2c3d4`) — your tracking number for progress and results.

**Read the result.** Every job returns three things:

- **Outcome** — what the agent concluded, in words.
- **Outcome status** — how it ended: `success`, `unverified` (answered but couldn't fully check itself — treat as a draft), `exhausted` (ran out of budget — split the goal and retry in parts), `failed`, or `cancelled`. Don't read "finished" as "succeeded" — this label is the truth.
- **Cost and steps** — what it spent, so there are never surprise bills. The full step-by-step ledger is saved and inspectable.

**Safety nets you get automatically:** per-job spending/step/time budgets it cannot exceed; destructive actions denied by default (with caps and confirmations where allowed); verify-before-claim on the research profiles; everything recorded to a local ledger (`.ape/` folder on your machine).

**If something goes wrong:**

| Symptom | What to do |
|---|---|
| `doctor` shows a FAIL | Fix that item first — most often Node version or a missing model key |
| "no provider" error | Open APE from inside your host app, or set one model key |
| Job ends `exhausted` | Split the goal into smaller objectives and run them separately |
| Job ends `unverified` | Treat the answer as a draft; re-run with a narrower, checkable question |
| Console won't open | Make sure no other copy is already running, then retry |

**Terms worth learning:** *profile* (which specialist + its rules — a settings file you can tweak later), *run / run ID* (one execution + its tracking number), *objective* (your goal sentence — specific and single-goal works best), *ledger* (saved history of everything, with costs).

*Suggested first session: `doctor`, open the console, give `research-verify` a small factual question. Watch it work, then read its outcome, status, and cost — that one loop teaches the whole system.*

## For integrators & technical users

**The idea.** Standard MCP servers are stateless executors; all planning lives in the host's model. APE inverts this with the Tool Orchestrator pattern taken to its conclusion: the tool handler runs its own reasoning loop with its own model calls, memory, and database. The host sees a function call that returns a result — what happened inside is APE's implementation. The agent is defined by a profile (YAML you edit): model, tools, budget, destructive policy. You reshape the agent by editing a file, not forking code.

```text
HOST (Claude, Codex, OpenCode, Cursor, Hermes, VSCode)
        |  one config entry
        v
APE  -> agent runtime ->  Genesis, EVE, ADAM, Skein
        |                  connectors (user-authored, egress-allowlisted)
        v
      .ape/  runs.db, memory, ledger, trace
```

Point your MCP host at `bin/ape-mcp.js` (stdio) or `ape-mcp --http 8787`. Manifests ship in-repo (`.claude-plugin/`, `.opencode/plugin.json`, `mcpServers.json`, `.codex/skills/ape/`). For a remotely reachable server (`https://your-domain.com/mcp`, bearer auth, Caddy TLS), see [Remote MCP endpoint](docs/remote.md).

**Use:**

```bash
ape-mcp run ape_status '{}'
ape-mcp run ape_agent_profiles '{}'
ape-mcp run ape_connector_call '{"connector":"web","operation":"search","input":{"query":"MCP"}}'
ape-mcp run ape_agent_run '{"profile":"research-verify","objective":"Verify: Wikipedia is free."}'
```

Set a model key first (`APE_ANTHROPIC_API_KEY` or `APE_OPENAI_API_KEY`); `ape_agent_status` polls the run and shows every step and its cost. No key needed in most setups: `provider: auto` detects the host platform's active provider (OpenCode, Claude Code, or Codex session state, env, or a local model) and reuses its credentials; `ape_status` shows what was detected.

**Environment.** `APE_DATA_DIR` overrides the data directory (default `<cwd>/.ape`). `APE_PYTHON` points at the Python 3 interpreter used by the vendored Skein task-graph engine (`ape_orchestrate`); when unset, APE probes `python` then `python3` on PATH, so Linux/macOS systems without a bare `python` alias work out of the box.

**Why this exists:** (1) host-chained tool calls are brittle and expensive to orchestrate — APE moves the loop server-side where each step is budgeted, traced, and recoverable; (2) agents need memory, audit, and budgets to be trustworthy — per-step ledger, governed mutations with confirmation gates, destructive-deny by default; (3) third-party access without per-service wrappers — declarative connectors (YAML endpoints, host allowlists, env-referenced auth; nothing outside the allowlist is contactable).

### Free model tiers: `freepool` + cost routing

No paid key? Export any free-tier keys you have (`GROQ_API_KEY`, `CEREBRAS_API_KEY`, `GEMINI_API_KEY`, `MISTRAL_API_KEY`, `OPENROUTER_API_KEY`, `NVIDIA_API_KEY`, `CLOUDFLARE_API_TOKEN`+`CLOUDFLARE_ACCOUNT_ID`, `HF_TOKEN`, `OPENCODE_API_KEY`; comma-separate several keys) and APE stacks them as one provider, `freepool`: it picks a healthy model under its rate limits, fails over on 429/5xx/timeout with cooldowns, learns real ceilings from headers, and records which upstream served in the receipt. With `provider: auto`, **cost routing** is opt-in (`APE_COST_ROUTING=1` or `policy.cost_routing: true`): local model → free tiers → your paid provider only when the task needs it and the budget allows. Having a free-tier key set does not change routing by itself. Strategies `auto | fast | smart | cost`; `ape_freepool_status` / `ape_freepool_models` show members and headroom (never keys). Personal use only — see [docs/freepool.md](docs/freepool.md) for setup, per-provider ToS caveats, and the self-maintained catalog.

## Docs

Install, [Profiles](docs/profiles.md), [Connectors](docs/connectors.md), [Mods](docs/mods.md), [Security](docs/security.md), [Protocol compatibility](docs/protocol-compat.md), [Fixed task set](docs/task-set.md), [freepool](docs/freepool.md), [Changelog](CHANGELOG.md)

## License

MIT. APE code and all vendored engines (Genesis, EVE, ADAM, Skein). See `NOTICE.md`.