# Quickstart

Install Agent Stash continuity for Claude Code (and other tools) in a few minutes.

## Step 1: Install the CLI

**One command** (registers a free API key if you don’t have one):

```bash
npx @agentstash/mcp init --register --claude
```

**Or use a key** from [agentstash.ai](https://agentstash.ai) (GitHub sign-in):

```bash
npx @agentstash/mcp init --api-key sk_your_key --claude
```

After the first install, the key is saved in `~/.agentstash/config.json`. Later:

```bash
npx @agentstash/mcp init --claude --force
npx @agentstash/mcp doctor
```

### More tools

```bash
npx @agentstash/mcp init --claude --cursor --opencode --codex
# or
npx @agentstash/mcp init --all
```

Restart Claude Code / Cursor / OpenCode / Codex after install.

### What `init --claude` installs

| Piece | Role |
|-------|------|
| MCP server | `remember`, `save_progress`, `resume_progress`, … |
| SessionStart hook | Injects prior progress into new sessions |
| PreCompact / SessionEnd | Auto checkpoints |
| StopFailure hook | Auto **handoff** on rate limit / API errors |
| Continuity skill | Soft guidance to save progress mid-work |

## Step 2: Use it

Memory is scoped to your git project automatically.

**Remember a decision:**
```
remember("auth-approach", "Using session cookies, not JWT. Decided after ADR-003.")
```

**Recall it in a new session:**
```
recall("auth-approach")
```

**Save progress before a risky refactor:**
```
save_progress(
  task="Migrate auth from JWT to session cookies",
  completed_steps=["Updated login endpoint", "Updated logout endpoint"],
  next_step="Update middleware to validate session instead of JWT",
  decisions=["Keep JWT for service-to-service, session for browser"],
  files_touched=["app/auth.py", "app/middleware.py"]
)
```

**When you hit a provider limit** (or want to freeze state yourself):

```bash
npx @agentstash/mcp handoff
npx @agentstash/mcp handoff -m "mid auth refactor" --to opencode
```

On resume, call `resume_progress` (or rely on SessionStart) — do not re-plan from zero.

## Advanced: MCP config only (no hooks)

If you only want tools without continuity hooks:

```json
{
  "mcpServers": {
    "agent-stash": {
      "command": "npx",
      "args": ["-y", "@agentstash/mcp"],
      "env": {
        "AGENT_STASH_API_KEY": "sk_your_key_here"
      }
    }
  }
}
```

Claude Code: `~/.claude/settings.json` · Cursor: `~/.cursor/mcp.json`

## Headless agent key (HTTP only)

```
POST https://agentstash.ai/register/agent
Content-Type: application/json

{"agent_name": "my-project"}
```

Use the returned `api_key` with the HTTP API or `init --api-key`.