К основному содержанию
плагин CX Codex

codex-honcho — плагин для Claude Code: что делает и как установить

Плагин codex-honcho сохраняет контекст и решения между перезапусками сессий с помощью сервиса памяти Honcho, избавляя от повторения инструкций.

MIT ★ 1 596 обновлён 2026-10-29

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-honcho@awesome-codex-plugins
Открыть на GitHub

Что делает codex-honcho

Плагин связывает рабочую среду с API Honcho через хуки жизненного цикла и MCP-сервер. При запуске сессии он автоматически подгружает прошлый контекст проекта и предпочтения пользователя. История сохраняется локально на диск и отправляется в фоновом режиме, поэтому агент не ждёт ответа сети во время диалога.

Codex получает доступ к набору инструментов MCP: семантический поиск по прошлым сообщениям через search, прямое обращение к памяти через chat, а также вызовы create_conclusions и query_conclusions для фиксации выводов. Привязку памяти можно переключать между каталогом проекта (per-directory), веткой в Git (git-branch) или отдельным чатом (chat-instance).

Для работы требуются Node в PATH, Codex версии не ниже 0.136.0 и ключ API от сервиса Honcho. Без заполненного файла ~/.honcho/config.json сервер памяти не сможет авторизоваться.

Какие задачи решает

  • сохранить предпочтения и решения разработчика между перезапусками сессий
  • изолировать контекст разных веток в Git с помощью стратегии git-branch
  • искать детали прошлых обсуждений через семантический инструмент search
  • передавать профиль пользователя между разными интеграциями через общий конфиг

Примеры запросов агенту

  • Вспомни через Honcho, какие архитектурные решения мы зафиксировали для модуля авторизации.
  • Сохрани в долгосрочную память, что в этом репозитории мы используем только строгую типизацию.
  • Найди в прошлых сессиях команду для развёртывания тестового стенда.

Как установить codex-honcho

Через маркетплейс плагинов

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-honcho@awesome-codex-plugins

По шагам, с командами для каждой платформы: Плагины Claude Code: маркетплейсы, установка и как собрать свой

Вопросы о codex-honcho

Как установить codex-honcho в Claude Code?

Выполните в терминале агента /plugin marketplace add hashgraph-online/awesome-codex-plugins, а затем запустите команду /plugin install codex-honcho@awesome-codex-plugins.

Что делает codex-honcho?

Плагин внедряет долговременную память Honcho в сессии Codex. Он сохраняет контекст на диск и передаёт его в новые диалоги, даже если вы перезапустили терминал или выполнили команду /clear.

Какие варианты группировки сессий поддерживает плагин?

В конфигурационном файле доступны три стратегии: per-directory для привязки к каталогу, git-branch для разделения по веткам и chat-instance для изолированных диалогов.

Исходный текст

codex-honcho · MIT
# codex-honcho

