---
title: "Claude Code"
icon: 'terminal'
description: "Add AI-native memory to Claude Code"
sidebarTitle: 'Claude Code'
---

Give Claude Code long-term memory that survives context wipes, session restarts, and `ctrl+c`. Claude remembers what you're working on, your preferences, and what it was doing across all your projects.


## Quick Start

### Step 1: Get Your Honcho API Key

1. Go to **[app.honcho.dev](https://app.honcho.dev)**
2. Sign up or log in
3. Copy your API key (starts with `hch-`)

### Step 2: Set Environment Variables

Add these to your shell config (`~/.zshrc`, `~/.bashrc`, or `~/.profile`):

```bash
# Required
export HONCHO_API_KEY="hch-your-api-key-here"

# Optional (defaults shown)
export HONCHO_PEER_NAME="$USER"           # Your name/identity
```

Then reload your shell:

```bash
source ~/.zshrc  # or ~/.bashrc
```

### Step 3: Install the Plugin

<Note>
This plugin requires [Bun](https://bun.sh). If you don't have it: `curl -fsSL https://bun.sh/install | bash`
</Note>

Open Claude Code and run:

```
/plugin marketplace add plastic-labs/claude-honcho
```

Then install:

```
/plugin install honcho@honcho
```

### Step 4: Restart Claude Code

```bash
# Exit Claude Code (ctrl+c or /exit)
# Start it again
claude
```

**That's it!** You should see the Honcho pixel art and memory loading on startup.

### Step 5: (Optional) Kickstart with an Interview

```
/honcho:interview
```

Claude will interview you about your personal preferences to kickstart a representation of you. What it learns will be saved in Honcho and remembered forever. The interview is specific to the peer name you chose — it carries across different projects!

## What You Get

- **Persistent Memory** — Claude remembers your preferences, projects, and context across sessions
- **Survives Context Wipes** — Even when Claude's context window resets, memory persists
- **Git Awareness** — Detects branch switches, commits, and changes made outside Claude
- **Flexible Sessions** — Map sessions per directory, per git branch, or per chat instance
- **AI Self-Awareness** — Claude knows what it was working on, even after restarts
- **Cross-Tool Context** — Link workspaces across Claude Code, Cursor, and other hosts so context flows between tools
- **Team Support** — Multiple people can share a workspace and build context together
- **MCP Tools** — Search memory, query knowledge about you, and save insights

## Configuration

All configuration lives in a single global file at `~/.honcho/config.json`. You can edit it directly, use the `/honcho:config` skill interactively, or use the `set_config` MCP tool. Environment variables work for initial setup but the config file takes precedence once it exists.

```jsonc
{
  // Required
  "apiKey": "hch-v2-...",

  // Identity
  "peerName": "alice",              // Your name (default: $USER)

  // Host-specific settings — each tool gets its own workspace and AI peer
  "hosts": {
    "claude_code": {
      "workspace": "claude_code",   // Workspace for Claude Code sessions
      "aiPeer": "claude",           // AI identity in this workspace
      "linkedHosts": ["cursor"]     // Read context from other hosts (optional)
    },
    "cursor": {
      "workspace": "cursor",
      "aiPeer": "cursor"
    }
  },

  // Session mapping
  "sessionStrategy": "per-directory", // "per-directory" | "git-branch" | "chat-instance"
  "sessionPeerPrefix": true,          // Prefix session names with peerName (default: true)

  // Message handling
  "saveMessages": true,
  "messageUpload": {
    "maxUserTokens": null,            // Truncate user messages (null = no limit)
    "maxAssistantTokens": null,       // Truncate assistant messages (null = no limit)
    "summarizeAssistant": false       // Summarize instead of sending full assistant text
  },

  // Context retrieval
  "contextRefresh": {
    "messageThreshold": 30,           // Refresh context every N messages
    "ttlSeconds": 300,                // Cache TTL for context
    "skipDialectic": false            // Skip dialectic chat() calls in user-prompt hook
  },

  // Endpoint
  "endpoint": {
    "environment": "production"       // "production" | "local"
    // or: "baseUrl": "http://your-server:8000/v3"
  },

  // Miscellaneous
  "localContext": { "maxEntries": 50 },
  "enabled": true,
  "logging": true,

  // Advanced: force all hosts to use the same workspace
  "globalOverride": false
}
```

### Session Strategies

Session strategy controls how Honcho maps your conversations to sessions:

| Strategy | Behavior | Best for |
| --- | --- | --- |
| `per-directory` (default) | One session per project directory. Stable across restarts. | Most users — each project accumulates its own memory |
| `git-branch` | Session name includes the current git branch. Switching branches switches sessions. | Feature-branch workflows where context per branch matters |
| `chat-instance` | Each Claude Code chat gets its own session. No continuity between restarts. | Ephemeral usage or when you want a clean slate each time |

Session names are prefixed with your `peerName` by default (e.g., `alice-my-project`). Set `sessionPeerPrefix: false` if you're the only user and want shorter names.

### Host-Aware Configuration

The plugin auto-detects which tool is running it (Claude Code, Cursor, etc.) and reads the matching block from `hosts`. Each host gets its own workspace and AI peer name, so data stays separated by default.

**Host detection priority:**
1. `HONCHO_HOST` env var (explicit override)
2. `cursor_version` in hook stdin (Cursor detected)
3. `CURSOR_PROJECT_DIR` env var (Cursor child process)
4. Default: `claude_code`

### Linking Hosts for Cross-Tool Context

If you use both Claude Code and Cursor, you can link them so context from one is readable in the other. Writes always stay in the current host's workspace — linking only adds read access.

```jsonc
{
  "hosts": {
    "claude_code": {
      "workspace": "claude_code",
      "aiPeer": "claude",
      "linkedHosts": ["cursor"]  // Claude Code can read Cursor's context
    },
    "cursor": {
      "workspace": "cursor",
      "aiPeer": "cursor",
      "linkedHosts": ["claude_code"]  // Cursor can read Claude Code's context
    }
  }
}
```

Or use `/honcho:config` and select **Workspace > Linking** to set this up interactively.

### Global Override

If you want all hosts to share a single workspace (instead of per-host isolation), set `globalOverride: true` and a flat `workspace` field:

```jsonc
{
  "globalOverride": true,
  "workspace": "shared",
  "hosts": {
    "claude_code": { "aiPeer": "claude" },
    "cursor": { "aiPeer": "cursor" }
  }
}
```

All tools will read and write to the `shared` workspace. Each tool still uses its own AI peer name.

## Building with Teammates

Multiple people can share context by pointing to the same workspace. Each person uses their own `peerName` as identity, and sessions are automatically prefixed with it to avoid collisions.

**Person A** (`~/.honcho/config.json`):
```json
{
  "apiKey": "hch-v2-team-key...",
  "peerName": "alice",
  "hosts": {
    "claude_code": {
      "workspace": "team-acme",
      "aiPeer": "claude"
    }
  }
}
```

**Person B** (`~/.honcho/config.json`):
```json
{
  "apiKey": "hch-v2-team-key...",
  "peerName": "bob",
  "hosts": {
    "claude_code": {
      "workspace": "team-acme",
      "aiPeer": "claude"
    }
  }
}
```

Both Alice and Bob write to the `team-acme` workspace. Their sessions are namespaced (e.g., `alice-my-project`, `bob-my-project`) so data doesn't collide, but Honcho's dialectic reasoning can draw on context from both users.

## Logging

The plugin logs activity to `~/.honcho/` and to Claude Code's verbose mode, so you can see exactly how Honcho is being used — what context is loaded at session start, what messages are saved, and what context is injected into Claude's prompts. Set `logging` to `false` in your config (or `HONCHO_LOGGING=false`) to disable file logging.

## MCP Tools

The plugin provides these tools via MCP:

| Tool | Description |
|------|-------------|
| `search` | Semantic search across session messages |
| `chat` | Query Honcho's knowledge about the user |
| `create_conclusion` | Save insights about the user to memory |
| `get_config` | View current configuration and status |
| `set_config` | Change any configuration field programmatically |

## Skills (Slash Commands)

| Command | Description |
| ------- | ----------- |
| `/honcho:status` | Show current memory status and connection info |
| `/honcho:config` | Interactive configuration menu |
| `/honcho:setup` | First-time setup — validate API key and create config |
| `/honcho:interview` | Interview to capture stable, cross-project user preferences |

### The Interview

The `/honcho:interview` skill conducts a short interview to learn stable, cross-project aspects about you:

- **Communication style** — Concise answers, detailed explanations, or a mix
- **Tone** — Direct and professional or conversational
- **Structure** — Bullet points, step-by-step, or narrative
- **Technical depth** — Beginner, intermediate, or expert
- **Code quality focus** — Clarity, performance, tests, or minimal changes
- **Collaboration style** — Make changes directly, propose options, or ask first

Each answer is saved as a conclusion in Honcho memory and persists across all your projects.

## Environment Variables

Environment variables work for initial bootstrap (before a config file exists). Once `~/.honcho/config.json` is written, the config file takes precedence for host-specific fields like `workspace`.

| Variable | Required | Default | Description |
| -------- | -------- | ------- | ----------- |
| `HONCHO_API_KEY` | **Yes** | — | Your Honcho API key from [app.honcho.dev](https://app.honcho.dev) |
| `HONCHO_PEER_NAME` | No | `$USER` | Your identity in the memory system |
| `HONCHO_WORKSPACE` | No | `claude_code` | Workspace name (used only when no config file exists) |
| `HONCHO_AI_PEER` | No | `claude` | AI peer name |
| `HONCHO_HOST` | No | auto-detected | Force host detection: `claude_code`, `cursor`, or `obsidian` |
| `HONCHO_ENDPOINT` | No | `production` | `production`, `local`, or a full URL |
| `HONCHO_ENABLED` | No | `true` | Set to `false` to disable |
| `HONCHO_SAVE_MESSAGES` | No | `true` | Set to `false` to stop saving messages |
| `HONCHO_LOGGING` | No | `true` | Set to `false` to disable file logging to `~/.honcho/` |

### Using a local Honcho instance

Via config file:
```json
{ "endpoint": { "environment": "local" } }
```

Or via env var:
```bash
export HONCHO_ENDPOINT="local"  # Uses http://localhost:8000/v3
```


---

## Using Honcho with Claude Desktop

You can also use Honcho with the Claude Desktop app via MCP. This lets Claude manage its own memory in the native desktop experience.

### Step 1: Get Your API Key

Get an API key from [app.honcho.dev](https://app.honcho.dev).

### Step 2: Configure Claude Desktop

<Note>
This requires [Node.js](https://nodejs.org). Claude Desktop or Claude Code can help you install it!
</Note>

Navigate to Claude Desktop's custom MCP servers settings and add Honcho:

```json
{
  "mcpServers": {
    "honcho": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.honcho.dev",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "X-Honcho-User-Name:${USER_NAME}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-honcho-key>",
        "USER_NAME": "<your-name>"
      }
    }
  }
}
```

**Optional customization** — You can also set a custom assistant name and workspace ID:

```json
{
  "mcpServers": {
    "honcho": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.honcho.dev",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "X-Honcho-User-Name:${USER_NAME}",
        "--header",
        "X-Honcho-Assistant-Name:${ASSISTANT_NAME}",
        "--header",
        "X-Honcho-Workspace-ID:${WORKSPACE_ID}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-honcho-key>",
        "USER_NAME": "<your-name>",
        "ASSISTANT_NAME": "<your-assistant-name>",
        "WORKSPACE_ID": "<your-custom-workspace-id>"
      }
    }
  }
}
```

### Step 3: Restart Claude Desktop

Upon relaunch, Honcho should start and the tools will be available.

### Step 4: Add Instructions

The Desktop app doesn't allow system prompts directly, but you can create a project and paste [these instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) into the "Project Instructions" field.

Claude will then query for insights before responding and write your messages to storage!

---

## Next Steps

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/plastic-labs/claude-honcho">
    Source code, issues, and README.
  </Card>

  <Card title="Honcho Architecture" icon="sitemap" href="../../documentation/core-concepts/architecture">
    Learn about peers, sessions, and dialectic reasoning.
  </Card>
</CardGroup>
