CodeTalker

Cross-harness agent conversation transcript normalizer and MCP server.

CodeTalker is an agent-callable tool and MCP server that normalizes conversation transcripts from different AI coding harnesses into a unified schema. This allows any agent to pick up context, search past decisions, or read thread history without requiring manual handoff documents.

Capabilities & Schema

• Normalized Intermediate Format: Standardized TextBlock, ThinkingBlock, ToolCallBlock, ToolResultBlock, CodeDiffBlock, AttachmentBlock, ApprovalBlock, SystemEventBlock.
• DAG / Branch Aware: Multi-branch threads (e.g. in ChatGPT/Codex or Claude Code) are exposed as distinct threads sharing a conversation ID.
• Fast Metadata Discovery: Fast header peeking and recency sorting for collections with 500+ session files.

Supported Harnesses & Verification Status

Stability, Fragility & Compatibility Disclaimers

MCP Tools

Agent quickstart

1. codetalk_capabilities — learn harness names, aliases, tool catalog, and unsupported hallucinated names (read_transcript, etc.).
2. Decision tree:
   • Lost context + know project path → codetalk_resolve_session → codetalk_read(since_last_user_input=true)
   • Know session_id → codetalk_read
   • Grep / find by title → codetalk_search(query=..., working_directory=... or harness=...)
   • Branch history → codetalk_branches / codetalk_diff_branches
3. codetalk_list — browse metadata; filter with working_directory and/or harness on busy machines.
4. codetalk_read with defaults — tail slice without system injections or raw_data.

Note: Codex CLI rollouts appear under harness chatgpt; use session_id for reads and conversation_id for branch tools.

Per-harness MCP onboarding

codetalk_capabilities and codetalk_info return server.project_root — update MCP config if it points at a stale scratch copy.

Context recovery (Freebuff-first)

Some harnesses lose in-flight prompt context while the full transcript remains on disk. Freebuff is the most common case: the agent may reply with "I can't see the session context…" even though desktop-v2.db still has every turn.

Symptom → fix

1. User says continue but the Freebuff agent is blind.
2. Call codetalk_resolve_session(working_directory="<project path>", harness="freebuff") to get the latest session_id for that repo.
3. Call codetalk_read(working_directory="<project path>", harness="freebuff", since_last_user_input=true) — or pass the resolved session_id — to recover what the user last asked and what the agent already did.
4. Optionally codetalk_search(query="can't see the session context", harness="freebuff") to find other threads that hit the same failure.

working_directory accepts plain paths (C:/path/to/myproject) or file:// URIs. Matching is normalized and case-insensitive on Windows. You do not need session_id when you know the project path — codetalk_read and codetalk_info accept working_directory directly.

Cross-harness recovery works too: open any harness with CodeTalker MCP configured (e.g. Cursor), point it at the Freebuff working_directory, and read the persisted transcript from there.

codetalk_capabilities returns the full recovery playbook in context_recovery.

v0.3: trigger-gated recovery + continue tokens

Since v0.3 the recovery mandate is trigger-gated and per-client:

• Per-client instructions. The handshake tailors instructions to the connecting client (via clientInfo.name): harnesses with known mid-thread context loss (Freebuff) receive the full marker-gated mandate; every other harness receives a short fallback. Healthy turns on any harness do zero recovery work.
• Mechanical wipe markers. Restart/failed-turn notices (<since_your_last_turn>, <failed_turn>, session-ended system notices) are detected in the transcript tail — no model judgment required for the loud class of wipes.
• Continue tokens. codetalk_recover now returns a continue_token line (codetalker-v3-continue {…}): an integrity-signed anchor (session, working directory, last user turn, transcript length). Agents end substantive turns with it; a later wiped turn passes it back as claimed_token, and the server verifies the agent's memory against the transcript on disk — anchors that were silently dropped or edited fail verification. codetalk_recover_token is the verification-only form. Silent mid-session wipes leave no transcript artifact, so their detection stays with the antecedent check — the token makes the recovery verifiable instead of guessed.
• Freebuff consent sidecar. codetalk_recover_token is new, so Freebuff requires a one-time tool re-approval in the Freebuff UI (remove and re-add the codetalker server) before the tool is callable there.

