yvgude--lean-ctx/docs/guides/codex-cli.md

Codex CLI + lean-ctx Integration Guide

Complete guide to setting up and optimally using lean-ctx with Codex CLI (OpenAI's terminal-based coding agent).

Overview

Property	Value
Integration mode	Hybrid (MCP reads + shell hooks)
Config file	~/.codex/config.toml
Rules file	~/.codex/instructions.md (shared block)
Setup command	lean-ctx init --agent codex

Quick Setup

# One command — configures MCP, rules, and shell hook
lean-ctx init --agent codex

# Verify
lean-ctx doctor

lean-ctx auto-detects Codex CLI by checking for ~/.codex/ or the codex binary in $PATH.

Note

: The Codex CLI config directory can be customized via the CODEX_HOME environment variable. lean-ctx respects this setting.

Proxy (lean-ctx proxy) will work only with proxy_require_token=false for ChatGPT subscriptions. You can set it in ~/.config/lean-ctx/config.toml or via lean-ctx config set proxy_require_token false

Manual Setup

Step 1: MCP Server Registration

Codex CLI uses TOML configuration. lean-ctx writes to ~/.codex/config.toml:

[mcp_servers.lean-ctx]
command = "lean-ctx"
args = []

If the file already exists, lean-ctx merges the [mcp_servers.lean-ctx] section without modifying other settings.

Key difference from JSON agents: Codex uses TOML format with [mcp_servers.<name>] sections instead of JSON mcpServers objects.

Step 2: Agent Rules

Codex CLI shares its rules infrastructure with Claude Code. lean-ctx creates dedicated rules at the Claude rules directory:

# lean-ctx — Context Engineering Layer
<!-- lean-ctx-rules -->

## Mode Selection
1. Editing the file? → `anchored` first (full text + anchors), then `diff` for re-reads
2. Need API surface only? → `map` or `signatures`
3. Large file, context only? → `entropy` or `aggressive`
4. Specific lines? → `lines:N-M`
5. Active task set? → `task`
6. Unsure? → `auto` (system selects optimal mode)

Anti-pattern: NEVER use `full` for files you won't edit — use `map` or `signatures`.

## File Editing
Anchored editing: `ctx_read(mode="anchored")` → `ctx_patch(path, op, line, hash, new_text)` —
never echo old text; batch via `ops:[…]`; `op=create` for new files. Stale anchor → CONFLICT
with fresh anchors (retry once). Native Edit/StrReplace stay fine; `ctx_edit` is the legacy
power-profile fallback. Write, Delete, Glob → use normally.

## Proactive (use without being asked)
- `ctx_overview(task)` at session start
- `ctx_compress` when context grows large

## Session Documentation
After significant work, document progress:
- ctx_knowledge(action=remember, category=decision, content=what and why)
- ctx_session(action=task, value=task description with progress)
When you see [CHECKPOINT] → document current status immediately.

Fallback only if a lean-ctx tool is unavailable: use native equivalents.
<!-- /lean-ctx -->

Step 3: Shell Hook

Codex CLI has shell access. lean-ctx installs compression hooks:

lean-ctx init --global

Sandbox Workflow

Codex CLI runs in a sandboxed environment for safety. lean-ctx integrates with this:

How the Sandbox Affects lean-ctx

Aspect	Behavior
File reads	Work normally — lean-ctx reads files within the sandbox
Shell commands	Compressed within sandbox constraints
Data directory	the lean-ctx data directory (~/.lean-ctx / XDG, or LEAN_CTX_DATA_DIR if you relocated it) must be accessible from the sandbox
Network	lean-ctx is local-first, no network needed

Sandbox Permissions

Codex CLI uses different permission levels. lean-ctx works with all of them:

• suggest — lean-ctx provides read-only context (map, signatures, search)
• auto-edit — lean-ctx provides reads + context for edits
• full-auto — lean-ctx provides full hybrid integration

Running with Full Auto

codex --approval-mode full-auto "refactor the auth module"

lean-ctx tools are available in all modes since they're read-only MCP tools.

Background Agent Integration

Codex CLI supports background agents for long-running tasks. lean-ctx enhances this:

Context Persistence

Background agents can lose context between steps. lean-ctx prevents this:

# Background agent step 1: Research
ctx_overview("migrate database from SQLite to PostgreSQL")
ctx_search("sqlite", "src/")
ctx_knowledge(action="remember", category="discovery", content="15 files reference SQLite directly")

# Background agent step 2: Plan (context persists via lean-ctx)
ctx_knowledge(action="recall", query="SQLite references")  # Returns the discovery from step 1
ctx_session(action="task", value="SQLite to PostgreSQL migration [25%]")

# Background agent step 3: Implement
ctx_read("src/db/connection.rs", "full")  # Cached from step 1's overview

Task Tracking

# Set task at the start
ctx_session(action="task", value="Database migration [0%]")

# Update as you go
ctx_session(action="task", value="Database migration [50%] — schema converted")

# Complete
ctx_session(action="task", value="Database migration [100%]")

Codex-Specific Workflow

Interactive Mode

codex

In interactive mode, lean-ctx tools are available directly:

> Use ctx_read to read src/main.rs in map mode
> Search for "async fn" using ctx_search
> Show me the impact of changing src/models/user.rs

One-Shot Mode

codex "add error handling to all API endpoints"

lean-ctx provides context compression during the one-shot execution:

1. Codex reads files → lean-ctx caches and compresses
2. Codex runs commands → shell hook compresses output
3. Codex makes edits → native edit tools (lean-ctx handles reads)

Quiet Mode

codex --quiet "fix the failing tests"

lean-ctx works in quiet mode without any additional output.

TOML Configuration Details

Full config.toml Example

# ~/.codex/config.toml

# MCP servers
[mcp_servers.lean-ctx]
command = "lean-ctx"
args = []

# Other Codex settings can coexist
# [other_section]
# ...

Custom Binary Path

If lean-ctx is installed in a non-standard location:

[mcp_servers.lean-ctx]
command = "/path/to/lean-ctx"
args = []

Custom CODEX_HOME

export CODEX_HOME=/custom/path
lean-ctx init --agent codex  # Writes to /custom/path/config.toml

Token Savings

Operation	Without lean-ctx	With lean-ctx	Savings
File read (cached)	~2000 tokens	~13 tokens	99.4%
File read (map)	~2000 tokens	~400 tokens	80%
git diff	~1200 tokens	~200 tokens	83%
cargo test	~2000 tokens	~300 tokens	85%
npm run build	~1500 tokens	~250 tokens	83%

Monitor savings:

lean-ctx gain --live

Advanced Features

Context Packs for Codex Tasks

Bundle context for complex tasks:

# Create a context pack
ctx_pack("create", "auth-refactor")

# Later, in a new Codex session
ctx_pack("load", "auth-refactor")

Code Review with Codex

# Get PR context
ctx_shell("git diff main...HEAD --stat")

# Review changes
ctx_review("src/api/handler.rs")

# Check for code smells
ctx_smells("src/api/handler.rs")

Multi-Step Refactoring

# Step 1: Analyze
ctx_overview("rename UserService to AccountService across the codebase")
ctx_refactor("references", "src/services/user.rs", "UserService")

# Step 2: Plan
ctx_impact("src/services/user.rs")
ctx_knowledge(action="remember", category="decision", content="Renaming UserService to AccountService — 12 files affected")

# Step 3: Execute
ctx_refactor("rename", "src/services/user.rs", "UserService", "AccountService")

Troubleshooting

MCP server not connecting

# Check config.toml
cat ~/.codex/config.toml

# Verify TOML syntax
# Should have [mcp_servers.lean-ctx] section

# Test MCP server
echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{}},"id":1}' | lean-ctx mcp

