# Wunder: code mode for all your APIs

Wunder is a CLI that installs OpenAPI, GraphQL and MCP APIs like packages; the agent searches for the few operations a task needs and writes one script instead of a chain of tool calls. Credentials stay in the OS keychain.

## Agent quickstart

Paste into your agent: "Read https://getwunder.dev/llms.txt and set up Wunder in this repo."

```
Set up Wunder in this project.
1. npm i -g wunder
   # check: `wunder version` prints a version
2. export WUNDER_REGISTRY=https://getwunder.dev
   # points the CLI at this registry; keep it set for the steps below
3. wunder auth login
   # opens a browser; ask the user to finish sign-in (--no-browser prints the URL)
4. wunder init
   # creates wunder.json and AGENTS.md in the current directory
5. wunder capability search "<what you need>"
   # suggests catalogue APIs with their install line; exit 4 with suggestions is expected here, continue
6. wunder install <org/api>
   # pins the schema in the lockfile; never calls the API
7. wunder credentials login <org/api>
   # the user approves access; never paste tokens into chat
8. wunder script new "<task>"
   # writes, checks and runs a saved script; quick questions: wunder run -e '…'
Run each step and stop on the first failure.
Add --json to any command for one structured result; JSON mode never asks interactive questions.
Exit code 2 means sign-in is required: run wunder auth login. Do not work around sign-in or consent.
```

## Why one script

When every API is a set of tools, every tool definition sits in the context window and every call goes through the model, one at a time, each result read back in. With Wunder the agent searches for the few operations the task needs and writes one script. Scripts are typed, saved and version-pinned, and reruns skip search and script writing.

Benchmark ("Find the customers affected by each open bug", GitHub + Linear + Pylon, Claude Code): 106 s and $0.32 with Wunder against 171 s and $1.82 with MCP servers. Rerunning the saved script: 16 s and $0.02.

## How it works

1. **Install**: `wunder install github/graphql`. Like npm dependencies, pinned in a lockfile.
2. **Search**: `wunder capability search "open issues"`. Plain words in, a typed call out.
3. **Run**: `wunder run -e '…'` for a quick question, `wunder script new "…"` for a saved script.
4. **Rerun**: `wunder run scripts/customers-hit.js`. Reruns reuse cached model answers.

## What a script looks like

```js
import { openIssues, searchTickets } from "wunder";

// Which customer accounts mention each open issue?
export default async () => {
  const issues = await openIssues.all({ owner: "acme", name: "api", states: ["OPEN"] });
  return Promise.all(issues.map(async (issue) => {
    const tickets = await searchTickets.all({ search_text: issue.title }, { max: 5 });
    return { issue: issue.title, accounts: tickets.map((t) => t.account?.id) };
  }));
};
```

Scripts can also call models and web search: `import { llm, decisions } from "wunder:model"` and `import { web } from "wunder:web"`. The broker adds keys; the script never sees them.

## Security

The script runs in a sandbox with no network, files or environment. Every API call goes through the broker, which reads the token from the OS keychain at the last step. API traffic never passes through Wunder. The registry never sees your data.

## Registry

Every package is an immutable `org/name` version with a hash in your lockfile. `wunder capability check` shows what a new schema would break before you upgrade. Publish your own API:

```
wunder init --package --name acme/api --format openapi --schema openapi.yaml
wunder publish
```

## FAQ

- **Is Wunder against MCP?** No. MCP is how an API describes itself, and Wunder installs MCP schemas next to OpenAPI and GraphQL. What we replace is tools called one at a time through the model.
- **Does the agent or the script see my API tokens?** No. Tokens live in your OS keychain and are injected at the boundary when a request leaves the sandbox. A credential is only ever sent to its configured destination; anything else is blocked.
- **Which agents and models does it work with?** Any agent that can run a shell command: Claude Code, Codex, Cursor and others. Your agent keeps its own model.
- **What if my API isn't in the registry?** If it has an OpenAPI 3.x or Swagger 2.0 document, a GraphQL schema or an MCP server, publish it yourself in two commands.