Installation & Setup

Install from PyPI

Published as codetalker-mcp (the name codetalker on PyPI belongs to an unrelated 2014 package):

pip install codetalker-mcp
# or
uv tool install codetalker-mcp

MCP config entries then need no repo path:

{
  "mcpServers": {
    "codetalker": {
      "command": "uvx",
      "args": ["--from", "codetalker-mcp", "codetalker"]
    }
  }
}

Running locally (development)

uv sync
uv run pytest -v
uv run codetalker --log-level INFO

Propagating MCP config after a move or clone

When the repo moves (e.g. to D:/codetalker), every harness MCP entry must point at the new path. Run the installer from the repo root:

.\scripts\install-harnesses.ps1 -ProjectRoot D:\codetalker

What it updates (when those config files exist on your machine):

Each file is backed up to *.bak before overwrite. Freebuff is not patched automatically — remove and re-add codetalker in the Freebuff client UI so a fresh MCP approval is minted (see script output for suggested command/args).

Optional path-independent mode (installs a global codetalker shim via uv):

.\scripts\install-harnesses.ps1 -UseUvTool

Limit to specific harnesses: -Harness Cursor,Codex. Preview changes: -WhatIf.

After running, restart each harness and call codetalk_capabilities — confirm server.project_root matches your install.

Cross-platform installer (macOS / Linux / any OS)

The same wiring logic ships as a stdlib-only Python entry point — usable immediately after pip install git+https://github.com/Ickleslimer/codetalker.git, no PowerShell required:

# preview what would change (default; modifies nothing)
codetalker-install --project-root /path/to/codetalker

# apply
codetalker-install --project-root /path/to/codetalker --write

# uv tool users (after: uv tool install /path/to/codetalker)
codetalker-install --uv-tool --write

Targets are the same as the PowerShell script (Cursor, Antigravity, Claude Desktop, Codex TOML) plus Freebuff desktop's launch registry (~/.agents/mcp.json, the path verified inside the Freebuff orchestrator bundle), which is created when missing and merged in place when present — so a fresh machine needs zero hand-editing. Existing codetalker entries are replaced in place, other MCP servers are preserved, every modified file gets a one-shot .bak backup, and CRLF line endings survive on Windows-written configs. The Claude Desktop config resolves to %APPDATA%\Claude\claude_desktop_config.json on Windows and ~/.claude/claude_desktop_config.json elsewhere.

One step always stays manual: after writing Freebuff's registry (or on first run), restart Freebuff and approve the codetalker manifest in the UI — the consent sidecar (~/.freebuff/mcp.json) is client-managed and its mutation endpoints are launch-token-gated by design. On Windows, either installer works; the PowerShell variant additionally offers uv tool install integration.

Adding to MCP Configuration (manual)

In your agent harness MCP config (e.g., Antigravity, Claude Desktop, Cursor):

{
  "mcpServers": {
    "codetalker": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/codetalker",
        "codetalker"
      ]
    }
  }
}

Development: the stranger-install smoke

CI (.github/workflows/stranger-smoke.yml) keeps the onboarding path honest on every push/PR: on ubuntu, macos, and windows runners it creates a fresh venv, installs the checked-out tree non-editable (exactly what pip install git+https://github.com/Ickleslimer/codetalker.git gives a stranger — CI deliberately installs from the tree rather than the GitHub URL, which would test the previous commit on push events), then runs scripts/stranger_smoke.py:

• stdio handshake + full tool catalog (core 8 tools present)
• v0.3 per-client instruction tailoring (freebuff mandate vs. short fallback)
• codetalk_capabilities answers, and its version matches the installed dist
• empty-home probe: with HOME/USERPROFILE/APPDATA/XDG_* redirected to an empty temp dir, capabilities and list answer gracefully (count: 0)

Run the same check locally against your editable install (skips the fresh-venv step but exercises the identical assertions):

uv pip install . && python scripts/stranger_smoke.py

Or replicate CI exactly:

uv venv .smoke-venv --python 3.12
uv pip install --python .smoke-venv/Scripts/python.exe .   # bin/python on posix
.smoke-venv/Scripts/python.exe scripts/stranger_smoke.py