Releases: Ickleslimer/codetalker
Release list
v0.3.7 — codetalker-mcp on PyPI
Release of the PyPI publication:
codetalker-mcp 0.3.7—
built and published by thepublish.yml
workflow via PyPI trusted publishing, gated on the stranger-install smoke.These notes are the live PyPI project description, fetched from the registry
at release time so this page and PyPI stay paired.
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.
Important
Privacy: read-only, local-only, no telemetry.
CodeTalker reads your agent harnesses' local conversation history and nothing else.
- Read-only by construction. Every harness database it touches (Cursor, Freebuff, OpenCode, Windsurf/Devin) is opened in SQLite read-only mode (
?mode=ro) — the driver itself refuses writes, so a bug in CodeTalker cannot modify your sessions. It writes no config files, keeps no cache, stores no state of its own. - What it touches. Only the harnesses' own storage directories listed in the support table below (e.g.
~/.codex/sessions,~/.config/freebuff-desktop,%APPDATA%/Cursor), plus local OpenCode desktop logs to discover that app's local server port. Nothing on your machine is modified. - Nothing is sent anywhere. The server speaks stdio only — it talks exclusively to the agent harness that launched it, on your machine. There is no telemetry, no analytics, no update checks. The one network-shaped exception is disclosed: the OpenCode sidecar adapter may issue a local HTTP GET to your own running OpenCode desktop app (port discovered from that app's local logs) to read session messages. No transcript data ever leaves your machine via CodeTalker — it leaves only if the agent harness you use sends tool results to its own model backend, which is outside CodeTalker's control.
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
| Harness | Aliases | Storage Locations | Test Status | Notes |
|---|---|---|---|---|
| OpenAI Codex CLI | codex, chatgpt |
~/.codex/sessions/**/rollout-*.jsonl, session_index.jsonl |
Live Verified | Tested across 480+ local CLI sessions with trailing timestamps and DAG resolution. |
| OpenAI ChatGPT Desktop | chatgpt |
%LOCALAPPDATA%/Packages/OpenAI.ChatGPT-Desktop_*/.../IndexedDB |
Live Verified | Tested via ccl-chromium-reader LevelDB parser. (See fragility disclaimer below). |
| ChatGPT Export DAG | chatgpt |
conversations.json (Export Archive) |
Live Verified | Linearizes branching conversation DAG trees into distinct threads. |
| Devin (formerly Windsurf) | devin, windsurf |
~/.codeium/chat_state/*.pb, state.vscdb |
Live Verified | Pure-Python wire-level Protobuf stream parser and workspace SQLite reader. |
| Freebuff | freebuff, codebuff |
~/.config/freebuff-desktop/projects/*/desktop-v2.db |
Live Verified | Full multi-turn conversation logs, reasoning traces, image attachments, and tool calls. |
| OpenCode Desktop | opencode, open_code |
%APPDATA%/ai.opencode.desktop/drafts.sqlite |
Live Verified | Decodes workspace paths, models, prompt histories, and active session drafts. (See notes below). |
| Google Antigravity | antigravity, agy |
~/.gemini/antigravity/brain/*/transcript.jsonl |
Live Verified | Real-time transcript logs, XML cleanup, subagent trees, thinking blocks, and checkpoints. |
| Cursor IDE | cursor |
%APPDATA%/Cursor/User/globalStorage/state.vscdb |
Live Verified | Scans composerHeaders across 50+ workspaces, bubbles, diffs, and reasoning traces. |
| Claude Code CLI | claude, claudecode |
~/.claude/projects/*/sessions/*.jsonl |
Fixture Tested (YMMV) | Implemented against Anthropic Messages API specs; not verified against an active local installation. |
| Aider Pair Programmer | aider |
.aider.chat.history.md, ~/.aider.chat.history.md |
Fixture Tested (YMMV) | Implemented for markdown chat logs and <<<< SEARCH ... === ... >>>> diffs; not installed locally. |
| GitHub Copilot Chat | copilot, github_copilot |
%APPDATA%/Code/User/workspaceStorage/*/chatSessions/*.jsonl |
Fixture Tested (YMMV) | Implemented for VSCode chat session JSONL logs; not verified against an active local installation. |
Stability, Fragility & Compatibility Disclaimers
Warning
ChatGPT Desktop App (LevelDB Cache) Fragility
The ChatGPT Desktop application uses Chromium IndexedDB / LevelDB to cache conversation state locally. This storage engine is unversioned, undocumented, and frequently modified by OpenAI between app updates.
- Recommendation: For reliable long-term retrieval, prefer Codex CLI rollouts (
~/.codex/sessions) or the official data export (conversations.json).
Note
OpenCode Desktop Cloud Streaming vs Local Drafts
OpenCode Desktop persists active drafts, models (grok, gpt-5.6, x-preview), and user prompt history in %APPDATA%/ai.opencode.desktop/drafts.sqlite. Because multi-turn assistant completions are rendered via live server-side WebSockets, local desktop records represent client-side prompts and active workspace drafts. Full multi-turn assistant outputs and tool executions are available if using OpenCode CLI JSONL logs (~/.opencode/sessions/*.jsonl).
Important
Cursor SQLite Schema Evolution
Cursor's internal storage schema in state.vscdb (composerHeaders, cursorDiskKV, composerData, bubbleId) evolves across Cursor releases. CodeTalker connects in read-only mode (?mode=ro) with schema fallbacks, but major upstream Cursor redesigns may require updating field mappings.
Tip
Fixture-Tested Adapters (YMMV)
The adapters for Claude Code CLI, Aider, and GitHub Copilot Chat have complete normalization logic verified by unit test fixtures, but have not been live-tested against active local installations on this machine. If you use these tools and encounter non-standard directory structures or version variations, use the root_path parameter to point CodeTalker directly to your transcript folder.
MCP Tools
| Tool | Parameters | Description |
|---|---|---|
codetalk_capabilities |
(none) | List harnesses, aliases, ID guidance, context-recovery playbook, and recommended read defaults. Call once per agent session. |
codetalk_list |
harness, conversation_id, working_directory, since, limit, root_path, include_capabilities, include_harness_status |
List sessions (slim by default). Filter by working_directory for project-scoped recovery. |
codetalk_resolve_session |
working_directory, harness, display_name, root_path, limit |
Resolve the most recent session for a project path when session_id is unknown (common Freebuff context-loss recovery). Optional display_name narrows by thread title. |
codetalk_read |
session_id, harness, working_directory, since, until, since_last_user_input, conversation_only, exclude_actor_roles, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Read normalized steps. Provide session_id or working_directory. Defaults: tail slice (from_end=true), conversation-only (conversation_only=true), no raw payloads (include_raw_data=false). |
codetalk_branches |
conversation_id, harness, root_path |
DAG branch tree, fork points, and subagent hierarchy (branch_id usually equals session_id). |
codetalk_diff_branches |
conversation_id, branch_a, branch_b, harness, summary_only, include_raw_data, limit_per_branch, from_end, root_path |
Compare branches. Defaults to summary_only=true (counts/metadata only). |
codetalk_filter |
session_id, harness, working_directory, keywords, step_types, actor_roles, conversation_only, exclude_actor_roles, since_last_user_input, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Filter steps by keywords, types, or roles. Accepts session_id or working_directory. |
codetalk_search |
query, harness, working_directory, since, limit, max_sessions_to_search, search_scope, root_path |
Search titles and transcript content. Pass working_directory or harness when scoped to one project. Title hits use match_type=title. |
codetalk_info |
session_id, harness, working_directory, root_path |
Fast metadata without step bodies (refreshes step counts when possible). Accepts session_id or working_directory. |
Agent quickstart
codetalk_capabilities— learn harness names, a...
v0.3.5 — codetalker-mcp on PyPI
Release of the PyPI publication:
codetalker-mcp 0.3.5—
built and published by thepublish.yml
workflow via PyPI trusted publishing, gated on the stranger-install smoke.These notes are the live PyPI project description, fetched from the registry
at release time so this page and PyPI stay paired.
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.
Important
Privacy: read-only, local-only, no telemetry.
CodeTalker reads your agent harnesses' local conversation history and nothing else.
- Read-only by construction. Every harness database it touches (Cursor, Freebuff, OpenCode, Windsurf/Devin) is opened in SQLite read-only mode (
?mode=ro) — the driver itself refuses writes, so a bug in CodeTalker cannot modify your sessions. It writes no config files, keeps no cache, stores no state of its own. - What it touches. Only the harnesses' own storage directories listed in the support table below (e.g.
~/.codex/sessions,~/.config/freebuff-desktop,%APPDATA%/Cursor), plus local OpenCode desktop logs to discover that app's local server port. Nothing on your machine is modified. - Nothing is sent anywhere. The server speaks stdio only — it talks exclusively to the agent harness that launched it, on your machine. There is no telemetry, no analytics, no update checks. The one network-shaped exception is disclosed: the OpenCode sidecar adapter may issue a local HTTP GET to your own running OpenCode desktop app (port discovered from that app's local logs) to read session messages. No transcript data ever leaves your machine via CodeTalker — it leaves only if the agent harness you use sends tool results to its own model backend, which is outside CodeTalker's control.
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
| Harness | Aliases | Storage Locations | Test Status | Notes |
|---|---|---|---|---|
| OpenAI Codex CLI | codex, chatgpt |
~/.codex/sessions/**/rollout-*.jsonl, session_index.jsonl |
Live Verified | Tested across 480+ local CLI sessions with trailing timestamps and DAG resolution. |
| OpenAI ChatGPT Desktop | chatgpt |
%LOCALAPPDATA%/Packages/OpenAI.ChatGPT-Desktop_*/.../IndexedDB |
Live Verified | Tested via ccl-chromium-reader LevelDB parser. (See fragility disclaimer below). |
| ChatGPT Export DAG | chatgpt |
conversations.json (Export Archive) |
Live Verified | Linearizes branching conversation DAG trees into distinct threads. |
| Devin (formerly Windsurf) | devin, windsurf |
~/.codeium/chat_state/*.pb, state.vscdb |
Live Verified | Pure-Python wire-level Protobuf stream parser and workspace SQLite reader. |
| Freebuff | freebuff, codebuff |
~/.config/freebuff-desktop/projects/*/desktop-v2.db |
Live Verified | Full multi-turn conversation logs, reasoning traces, image attachments, and tool calls. |
| OpenCode Desktop | opencode, open_code |
%APPDATA%/ai.opencode.desktop/drafts.sqlite |
Live Verified | Decodes workspace paths, models, prompt histories, and active session drafts. (See notes below). |
| Google Antigravity | antigravity, agy |
~/.gemini/antigravity/brain/*/transcript.jsonl |
Live Verified | Real-time transcript logs, XML cleanup, subagent trees, thinking blocks, and checkpoints. |
| Cursor IDE | cursor |
%APPDATA%/Cursor/User/globalStorage/state.vscdb |
Live Verified | Scans composerHeaders across 50+ workspaces, bubbles, diffs, and reasoning traces. |
| Claude Code CLI | claude, claudecode |
~/.claude/projects/*/sessions/*.jsonl |
Fixture Tested (YMMV) | Implemented against Anthropic Messages API specs; not verified against an active local installation. |
| Aider Pair Programmer | aider |
.aider.chat.history.md, ~/.aider.chat.history.md |
Fixture Tested (YMMV) | Implemented for markdown chat logs and <<<< SEARCH ... === ... >>>> diffs; not installed locally. |
| GitHub Copilot Chat | copilot, github_copilot |
%APPDATA%/Code/User/workspaceStorage/*/chatSessions/*.jsonl |
Fixture Tested (YMMV) | Implemented for VSCode chat session JSONL logs; not verified against an active local installation. |
Stability, Fragility & Compatibility Disclaimers
Warning
ChatGPT Desktop App (LevelDB Cache) Fragility
The ChatGPT Desktop application uses Chromium IndexedDB / LevelDB to cache conversation state locally. This storage engine is unversioned, undocumented, and frequently modified by OpenAI between app updates.
- Recommendation: For reliable long-term retrieval, prefer Codex CLI rollouts (
~/.codex/sessions) or the official data export (conversations.json).
Note
OpenCode Desktop Cloud Streaming vs Local Drafts
OpenCode Desktop persists active drafts, models (grok, gpt-5.6, x-preview), and user prompt history in %APPDATA%/ai.opencode.desktop/drafts.sqlite. Because multi-turn assistant completions are rendered via live server-side WebSockets, local desktop records represent client-side prompts and active workspace drafts. Full multi-turn assistant outputs and tool executions are available if using OpenCode CLI JSONL logs (~/.opencode/sessions/*.jsonl).
Important
Cursor SQLite Schema Evolution
Cursor's internal storage schema in state.vscdb (composerHeaders, cursorDiskKV, composerData, bubbleId) evolves across Cursor releases. CodeTalker connects in read-only mode (?mode=ro) with schema fallbacks, but major upstream Cursor redesigns may require updating field mappings.
Tip
Fixture-Tested Adapters (YMMV)
The adapters for Claude Code CLI, Aider, and GitHub Copilot Chat have complete normalization logic verified by unit test fixtures, but have not been live-tested against active local installations on this machine. If you use these tools and encounter non-standard directory structures or version variations, use the root_path parameter to point CodeTalker directly to your transcript folder.
MCP Tools
| Tool | Parameters | Description |
|---|---|---|
codetalk_capabilities |
(none) | List harnesses, aliases, ID guidance, context-recovery playbook, and recommended read defaults. Call once per agent session. |
codetalk_list |
harness, conversation_id, working_directory, since, limit, root_path, include_capabilities, include_harness_status |
List sessions (slim by default). Filter by working_directory for project-scoped recovery. |
codetalk_resolve_session |
working_directory, harness, display_name, root_path, limit |
Resolve the most recent session for a project path when session_id is unknown (common Freebuff context-loss recovery). Optional display_name narrows by thread title. |
codetalk_read |
session_id, harness, working_directory, since, until, since_last_user_input, conversation_only, exclude_actor_roles, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Read normalized steps. Provide session_id or working_directory. Defaults: tail slice (from_end=true), conversation-only (conversation_only=true), no raw payloads (include_raw_data=false). |
codetalk_branches |
conversation_id, harness, root_path |
DAG branch tree, fork points, and subagent hierarchy (branch_id usually equals session_id). |
codetalk_diff_branches |
conversation_id, branch_a, branch_b, harness, summary_only, include_raw_data, limit_per_branch, from_end, root_path |
Compare branches. Defaults to summary_only=true (counts/metadata only). |
codetalk_filter |
session_id, harness, working_directory, keywords, step_types, actor_roles, conversation_only, exclude_actor_roles, since_last_user_input, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Filter steps by keywords, types, or roles. Accepts session_id or working_directory. |
codetalk_search |
query, harness, working_directory, since, limit, max_sessions_to_search, search_scope, root_path |
Search titles and transcript content. Pass working_directory or harness when scoped to one project. Title hits use match_type=title. |
codetalk_info |
session_id, harness, working_directory, root_path |
Fast metadata without step bodies (refreshes step counts when possible). Accepts session_id or working_directory. |
Agent quickstart
codetalk_capabilities— learn harness names, a...
v0.3.4 — codetalker-mcp on PyPI
Release of the PyPI publication:
codetalker-mcp 0.3.4—
built and published by thepublish.yml
workflow via PyPI trusted publishing, gated on the stranger-install smoke.These notes are the live PyPI project description, fetched from the registry
at release time so this page and PyPI stay paired.
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.
Important
Privacy: read-only, local-only, no telemetry.
CodeTalker reads your agent harnesses' local conversation history and nothing else.
- Read-only by construction. Every harness database it touches (Cursor, Freebuff, OpenCode, Windsurf/Devin) is opened in SQLite read-only mode (
?mode=ro) — the driver itself refuses writes, so a bug in CodeTalker cannot modify your sessions. It writes no config files, keeps no cache, stores no state of its own. - What it touches. Only the harnesses' own storage directories listed in the support table below (e.g.
~/.codex/sessions,~/.config/freebuff-desktop,%APPDATA%/Cursor), plus local OpenCode desktop logs to discover that app's local server port. Nothing on your machine is modified. - Nothing is sent anywhere. The server speaks stdio only — it talks exclusively to the agent harness that launched it, on your machine. There is no telemetry, no analytics, no update checks. The one network-shaped exception is disclosed: the OpenCode sidecar adapter may issue a local HTTP GET to your own running OpenCode desktop app (port discovered from that app's local logs) to read session messages. No transcript data ever leaves your machine via CodeTalker — it leaves only if the agent harness you use sends tool results to its own model backend, which is outside CodeTalker's control.
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
| Harness | Aliases | Storage Locations | Test Status | Notes |
|---|---|---|---|---|
| OpenAI Codex CLI | codex, chatgpt |
~/.codex/sessions/**/rollout-*.jsonl, session_index.jsonl |
Live Verified | Tested across 480+ local CLI sessions with trailing timestamps and DAG resolution. |
| OpenAI ChatGPT Desktop | chatgpt |
%LOCALAPPDATA%/Packages/OpenAI.ChatGPT-Desktop_*/.../IndexedDB |
Live Verified | Tested via ccl-chromium-reader LevelDB parser. (See fragility disclaimer below). |
| ChatGPT Export DAG | chatgpt |
conversations.json (Export Archive) |
Live Verified | Linearizes branching conversation DAG trees into distinct threads. |
| Devin (formerly Windsurf) | devin, windsurf |
~/.codeium/chat_state/*.pb, state.vscdb |
Live Verified | Pure-Python wire-level Protobuf stream parser and workspace SQLite reader. |
| Freebuff | freebuff, codebuff |
~/.config/freebuff-desktop/projects/*/desktop-v2.db |
Live Verified | Full multi-turn conversation logs, reasoning traces, image attachments, and tool calls. |
| OpenCode Desktop | opencode, open_code |
%APPDATA%/ai.opencode.desktop/drafts.sqlite |
Live Verified | Decodes workspace paths, models, prompt histories, and active session drafts. (See notes below). |
| Google Antigravity | antigravity, agy |
~/.gemini/antigravity/brain/*/transcript.jsonl |
Live Verified | Real-time transcript logs, XML cleanup, subagent trees, thinking blocks, and checkpoints. |
| Cursor IDE | cursor |
%APPDATA%/Cursor/User/globalStorage/state.vscdb |
Live Verified | Scans composerHeaders across 50+ workspaces, bubbles, diffs, and reasoning traces. |
| Claude Code CLI | claude, claudecode |
~/.claude/projects/*/sessions/*.jsonl |
Fixture Tested (YMMV) | Implemented against Anthropic Messages API specs; not verified against an active local installation. |
| Aider Pair Programmer | aider |
.aider.chat.history.md, ~/.aider.chat.history.md |
Fixture Tested (YMMV) | Implemented for markdown chat logs and <<<< SEARCH ... === ... >>>> diffs; not installed locally. |
| GitHub Copilot Chat | copilot, github_copilot |
%APPDATA%/Code/User/workspaceStorage/*/chatSessions/*.jsonl |
Fixture Tested (YMMV) | Implemented for VSCode chat session JSONL logs; not verified against an active local installation. |
Stability, Fragility & Compatibility Disclaimers
Warning
ChatGPT Desktop App (LevelDB Cache) Fragility
The ChatGPT Desktop application uses Chromium IndexedDB / LevelDB to cache conversation state locally. This storage engine is unversioned, undocumented, and frequently modified by OpenAI between app updates.
- Recommendation: For reliable long-term retrieval, prefer Codex CLI rollouts (
~/.codex/sessions) or the official data export (conversations.json).
Note
OpenCode Desktop Cloud Streaming vs Local Drafts
OpenCode Desktop persists active drafts, models (grok, gpt-5.6, x-preview), and user prompt history in %APPDATA%/ai.opencode.desktop/drafts.sqlite. Because multi-turn assistant completions are rendered via live server-side WebSockets, local desktop records represent client-side prompts and active workspace drafts. Full multi-turn assistant outputs and tool executions are available if using OpenCode CLI JSONL logs (~/.opencode/sessions/*.jsonl).
Important
Cursor SQLite Schema Evolution
Cursor's internal storage schema in state.vscdb (composerHeaders, cursorDiskKV, composerData, bubbleId) evolves across Cursor releases. CodeTalker connects in read-only mode (?mode=ro) with schema fallbacks, but major upstream Cursor redesigns may require updating field mappings.
Tip
Fixture-Tested Adapters (YMMV)
The adapters for Claude Code CLI, Aider, and GitHub Copilot Chat have complete normalization logic verified by unit test fixtures, but have not been live-tested against active local installations on this machine. If you use these tools and encounter non-standard directory structures or version variations, use the root_path parameter to point CodeTalker directly to your transcript folder.
MCP Tools
| Tool | Parameters | Description |
|---|---|---|
codetalk_capabilities |
(none) | List harnesses, aliases, ID guidance, context-recovery playbook, and recommended read defaults. Call once per agent session. |
codetalk_list |
harness, conversation_id, working_directory, since, limit, root_path, include_capabilities, include_harness_status |
List sessions (slim by default). Filter by working_directory for project-scoped recovery. |
codetalk_resolve_session |
working_directory, harness, display_name, root_path, limit |
Resolve the most recent session for a project path when session_id is unknown (common Freebuff context-loss recovery). Optional display_name narrows by thread title. |
codetalk_read |
session_id, harness, working_directory, since, until, since_last_user_input, conversation_only, exclude_actor_roles, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Read normalized steps. Provide session_id or working_directory. Defaults: tail slice (from_end=true), conversation-only (conversation_only=true), no raw payloads (include_raw_data=false). |
codetalk_branches |
conversation_id, harness, root_path |
DAG branch tree, fork points, and subagent hierarchy (branch_id usually equals session_id). |
codetalk_diff_branches |
conversation_id, branch_a, branch_b, harness, summary_only, include_raw_data, limit_per_branch, from_end, root_path |
Compare branches. Defaults to summary_only=true (counts/metadata only). |
codetalk_filter |
session_id, harness, working_directory, keywords, step_types, actor_roles, conversation_only, exclude_actor_roles, since_last_user_input, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Filter steps by keywords, types, or roles. Accepts session_id or working_directory. |
codetalk_search |
query, harness, working_directory, since, limit, max_sessions_to_search, search_scope, root_path |
Search titles and transcript content. Pass working_directory or harness when scoped to one project. Title hits use match_type=title. |
codetalk_info |
session_id, harness, working_directory, root_path |
Fast metadata without step bodies (refreshes step counts when possible). Accepts session_id or working_directory. |
Agent quickstart
codetalk_capabilities— learn harness names, a...
v0.3.3 — codetalker-mcp on PyPI
Release of the PyPI publication:
codetalker-mcp 0.3.3—
built and published by thepublish.yml
workflow via PyPI trusted publishing, gated on the stranger-install smoke.These notes are the live PyPI project description, fetched from the registry
at release time so this page and PyPI stay paired.
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.
Important
Privacy: read-only, local-only, no telemetry.
CodeTalker reads your agent harnesses' local conversation history and nothing else.
- Read-only by construction. Every harness database it touches (Cursor, Freebuff, OpenCode, Windsurf/Devin) is opened in SQLite read-only mode (
?mode=ro) — the driver itself refuses writes, so a bug in CodeTalker cannot modify your sessions. It writes no config files, keeps no cache, stores no state of its own. - What it touches. Only the harnesses' own storage directories listed in the support table below (e.g.
~/.codex/sessions,~/.config/freebuff-desktop,%APPDATA%/Cursor), plus local OpenCode desktop logs to discover that app's local server port. Nothing on your machine is modified. - Nothing is sent anywhere. The server speaks stdio only — it talks exclusively to the agent harness that launched it, on your machine. There is no telemetry, no analytics, no update checks. The one network-shaped exception is disclosed: the OpenCode sidecar adapter may issue a local HTTP GET to your own running OpenCode desktop app (port discovered from that app's local logs) to read session messages. No transcript data ever leaves your machine via CodeTalker — it leaves only if the agent harness you use sends tool results to its own model backend, which is outside CodeTalker's control.
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
| Harness | Aliases | Storage Locations | Test Status | Notes |
|---|---|---|---|---|
| OpenAI Codex CLI | codex, chatgpt |
~/.codex/sessions/**/rollout-*.jsonl, session_index.jsonl |
Live Verified | Tested across 480+ local CLI sessions with trailing timestamps and DAG resolution. |
| OpenAI ChatGPT Desktop | chatgpt |
%LOCALAPPDATA%/Packages/OpenAI.ChatGPT-Desktop_*/.../IndexedDB |
Live Verified | Tested via ccl-chromium-reader LevelDB parser. (See fragility disclaimer below). |
| ChatGPT Export DAG | chatgpt |
conversations.json (Export Archive) |
Live Verified | Linearizes branching conversation DAG trees into distinct threads. |
| Devin (formerly Windsurf) | devin, windsurf |
~/.codeium/chat_state/*.pb, state.vscdb |
Live Verified | Pure-Python wire-level Protobuf stream parser and workspace SQLite reader. |
| Freebuff | freebuff, codebuff |
~/.config/freebuff-desktop/projects/*/desktop-v2.db |
Live Verified | Full multi-turn conversation logs, reasoning traces, image attachments, and tool calls. |
| OpenCode Desktop | opencode, open_code |
%APPDATA%/ai.opencode.desktop/drafts.sqlite |
Live Verified | Decodes workspace paths, models, prompt histories, and active session drafts. (See notes below). |
| Google Antigravity | antigravity, agy |
~/.gemini/antigravity/brain/*/transcript.jsonl |
Live Verified | Real-time transcript logs, XML cleanup, subagent trees, thinking blocks, and checkpoints. |
| Cursor IDE | cursor |
%APPDATA%/Cursor/User/globalStorage/state.vscdb |
Live Verified | Scans composerHeaders across 50+ workspaces, bubbles, diffs, and reasoning traces. |
| Claude Code CLI | claude, claudecode |
~/.claude/projects/*/sessions/*.jsonl |
Fixture Tested (YMMV) | Implemented against Anthropic Messages API specs; not verified against an active local installation. |
| Aider Pair Programmer | aider |
.aider.chat.history.md, ~/.aider.chat.history.md |
Fixture Tested (YMMV) | Implemented for markdown chat logs and <<<< SEARCH ... === ... >>>> diffs; not installed locally. |
| GitHub Copilot Chat | copilot, github_copilot |
%APPDATA%/Code/User/workspaceStorage/*/chatSessions/*.jsonl |
Fixture Tested (YMMV) | Implemented for VSCode chat session JSONL logs; not verified against an active local installation. |
Stability, Fragility & Compatibility Disclaimers
Warning
ChatGPT Desktop App (LevelDB Cache) Fragility
The ChatGPT Desktop application uses Chromium IndexedDB / LevelDB to cache conversation state locally. This storage engine is unversioned, undocumented, and frequently modified by OpenAI between app updates.
- Recommendation: For reliable long-term retrieval, prefer Codex CLI rollouts (
~/.codex/sessions) or the official data export (conversations.json).
Note
OpenCode Desktop Cloud Streaming vs Local Drafts
OpenCode Desktop persists active drafts, models (grok, gpt-5.6, x-preview), and user prompt history in %APPDATA%/ai.opencode.desktop/drafts.sqlite. Because multi-turn assistant completions are rendered via live server-side WebSockets, local desktop records represent client-side prompts and active workspace drafts. Full multi-turn assistant outputs and tool executions are available if using OpenCode CLI JSONL logs (~/.opencode/sessions/*.jsonl).
Important
Cursor SQLite Schema Evolution
Cursor's internal storage schema in state.vscdb (composerHeaders, cursorDiskKV, composerData, bubbleId) evolves across Cursor releases. CodeTalker connects in read-only mode (?mode=ro) with schema fallbacks, but major upstream Cursor redesigns may require updating field mappings.
Tip
Fixture-Tested Adapters (YMMV)
The adapters for Claude Code CLI, Aider, and GitHub Copilot Chat have complete normalization logic verified by unit test fixtures, but have not been live-tested against active local installations on this machine. If you use these tools and encounter non-standard directory structures or version variations, use the root_path parameter to point CodeTalker directly to your transcript folder.
MCP Tools
| Tool | Parameters | Description |
|---|---|---|
codetalk_capabilities |
(none) | List harnesses, aliases, ID guidance, context-recovery playbook, and recommended read defaults. Call once per agent session. |
codetalk_list |
harness, conversation_id, working_directory, since, limit, root_path, include_capabilities, include_harness_status |
List sessions (slim by default). Filter by working_directory for project-scoped recovery. |
codetalk_resolve_session |
working_directory, harness, display_name, root_path, limit |
Resolve the most recent session for a project path when session_id is unknown (common Freebuff context-loss recovery). Optional display_name narrows by thread title. |
codetalk_read |
session_id, harness, working_directory, since, until, since_last_user_input, conversation_only, exclude_actor_roles, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Read normalized steps. Provide session_id or working_directory. Defaults: tail slice (from_end=true), conversation-only (conversation_only=true), no raw payloads (include_raw_data=false). |
codetalk_branches |
conversation_id, harness, root_path |
DAG branch tree, fork points, and subagent hierarchy (branch_id usually equals session_id). |
codetalk_diff_branches |
conversation_id, branch_a, branch_b, harness, summary_only, include_raw_data, limit_per_branch, from_end, root_path |
Compare branches. Defaults to summary_only=true (counts/metadata only). |
codetalk_filter |
session_id, harness, working_directory, keywords, step_types, actor_roles, conversation_only, exclude_actor_roles, since_last_user_input, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Filter steps by keywords, types, or roles. Accepts session_id or working_directory. |
codetalk_search |
query, harness, working_directory, since, limit, max_sessions_to_search, search_scope, root_path |
Search titles and transcript content. Pass working_directory or harness when scoped to one project. Title hits use match_type=title. |
codetalk_info |
session_id, harness, working_directory, root_path |
Fast metadata without step bodies (refreshes step counts when possible). Accepts session_id or working_directory. |
Agent quickstart
codetalk_capabilities— learn harness names, a...
v0.3.2 — codetalker-mcp on PyPI
Release of the PyPI publication:
codetalker-mcp 0.3.2—
built and published by thepublish.yml
workflow via PyPI trusted publishing, gated on the stranger-install smoke.These notes are the live PyPI project description, fetched from the registry
at release time so this page and PyPI stay paired.
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.
Important
Privacy: read-only, local-only, no telemetry.
CodeTalker reads your agent harnesses' local conversation history and nothing else.
- Read-only by construction. Every harness database it touches (Cursor, Freebuff, OpenCode, Windsurf/Devin) is opened in SQLite read-only mode (
?mode=ro) — the driver itself refuses writes, so a bug in CodeTalker cannot modify your sessions. It writes no config files, keeps no cache, stores no state of its own. - What it touches. Only the harnesses' own storage directories listed in the support table below (e.g.
~/.codex/sessions,~/.config/freebuff-desktop,%APPDATA%/Cursor), plus local OpenCode desktop logs to discover that app's local server port. Nothing on your machine is modified. - Nothing is sent anywhere. The server speaks stdio only — it talks exclusively to the agent harness that launched it, on your machine. There is no telemetry, no analytics, no update checks. The one network-shaped exception is disclosed: the OpenCode sidecar adapter may issue a local HTTP GET to your own running OpenCode desktop app (port discovered from that app's local logs) to read session messages. No transcript data ever leaves your machine via CodeTalker — it leaves only if the agent harness you use sends tool results to its own model backend, which is outside CodeTalker's control.
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
| Harness | Aliases | Storage Locations | Test Status | Notes |
|---|---|---|---|---|
| OpenAI Codex CLI | codex, chatgpt |
~/.codex/sessions/**/rollout-*.jsonl, session_index.jsonl |
Live Verified | Tested across 480+ local CLI sessions with trailing timestamps and DAG resolution. |
| OpenAI ChatGPT Desktop | chatgpt |
%LOCALAPPDATA%/Packages/OpenAI.ChatGPT-Desktop_*/.../IndexedDB |
Live Verified | Tested via ccl-chromium-reader LevelDB parser. (See fragility disclaimer below). |
| ChatGPT Export DAG | chatgpt |
conversations.json (Export Archive) |
Live Verified | Linearizes branching conversation DAG trees into distinct threads. |
| Devin (formerly Windsurf) | devin, windsurf |
~/.codeium/chat_state/*.pb, state.vscdb |
Live Verified | Pure-Python wire-level Protobuf stream parser and workspace SQLite reader. |
| Freebuff | freebuff, codebuff |
~/.config/freebuff-desktop/projects/*/desktop-v2.db |
Live Verified | Full multi-turn conversation logs, reasoning traces, image attachments, and tool calls. |
| OpenCode Desktop | opencode, open_code |
%APPDATA%/ai.opencode.desktop/drafts.sqlite |
Live Verified | Decodes workspace paths, models, prompt histories, and active session drafts. (See notes below). |
| Google Antigravity | antigravity, agy |
~/.gemini/antigravity/brain/*/transcript.jsonl |
Live Verified | Real-time transcript logs, XML cleanup, subagent trees, thinking blocks, and checkpoints. |
| Cursor IDE | cursor |
%APPDATA%/Cursor/User/globalStorage/state.vscdb |
Live Verified | Scans composerHeaders across 50+ workspaces, bubbles, diffs, and reasoning traces. |
| Claude Code CLI | claude, claudecode |
~/.claude/projects/*/sessions/*.jsonl |
Fixture Tested (YMMV) | Implemented against Anthropic Messages API specs; not verified against an active local installation. |
| Aider Pair Programmer | aider |
.aider.chat.history.md, ~/.aider.chat.history.md |
Fixture Tested (YMMV) | Implemented for markdown chat logs and <<<< SEARCH ... === ... >>>> diffs; not installed locally. |
| GitHub Copilot Chat | copilot, github_copilot |
%APPDATA%/Code/User/workspaceStorage/*/chatSessions/*.jsonl |
Fixture Tested (YMMV) | Implemented for VSCode chat session JSONL logs; not verified against an active local installation. |
Stability, Fragility & Compatibility Disclaimers
Warning
ChatGPT Desktop App (LevelDB Cache) Fragility
The ChatGPT Desktop application uses Chromium IndexedDB / LevelDB to cache conversation state locally. This storage engine is unversioned, undocumented, and frequently modified by OpenAI between app updates.
- Recommendation: For reliable long-term retrieval, prefer Codex CLI rollouts (
~/.codex/sessions) or the official data export (conversations.json).
Note
OpenCode Desktop Cloud Streaming vs Local Drafts
OpenCode Desktop persists active drafts, models (grok, gpt-5.6, x-preview), and user prompt history in %APPDATA%/ai.opencode.desktop/drafts.sqlite. Because multi-turn assistant completions are rendered via live server-side WebSockets, local desktop records represent client-side prompts and active workspace drafts. Full multi-turn assistant outputs and tool executions are available if using OpenCode CLI JSONL logs (~/.opencode/sessions/*.jsonl).
Important
Cursor SQLite Schema Evolution
Cursor's internal storage schema in state.vscdb (composerHeaders, cursorDiskKV, composerData, bubbleId) evolves across Cursor releases. CodeTalker connects in read-only mode (?mode=ro) with schema fallbacks, but major upstream Cursor redesigns may require updating field mappings.
Tip
Fixture-Tested Adapters (YMMV)
The adapters for Claude Code CLI, Aider, and GitHub Copilot Chat have complete normalization logic verified by unit test fixtures, but have not been live-tested against active local installations on this machine. If you use these tools and encounter non-standard directory structures or version variations, use the root_path parameter to point CodeTalker directly to your transcript folder.
MCP Tools
| Tool | Parameters | Description |
|---|---|---|
codetalk_capabilities |
(none) | List harnesses, aliases, ID guidance, context-recovery playbook, and recommended read defaults. Call once per agent session. |
codetalk_list |
harness, conversation_id, working_directory, since, limit, root_path, include_capabilities, include_harness_status |
List sessions (slim by default). Filter by working_directory for project-scoped recovery. |
codetalk_resolve_session |
working_directory, harness, display_name, root_path, limit |
Resolve the most recent session for a project path when session_id is unknown (common Freebuff context-loss recovery). Optional display_name narrows by thread title. |
codetalk_read |
session_id, harness, working_directory, since, until, since_last_user_input, conversation_only, exclude_actor_roles, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Read normalized steps. Provide session_id or working_directory. Defaults: tail slice (from_end=true), conversation-only (conversation_only=true), no raw payloads (include_raw_data=false). |
codetalk_branches |
conversation_id, harness, root_path |
DAG branch tree, fork points, and subagent hierarchy (branch_id usually equals session_id). |
codetalk_diff_branches |
conversation_id, branch_a, branch_b, harness, summary_only, include_raw_data, limit_per_branch, from_end, root_path |
Compare branches. Defaults to summary_only=true (counts/metadata only). |
codetalk_filter |
session_id, harness, working_directory, keywords, step_types, actor_roles, conversation_only, exclude_actor_roles, since_last_user_input, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Filter steps by keywords, types, or roles. Accepts session_id or working_directory. |
codetalk_search |
query, harness, working_directory, since, limit, max_sessions_to_search, search_scope, root_path |
Search titles and transcript content. Pass working_directory or harness when scoped to one project. Title hits use match_type=title. |
codetalk_info |
session_id, harness, working_directory, root_path |
Fast metadata without step bodies (refreshes step counts when possible). Accepts session_id or working_directory. |
Agent quickstart
codetalk_capabilities— learn harness names, aliases, tool catalog, and unsupported hallucinated names (read_transcript, etc.).- 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....
- Lost context + know project path →
v0.3.1 — codetalker-mcp on PyPI (first PyPI release)
Release of the first PyPI publication:
codetalker-mcp 0.3.1— built and published by thepublish.ymlworkflow via PyPI trusted publishing, gated on the stranger-install smoke.The notes below are the live PyPI project description, fetched from the registry at release time so this page and PyPI stay paired.
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.
Important
Privacy: read-only, local-only, no telemetry.
CodeTalker reads your agent harnesses' local conversation history and nothing else.
- Read-only by construction. Every harness database it touches (Cursor, Freebuff, OpenCode, Windsurf/Devin) is opened in SQLite read-only mode (
?mode=ro) — the driver itself refuses writes, so a bug in CodeTalker cannot modify your sessions. It writes no config files, keeps no cache, stores no state of its own. - What it touches. Only the harnesses' own storage directories listed in the support table below (e.g.
~/.codex/sessions,~/.config/freebuff-desktop,%APPDATA%/Cursor), plus local OpenCode desktop logs to discover that app's local server port. Nothing on your machine is modified. - Nothing is sent anywhere. The server speaks stdio only — it talks exclusively to the agent harness that launched it, on your machine. There is no telemetry, no analytics, no update checks. The one network-shaped exception is disclosed: the OpenCode sidecar adapter may issue a local HTTP GET to your own running OpenCode desktop app (port discovered from that app's local logs) to read session messages. No transcript data ever leaves your machine via CodeTalker — it leaves only if the agent harness you use sends tool results to its own model backend, which is outside CodeTalker's control.
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
| Harness | Aliases | Storage Locations | Test Status | Notes |
|---|---|---|---|---|
| OpenAI Codex CLI | codex, chatgpt |
~/.codex/sessions/**/rollout-*.jsonl, session_index.jsonl |
Live Verified | Tested across 480+ local CLI sessions with trailing timestamps and DAG resolution. |
| OpenAI ChatGPT Desktop | chatgpt |
%LOCALAPPDATA%/Packages/OpenAI.ChatGPT-Desktop_*/.../IndexedDB |
Live Verified | Tested via ccl-chromium-reader LevelDB parser. (See fragility disclaimer below). |
| ChatGPT Export DAG | chatgpt |
conversations.json (Export Archive) |
Live Verified | Linearizes branching conversation DAG trees into distinct threads. |
| Devin (formerly Windsurf) | devin, windsurf |
~/.codeium/chat_state/*.pb, state.vscdb |
Live Verified | Pure-Python wire-level Protobuf stream parser and workspace SQLite reader. |
| Freebuff | freebuff, codebuff |
~/.config/freebuff-desktop/projects/*/desktop-v2.db |
Live Verified | Full multi-turn conversation logs, reasoning traces, image attachments, and tool calls. |
| OpenCode Desktop | opencode, open_code |
%APPDATA%/ai.opencode.desktop/drafts.sqlite |
Live Verified | Decodes workspace paths, models, prompt histories, and active session drafts. (See notes below). |
| Google Antigravity | antigravity, agy |
~/.gemini/antigravity/brain/*/transcript.jsonl |
Live Verified | Real-time transcript logs, XML cleanup, subagent trees, thinking blocks, and checkpoints. |
| Cursor IDE | cursor |
%APPDATA%/Cursor/User/globalStorage/state.vscdb |
Live Verified | Scans composerHeaders across 50+ workspaces, bubbles, diffs, and reasoning traces. |
| Claude Code CLI | claude, claudecode |
~/.claude/projects/*/sessions/*.jsonl |
Fixture Tested (YMMV) | Implemented against Anthropic Messages API specs; not verified against an active local installation. |
| Aider Pair Programmer | aider |
.aider.chat.history.md, ~/.aider.chat.history.md |
Fixture Tested (YMMV) | Implemented for markdown chat logs and <<<< SEARCH ... === ... >>>> diffs; not installed locally. |
| GitHub Copilot Chat | copilot, github_copilot |
%APPDATA%/Code/User/workspaceStorage/*/chatSessions/*.jsonl |
Fixture Tested (YMMV) | Implemented for VSCode chat session JSONL logs; not verified against an active local installation. |
Stability, Fragility & Compatibility Disclaimers
Warning
ChatGPT Desktop App (LevelDB Cache) Fragility
The ChatGPT Desktop application uses Chromium IndexedDB / LevelDB to cache conversation state locally. This storage engine is unversioned, undocumented, and frequently modified by OpenAI between app updates.
- Recommendation: For reliable long-term retrieval, prefer Codex CLI rollouts (
~/.codex/sessions) or the official data export (conversations.json).
Note
OpenCode Desktop Cloud Streaming vs Local Drafts
OpenCode Desktop persists active drafts, models (grok, gpt-5.6, x-preview), and user prompt history in %APPDATA%/ai.opencode.desktop/drafts.sqlite. Because multi-turn assistant completions are rendered via live server-side WebSockets, local desktop records represent client-side prompts and active workspace drafts. Full multi-turn assistant outputs and tool executions are available if using OpenCode CLI JSONL logs (~/.opencode/sessions/*.jsonl).
Important
Cursor SQLite Schema Evolution
Cursor's internal storage schema in state.vscdb (composerHeaders, cursorDiskKV, composerData, bubbleId) evolves across Cursor releases. CodeTalker connects in read-only mode (?mode=ro) with schema fallbacks, but major upstream Cursor redesigns may require updating field mappings.
Tip
Fixture-Tested Adapters (YMMV)
The adapters for Claude Code CLI, Aider, and GitHub Copilot Chat have complete normalization logic verified by unit test fixtures, but have not been live-tested against active local installations on this machine. If you use these tools and encounter non-standard directory structures or version variations, use the root_path parameter to point CodeTalker directly to your transcript folder.
MCP Tools
| Tool | Parameters | Description |
|---|---|---|
codetalk_capabilities |
(none) | List harnesses, aliases, ID guidance, context-recovery playbook, and recommended read defaults. Call once per agent session. |
codetalk_list |
harness, conversation_id, working_directory, since, limit, root_path, include_capabilities, include_harness_status |
List sessions (slim by default). Filter by working_directory for project-scoped recovery. |
codetalk_resolve_session |
working_directory, harness, display_name, root_path, limit |
Resolve the most recent session for a project path when session_id is unknown (common Freebuff context-loss recovery). Optional display_name narrows by thread title. |
codetalk_read |
session_id, harness, working_directory, since, until, since_last_user_input, conversation_only, exclude_actor_roles, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Read normalized steps. Provide session_id or working_directory. Defaults: tail slice (from_end=true), conversation-only (conversation_only=true), no raw payloads (include_raw_data=false). |
codetalk_branches |
conversation_id, harness, root_path |
DAG branch tree, fork points, and subagent hierarchy (branch_id usually equals session_id). |
codetalk_diff_branches |
conversation_id, branch_a, branch_b, harness, summary_only, include_raw_data, limit_per_branch, from_end, root_path |
Compare branches. Defaults to summary_only=true (counts/metadata only). |
codetalk_filter |
session_id, harness, working_directory, keywords, step_types, actor_roles, conversation_only, exclude_actor_roles, since_last_user_input, include_thinking, include_raw_data, max_step_chars, offset, from_end, limit, root_path |
Filter steps by keywords, types, or roles. Accepts session_id or working_directory. |
codetalk_search |
query, harness, working_directory, since, limit, max_sessions_to_search, search_scope, root_path |
Search titles and transcript content. Pass working_directory or harness when scoped to one project. Title hits use match_type=title. |
codetalk_info |
session_id, harness, working_directory, root_path |
Fast metadata without step bodies (refreshes step counts when possible). Accepts session_id or working_directory. |
Agent quickstart
codetalk_capabilities— learn harness names, aliases, tool catalog, and unsupported hallucinated names (read_transcript, etc.).- 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_director...
- Lost context + know project path →
v0.3.0 — Trigger-gated recovery, per-client instructions, continue tokens
Highlights
Trigger-gated recovery (mechanical, not judgment-based)
Restart and failed-turn wipe notices (<since_your_last_turn>, <failed_turn>, session-ended system strings, Freebuff auto-resume sentinels) are now detected mechanically from the transcript tail. detect_session_fresh scans USER/SYSTEM steps only, so assistant text merely quoting a marker cannot trip it. Recovery fires when memory was actually lost — healthy turns do zero recovery work.
Per-client instructions
The server tailors its MCP instructions to each connecting client via clientInfo.name: Freebuff-class clients receive the full marker-gated mandate; every other harness gets a ~46% shorter fallback with no per-turn vigilance duty. The implementation patches ServerRunner._handle_initialize — middleware swapping server.instructions is impossible in this SDK (read-only property; init_options snapshotted before any message flows).
Continue tokens (verifiable recovery for silent wipes)
Silent mid-session wipes leave no transcript artifact, so detection stays with the antecedent check — but recovery is now verifiable. codetalk_recover returns a signed codetalker-v3-continue anchor (session, working dir, last user turn, transcript length). The agent ends turns with it; a later wiped turn passes it back as claimed_token, and the server proves or refutes the agent's memory against disk. New codetalk_recover_token is the verification-only form.
Measurement (v0.2 baseline vs. v0.3)
- Freebuff (v0.2 era, 100 turns): exactly 1
codetalk_recovercall, on a genuine wipe — zero false recoveries; instruction tax ~184 tokens → v0.3 Freebuff payload ~268 tokens (gating detail worth paying for), other harnesses ~98 tokens. - Codex (4,432 calls across 211 sessions): all memory reads, all predating v0.2 — v0.3's fallback payload cuts their standing cost ~46% and adds no recovery vigilance duty.
Verification
99/99 tests (new test_continuity.py covers marker detection, token round-trip, forgery/truncation rejection, tailoring). Live dual-client handshake proven: Freebuff-identified client receives the mandate, a generic client the fallback. End-to-end token handshake: issue → honest verify → forged reject.
Upgrade notes
- Install is editable → v0.3 is live at next server start.
- Freebuff users: remove and re-add the codetalker server once in the Freebuff UI — the consent sidecar pins
allowedTools, andcodetalk_recover_tokenneeds re-approval. - Other harnesses pick up v0.3 via their normal config with no action.
Full changelog: afbfd36...v0.3.0