Codex

Give Codex long-term memory that survives context resets, session restarts, and fresh conversations. Codex remembers what you’re working on, your preferences, and the decisions you’ve made — across every project. Lifecycle hooks capture each session to Honcho and inject the relevant context back at session start, so you never have to repeat yourself.

Prerequisites

Codex ≥ 0.136.0
Node on your PATH (runs the installer and the hooks)

Quick Start

Step 1: Get Your Honcho API Key

Go to app.honcho.dev
Sign up or log in
Copy your API key (starts with hch-)

Step 2: Save Your API Key

Your key lives in ~/.honcho/config.json — the single config file every Honcho integration reads. codex-honcho takes the key straight from there.

Already have your key in ~/.honcho/config.json? If another Honcho integration already wrote it there, there’s nothing to do — skip to Step 3 and install picks it up automatically.

First time? Create it with the Honcho CLI:

honcho init   # prompts for your key, writes ~/.honcho/config.json
              # no CLI yet? uv tool install honcho-cli && honcho init

If you’d rather write the file yourself:

// ~/.honcho/config.json
{ "apiKey": "hch-your-api-key-here" }

Step 3: Install the Plugin

npm install -g @honcho-ai/codex-honcho
codex-honcho install      # registers hooks + MCP + skill in ~/.codex

install copies your resolved key into ~/.codex/config.toml so the Honcho MCP server authenticates with no environment variable to set. If you ever rotate your key, re-run codex-honcho install to refresh it.

Step 4: Restart Codex

Restart Codex (or start a new session) to load the hooks and the [features].hooks flag. On your next session start you’ll see Honcho memory load into context.

Step 5: (Optional) Tell Codex to use its memory

The bundled honcho-memory skill already nudges Codex to recall and save actively. To reinforce it, add a short directive to your global Codex instructions (~/.codex/AGENTS.md):

# Honcho Memory

You have persistent memory via Honcho. Context about me is loaded at the start
of every session — trust it and act on it; don't ask me what you already know.
Use the Honcho MCP tools (`search`, `chat`) to recall more mid-task, and
`create_conclusions` to save new preferences, decisions, and patterns as you learn them.

What You Get

Persistent Memory — Codex remembers your preferences, projects, and context across sessions
Survives Context Resets — Memory persists through /clear, compaction, and restarts
Active Recall — Codex can search your history and query what Honcho knows about you mid-task, not just at startup
Git Awareness — Optionally scope memory per branch, so feature work keeps its own context
Flexible Sessions — Map memory per directory, per git branch, or per chat instance
Local-First Capture — Conversations are queued to disk instantly and uploaded in the background — capture never blocks your turn or hits the network mid-conversation
Cross-Tool Context — Shares ~/.honcho/config.json with other Honcho integrations (Claude Code, Cursor, …), so context can follow you between tools

Configuration

All settings live in ~/.honcho/config.json (shared with other Honcho integrations). Codex-specific settings go under hosts.codex, falling back to the root fields. The hooks only ever read this file; install is the only writer.

{
  "apiKey": "hch-…",
  "peerName": "alice",              // your identity (default: $USER)
  "hosts": {
    "codex": {
      "workspace": "codex",          // Honcho workspace for Codex memory
      "sessionStrategy": "per-directory",
      "injectPerPrompt": false,      // re-inject context every turn (off by default)
      "saveMessages": true           // false = read memory but never write
    }
  }
}

Session Strategies

Controls how Codex conversations map to Honcho sessions:

Strategy	Session name	Best for
`per-directory` (default)	`my-app`	Most users — each project accumulates its own memory
`git-branch`	`my-app-main`	Feature-branch workflows where context per branch matters
`chat-instance`	`my-app-019ea7df`	Ephemeral usage — a clean slate per conversation

An explicit sessions[cwd] mapping overrides all strategies. Environment overrides: HONCHO_API_KEY, HONCHO_PEER_NAME, HONCHO_CONFIG_DIR.

Building with Teammates

Because ~/.honcho/config.json is shared across Honcho hosts, teammates can collaborate by pointing at the same workspace while keeping their own identities. Each person uses their own peerName, so their contributions are attributed to distinct peers even when they work in the same repo. Alice (~/.honcho/config.json):