# Re-run setup
lean-ctx init --agent codex

Custom CODEX_HOME not detected

# Ensure CODEX_HOME is set
echo $CODEX_HOME

# Re-run with explicit path
CODEX_HOME=/your/path lean-ctx init --agent codex

TOML parsing errors

If Codex reports config errors:

# Validate TOML syntax
python3 -c "import tomllib; tomllib.load(open('$HOME/.codex/config.toml', 'rb'))"

# Common issues:
# - Missing quotes around paths with spaces
# - Duplicate section headers
# - Trailing commas (not valid in TOML)

Sandbox blocking lean-ctx

If the sandbox prevents lean-ctx from accessing files:

# Ensure lean-ctx data dir is accessible
ls -la ~/.lean-ctx/

# Check if the binary is accessible from sandbox
which lean-ctx

Shell hook not working in sandbox

The shell hook may not activate in Codex's sandbox. lean-ctx's MCP tools (ctx_shell) still work:

# Use ctx_shell instead of direct shell commands
ctx_shell("git status")
ctx_shell("cargo test")

Codex Desktop / Codex Cloud: these clients' models instinctively reach for a tool literally named shell (or bash) rather than ctx_shell. lean-ctx registers a shell tool that is a 1:1 alias of ctx_shell — same pattern compression, same allowlist — so commands stay compressed even when the model never learns the ctx_ prefix. Nothing to configure; it ships in every profile.

Tools not available

# Verify Codex sees the MCP server
codex --list-mcp-servers

# Check binary path
which lean-ctx

# Re-install
lean-ctx init --agent codex

Further Reading

• lean-ctx Tools Reference
• CLI Reference
• Codex CLI Documentation
• MCP Protocol