[![codex-honcho](./assets/honcho_codex.png)](https://honcho.dev)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm](https://img.shields.io/npm/v/@honcho-ai/codex-honcho?color=blue)](https://www.npmjs.com/package/@honcho-ai/codex-honcho)
[![Honcho](https://img.shields.io/badge/Honcho-Memory%20API-blue)](https://honcho.dev)

**Persistent memory for [OpenAI Codex](https://developers.openai.com/codex), powered by [Honcho](https://honcho.dev) from Plastic Labs.**

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.

## 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

## Prerequisites

- **[Codex](https://developers.openai.com/codex) ≥ 0.136.0**
- **[Node](https://nodejs.org)** on your `PATH` (runs the installer and the hooks)

## 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: 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. (codex-honcho reads only this file, `hosts.codex`, and `HONCHO_API_KEY` — not any tool's private config, so confirm the key is in `~/.honcho/config.json` with `codex-honcho status`.)

**First time?** Create it with the Honcho CLI:

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

Either way the key stays in one place. If you'd rather write the file yourself:

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

### Step 3: Install the Plugin

```bash
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`):

```markdown
# 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.
```

## 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                       |

## 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.

```jsonc
{
  "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`.

## How It Works

```
┌──────────────────────────────────────────────────────────────────────┐
│                              Codex                                    │
├──────────────────────────────────────────────────────────────────────┤
│  SessionStart  │  UserPrompt     │  PostToolUse   │  Stop / PreCompact │
│  ───────────   │  ───────────    │  ────────────  │  ───────────────── │
│  recall:       │  prompt:        │  observe:      │  writeback:        │
│  load context  │  (optional)     │  note tool     │  capture the new   │
│  from Honcho   │  per-turn ctx   │  calls         │  transcript tail   │
└──────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
          ~/.honcho/codex/queue/<key>.jsonl   (append-only, local, instant)
                              │
                              ▼  flush (inline, end of turn)
                         Honcho API  →  Persistent Memory
                              │
                              ▼  retrieved as context at the next session start
```

The plugin hooks into Codex's lifecycle events:

- **SessionStart** (`recall`) — creates/materializes the session and injects a lean `<honcho-memory>` context block
- **UserPromptSubmit** (`prompt`) — optional per-turn context injection (off by default; the MCP tools cover depth)
- **PostToolUse** (`observe`) — appends a one-line note for significant tool calls to the local queue
- **Stop / PreCompact** (`writeback`) — captures the new transcript tail, then flushes the queue to Honcho

Capture is **local-first**: hooks only ever append to a plain JSONL queue, so they're instant and never touch the network. The flush is lock-guarded and advances a per-chunk sent marker, so a failed or partial upload simply stays queued and retries on the next turn. Inspect the local queue any time with `tail -f ~/.honcho/codex/queue/*.jsonl`, and run `codex-honcho status` to see the pending depth plus a deep link to your session in the Honcho GUI to confirm what landed server-side.

## 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`.

## 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.

## Install from a GitHub Clone (no npm)

```bash
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](https://bun.sh)**; 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.

## Development

```
bin/codex-honcho.ts      CLI: install · remove · status · <hook verb>
src/dispatch.ts          verb → handler routing
src/hooks/               recall · prompt · observe · writeback · flush
src/transcript/codex.ts  Codex rollout (.jsonl) parser
src/queue.ts             append-only outbox + sent high-water-mark
src/cursor.ts            per-conversation rollout delta cursor
src/connectors/          hooks.json · config.toml MCP block · skill writers
src/config.ts            hosts.codex resolution; session naming
skills/honcho-memory/    when-to-recall guidance for the model
```

```bash
bun test
bun run typecheck
```

## License

MIT — see [LICENSE](LICENSE)

## Links

- **Honcho**: [honcho.dev](https://honcho.dev) — the memory API
- **Documentation**: [docs.honcho.dev](https://docs.honcho.dev)
- **Discord**: [Join the community](https://discord.gg/plasticlabs)
- **X**: [@honchodotdev](https://x.com/honchodotdev)
- **Plastic Labs**: [plasticlabs.ai](https://plasticlabs.ai)

© Plastic Labs · MIT · hashgraph-online/awesome-codex-plugins

Похожие плагины

Все плагины по теме «Настройка агента: память, контекст, субагенты» →
honcho-cli plastic-labs Скилл honcho-cli для Claude Code исследует рабочие пространства Honcho через CLI. Запускается при проверке памяти peer, контекста сессии и ответов диалектики. CX Codex +1 626установок honcho-memory plastic-labs Скилл honcho-memory для Claude Code описывает, как подключённый Honcho хранит контекст пользователя и возвращает его агенту. Персонализирует диалоги между сессиями. CX Codex +1 214установок ub-mode unclebob Скилл ub-mode для Claude Code помогает разработчикам структурировать изменения в коде. Он направляет процесс разработки, следуя принципам «Сначала заставь работать, затем сделай правильно, затем следуй практикам». CX Codex +1 930установок methodology-advisor FlorianBruniaux Команда methodology-advisor для Claude Code и Codex изучает кодовую базу и задаёт три вопроса, чтобы подобрать подходящий стек методологий AI-разработки. Запускается вручную, когда нужно выбрать процесс до начала активной работы с агентом. CX Codex +1 ★ 6 529звёзд репо discernment-nudge официальный anthropics Плагин discernment-nudge для Claude Code и Claude.ai, который добавляет два-три коротких вопроса после развёрнутого ответа. Помогает проверить факты, разобрать логику и заметить, чего не хватает в рассуждении. ★ 198 522звёзд репо example-skills официальный anthropics Плагин example-skills для Claude Code и Claude.ai с набором примеров скиллов. Показывает, как строить скиллы, MCP-серверы, артефакты, тесты веб-приложений и внутренние коммуникации. ★ 198 522звёзд репо impeccable pbakaus Плагин impeccable для Claude Code, который даёт агенту словарь дизайнера и 24 команды для работы с интерфейсами. Запускается на каждом этапе: от сбора контекста проекта до финальной полировки перед релизом. ★ 114 575звёзд репо superpowers obra Плагин superpowers для Claude Code и Codex, который учит агента работать по полной методологии: сбор требований, проектирование, TDD и разработка через субагентов. Запускается автоматически, когда ты начинаешь строить что-то новое. CX Codex ★ 323 788звёзд репо

Из того же набора391

Весь набор →
kernel Плагин kernel ставит хуки-ограждения в Claude и Codex: блокирует разрушительные команды, закрывает необратимые операции одноразовым токеном и ведёт память агента в SQLite. CX Codex ★ 1 596звёзд репо jev-use Плагин jev-use делегирует быстрые бинарные решения и проверку шелл-команд модели суждений Jev без генерации лишнего текста. CX Codex ★ 1 596звёзд репо sirv-media-skills Плагин sirv-media-skills для Claude Code объединяет восемь скиллов для аудита изображений и видео, работы с Sirv API, галереями и 360-вью. Скиллы охватывают веб-производительность и товарный контент. CX Codex ★ 1 596звёзд репо hotl Плагин hotl ведёт задачу через восемь фаз: брейншторм, письменный план, исполнение, ревью и проверка тестами. Для фич, рефакторингов и правок, которые страшно пускать наугад. CX Codex ★ 1 596звёзд репо homie Плагин homie помогает создавать multiplayer-игры, музыку и видео, а затем публиковать их через студию на своём Cloudflare. CX Codex ★ 1 596звёзд репо hol-guard-plugin Проверяет вызовы инструментов перед выполнением и блокирует подозрительные операции. Встраивается в локальный слой безопасности, требует предварительно установленный hol-guard CLI. CX Codex ★ 1 596звёзд репо herdr-codex-subagents Плагин herdr-codex-subagents открывает отдельные терминальные панели Herdr только для чтения под каждого субагента Codex и автоматически закрывает их после выполнения работы. CX Codex ★ 1 596звёзд репо hera-unity Плагин hera-unity учит агента работать с запущенным Unity Editor через CLI hera-agent-unity: смотреть сцену, менять ассеты, гонять тесты и Play Mode. CX Codex ★ 1 596звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой