# Agent Setup

Give any AI agent persistent TokST memory in under a minute.

## Browser Setup (recommended)

For a local CLI or desktop Agent, run one command. It downloads the standalone TokST CLI, then opens browser authorization:

```bash
curl -fsSL https://tokst.com/install.sh | bash
```

Windows PowerShell uses:

```powershell
irm https://tokst.com/install.ps1 | iex
```

TokST opens a browser, confirms the signed-in account, saves the credential locally, then verifies the connection. Workspace and Atlas selection remain explicit in each command, MCP tool call, or optional directory binding. This flow keeps the API key out of chat messages and copied configuration.

## One-Link Setup

Copy this message and paste it into your agent's chat:

```
Read https://tokst.com/skill.md and install TokST memory skill step by step.
Start with: curl -fsSL https://tokst.com/install.sh | bash
```

The agent will read the linked guide and follow the matching setup steps:
1. Run `curl -fsSL https://tokst.com/install.sh | bash`
2. Approve the browser connection
3. Run `tokst init --agents <agent>` in any directory to write agent instructions; create and bind an Atlas separately when project routing is needed
4. Place the `tokst-memory` Skill in the client directory when the client supports Skills
5. Start with context and structured Markdown memories

If your agent can't access links directly, download the guide first:

```bash
curl -fsSL https://tokst.com/skill.md -o SKILL.md
```

Then tell your agent: `Read SKILL.md and follow the setup steps.`

**Version checking is built in** — re-reading the link updates the skill to the latest version automatically.

> The skill files are stateless. All your memories live in the TokST cloud, not in these files. Updating the skill never affects your data.

---

## Which Agents Are Supported?

Place `skill.md` as `SKILL.md` in the directory used by your agent:

| Agent | Skill directory |
|-------|----------------|
| Claude Code | `~/.claude/skills/tokst-memory/` |
| Codex | `~/.codex/skills/tokst-memory/` |
| Pi | `~/.pi/skills/tokst-memory/` |
| WorkBuddy | `~/.workbuddy/skills/tokst-memory/` |
| ZCode | `~/.zcode/skills/tokst-memory/` |
| Qoder | `~/.qoder/skills/tokst-memory/` |
| Kimi Code | `~/.kimi-code/skills/tokst-memory/` |
| Cursor / Windsurf | `~/.cursor/skills/tokst-memory/` |
| Any MCP-compatible agent | `~/.agents/skills/tokst-memory/` |

---

## Manual Setup

The installer is the supported starting point for a fresh computer. It requires a Unix shell and `curl`; macOS, Linux, and WSL include both in their standard environments.

```bash
# Install the standalone CLI, then authorize in the browser
curl -fsSL https://tokst.com/install.sh | bash
tokst doctor

# Verify
tokst status
```

### Step 2: Install the skill files

The easiest way is to paste the one-link setup into your agent's chat — it handles installation automatically. See [One-Link Setup](#one-link-setup-recommended) above.

To install manually, use the one-link setup script instead of downloading individual files:

### Step 3: Add MCP (optional)

TokST supports Claude Code, Codex, Pi, WorkBuddy, ZCode, Qoder, Kimi, and other MCP clients. OAuth-capable clients can connect to the cloud endpoint directly. The MCP client opens TokST for approval and needs no local runtime. Set `TOKST_MCP_TOOLSET=core` on a remote service only when a focused 11-tool memory surface is required:

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp"
    }
  }
}
```

WorkBuddy, ZCode, Qoder, Kimi, and other clients that use a static configuration can authenticate with a dedicated API key. Create one in [Dashboard API Keys](https://tokst.com/dashboard/api-keys), then use this Streamable HTTP configuration:

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_api_key"
      }
    }
  }
}
```

Use a dedicated key for each client and revoke it from the dashboard when that client no longer needs access.

Local stdio MCP remains available after the installer for clients that require a local process.

---

## Dashboard Shortcut

When you create an API key in the [dashboard](https://tokst.com/dashboard/api-keys), the creation modal shows:
- A ready-to-copy **SKILL.md** (with your key embedded)
- A **Quick Start script** (one paste into terminal)
- An **MCP config** JSON
- A per-row **Copy for Agent** button on each key

You can also just share `https://tokst.com/skill.md` — the agent handles the rest.

---

## Verify It Works

```bash
# Check CLI is connected
tokst status

# Check skill files are installed (adjust path for your agent)
head -5 ~/.claude/skills/tokst-memory/SKILL.md
# Should show: --- name: tokst-memory ... version: 0.8.3 ---

# Store a test memory
TOKST_AGENT=1 tokst remember "Agent setup complete" --type note --json

# Search for it
TOKST_AGENT=1 tokst search "agent setup" --json

# Optional: enable automatic memory bridges once
tokst auto on --agent all
tokst acp proxy -- <acp-agent-command> [args]
tokst auto status
```

### OpenCode Terminal, App, and ACP

OpenCode Terminal and the macOS App load the TokST global plugin after one restart. Sessions started with `opencode` or resumed with `opencode -s` map to one TokST Session and update the same automatic memory. An ACP-compatible editor or IDE can also launch OpenCode through TokST.

```bash
tokst auto on --agent opencode
tokst acp opencode --doctor
```

Use this Agent command in an ACP-compatible editor or IDE:

```json
{
  "command": "tokst",
  "args": ["acp", "opencode"]
}
```

`tokst auto repair --agent opencode` regenerates the global plugin with the current absolute TokST executable path. `tokst acp opencode --repair` retains the ACP Host repair workflow.

### Pi, Codex, Claude Code, and Claude Desktop

Enable all detected native clients once, then restart the client you use. Pi receives a global extension. Codex and Claude Code receive TokST-managed Hook entries while every existing Hook remains in place. Each entrypoint maps a native session to one TokST Session and updates its matching automatic memory when the conversation resumes.

```bash
tokst auto on --agent pi,codex,claude
tokst auto verify --agent pi,codex,claude --json
tokst acp pi --doctor
```

Claude Desktop uses the TokST MCP extension for assisted memory capture, search, Session lifecycle, and reversal. Its desktop integration remains `assisted`; it does not claim automatic conversation observation.

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Agent doesn't see the skill | Verify the skill directory path matches your agent (`~/.claude/skills/`, `~/.cursor/skills/`, etc.) |
| `tokst: command not found` | Run `curl -fsSL https://tokst.com/install.sh \| bash`, then open a new terminal. |
| `Not logged in` | `tokst login --key tk_live_xxxx` |
| MCP tools not showing | Run `tokst login` on the same machine as the MCP server |
| Skill is outdated | Re-read `tokst.com/skill.md` or re-download the files |
| Automatic memory has not appeared | Run `tokst auto status --agent opencode` or `tokst auto status --agent workbuddy`; restart the corresponding client after bridge installation. |
| `tokst acp opencode` reports a legacy config | Run `tokst acp opencode --repair`, then restart the ACP host. |
| Automatic memory blocked a session | Run `tokst auto status`; keys, passwords, cookies, and private keys are intentionally removed or blocked before upload. |

Full CLI reference: [CLI Commands](/docs/cli)