{
  "apiKey": "hch-team-key...",
  "peerName": "alice",
  "hosts": {
    "codex": { "workspace": "team-acme" }
  }
}

Bob (~/.honcho/config.json):

{
  "apiKey": "hch-team-key...",
  "peerName": "bob",
  "hosts": {
    "codex": { "workspace": "team-acme" }
  }
}

Both Alice and Bob write to the team-acme workspace. Working in the same repo, they share a session (named by directory, e.g. my-app) but appear in it as separate peers — so Honcho’s dialectic reasoning can draw on context from both.

MCP Tools

Once installed, Codex can call these Honcho tools directly:

Tool	Description
`search`	Semantic search across your session messages
`chat`	Ask Honcho a natural-language question about you
`get_peer_context`	Fetch the current model of you (representation + peer card)
`get_representation`	Lightweight representation string
`create_conclusions`	Save durable insights to memory
`list_conclusions`	List saved conclusions
`query_conclusions`	Semantic search across derived conclusions
`delete_conclusion`	Remove a conclusion by ID

Commands

Command	Effect
`codex-honcho install`	Install hooks + MCP + skill
`codex-honcho status`	Installed components, pending queue depth, GUI link
`codex-honcho remove`	Strip only what this installs

What Install Writes

Path	Change
`~/.codex/honcho/`	staged copy of the bundle the hooks run (kept stable across npm/npx cache eviction)
`~/.codex/hooks.json`	adds the four hook entries (merged; your own hooks untouched)
`~/.codex/config.toml`	sets `[features].hooks = true`; registers `[mcp_servers.honcho]` → `mcp.honcho.dev` (native HTTP)
`~/.codex/skills/honcho-memory/`	the active-recall skill
`~/.honcho/config.json`	persists the resolved `apiKey` + `peerName` (other fields and `hosts.*` blocks preserved)

codex-honcho remove reverses exactly these.

Troubleshooting

No memory loading / MCP not registered. Confirm your key is in ~/.honcho/config.json (codex-honcho status shows honcho config: found). If it’s missing, run honcho init (or add { "apiKey": "hch-…" } to the file yourself), then re-run codex-honcho install — without a key, install registers the hooks and skill but skips the MCP server. Hooks aren’t firing. Restart Codex after installing so it loads hooks.json and the [features].hooks flag. Check codex-honcho status for installed components and pending queue depth. Memory not persisting. Make sure saveMessages isn’t set to false under hosts.codex.

Install from a GitHub Clone (no npm)

git clone https://github.com/plastic-labs/codex-honcho
cd codex-honcho
./install.sh              # bun install + bun run bin/codex-honcho.ts install

The clone path runs the TypeScript source directly and so requires bun; it wires the hooks to bun run <this dir>/bin/codex-honcho.ts, so keep the clone in place. The npm install instead stages the bundled dist/codex-honcho.mjs to ~/.codex/honcho/ and wires hooks to node — node-only, and stable across npm update, npx cache eviction, or removing the package.

Prerequisites

Quick Start

Step 1: Get Your Honcho API Key

Step 2: Save Your API Key

Step 3: Install the Plugin

Step 4: Restart Codex

Step 5: (Optional) Tell Codex to use its memory

What You Get

Configuration

Session Strategies

Building with Teammates

MCP Tools

Commands

What Install Writes

Troubleshooting

Install from a GitHub Clone (no npm)

Next Steps

GitHub Repository

Honcho Architecture

​Prerequisites

​Quick Start

​Step 1: Get Your Honcho API Key

​Step 2: Save Your API Key

​Step 3: Install the Plugin

​Step 4: Restart Codex

​Step 5: (Optional) Tell Codex to use its memory

​What You Get

​Configuration

​Session Strategies

​Building with Teammates

​MCP Tools

​Commands

​What Install Writes

​Troubleshooting

​Install from a GitHub Clone (no npm)

​Next Steps

GitHub Repository

Honcho Architecture

Prerequisites

Quick Start

Step 1: Get Your Honcho API Key

Step 2: Save Your API Key

Step 3: Install the Plugin

Step 4: Restart Codex

Step 5: (Optional) Tell Codex to use its memory

What You Get

Configuration

Session Strategies

Building with Teammates

MCP Tools

Commands

What Install Writes

Troubleshooting

Install from a GitHub Clone (no npm)

Next Steps