Skip to content

The Session Smith

Edit source

One workbench for Claude, Codex, and Copilot

AgentSmith is a local command-line workbench for the sessions that Claude Code, Codex, and GitHub Copilot CLI leave on your machine. It finds them, reads them, searches them, measures them, resumes them, exports them, and cleans them up. The working directory is the common thread.

That last part is the one I care about.

I do not wake up thinking, “I should resume session 019c7390-55cc-7e83-9537-e7534558d473.” I think, “I was working on AgentSmith.” The repository is what I remember. The session ID is bookkeeping.

So I start from the repository and resume what ran there:

Terminal window
cd ~/code/AgentSmith
asmith ls --here
asmith resume codex

AgentSmith makes the directory the handle and lets the native agent remain the engine.

The three agents all preserve useful history. They simply disagree on its shape.

Claude Code keeps project-scoped JSONL conversations, including adjacent subagent material. Codex combines rollout files with a SQLite thread index. Copilot CLI has session-state files, an index, usage data, and its own rules for which records can still be resumed. Their token accounting does not line up either. Cache reads, cache writes, reasoning tokens, child agents, and Copilot’s AIU belong to different ledgers.

None of this is bad design. Each store serves its own agent. It becomes awkward when one repository has been touched by all three. Listing one such repository puts them side by side:

Terminal window
$ asmith ls --here
* codex 019c7390 18m 42 turns ~/code/project Tighten the parser
* claude bbe91a64 2h 19 turns ~/code/project Trace config loading
* copilot 7a3fc324 1d 8 turns ~/code/project Add import validation

The source label stays visible because normalization should not become laundering. A Codex turn remains a Codex turn. A Copilot AIU does not quietly turn into a Claude token. AgentSmith works each native store through a backend, then exposes the pieces that can be compared honestly: identity, directory, timestamps, messages, touched files, resumability, and usage.

AgentSmith takes the working directory and the Claude, Codex, and Copilot session stores and builds one normalized view that every command, from list to merge, works on.

Think of it as a smith. The three stores never get poured into one anonymous vat. Their internals are heated just enough to become workable, while provenance and native artifacts survive the hammer.

The command is asmith. Most days, five commands cover the ground:

Terminal window
$ asmith ls -n 15 # recent sessions across all three agents
$ asmith ls --here # sessions attached to this directory
$ asmith tree # group the whole history by directory
$ asmith show 019c7390 # metadata, files, usage, and resume details
$ asmith dump 019c7390 # render the conversation

Every listing says which agent produced each row. Full IDs work, but a unique prefix is enough. Paths work where they make sense, so asmith show ., asmith files ., and asmith usage . follow the newest matching session for the current directory.

There is one search across all three stores:

Terminal window
asmith search "palette cache"
asmith grep 'OSC 133.*precmd' .

search finds a literal phrase across sessions. grep runs a regular expression over rendered transcripts. dump can include tool arguments, results, reasoning, or nested subagents, and it can render Markdown when the terminal is no longer the right place to read a long conversation.

Usage gets the same treatment. AgentSmith keeps each model’s fresh input, output, cache, and reasoning counts separate, then offers an explicitly estimated weighted-token count for ranking sessions across agents. The estimate is for comparison. Each native count remains beside it.

Each native CLI already knows how to resume its own sessions. Claude Code, for example, scopes session lookup to the current project and its worktrees. Copilot records enough local state to resume and also offers its broader Chronicle history. AgentSmith does not replace those mechanisms.

It chooses the newest resumable native session for a directory and calls the right one:

Terminal window
asmith resume claude
asmith resume codex ~/code/KronuZSH
asmith resume copilot ~/code/AgentSmith

The optional shell integration goes one step further. Calling claude, codex, or copilot with no arguments resumes the current directory when possible, and starts a new session when there is nothing to resume. Arguments pass straight through to the real CLI. Know one thing before you source it: the bare codex and copilot run with their approvals off (--dangerously-bypass-approvals-and-sandbox, --yolo), and so does asmith resume for those two.

Directories become lightweight session names without creating another session database.

A rendered transcript is useful, but it is not always the whole job. Sessions can have native sidecars, child-agent conversations, memory, project instructions, settings, hooks, and skills. AgentSmith exports the material it can attribute by default and records it in a checksummed directory bundle:

project-export/
├── manifest.json
├── sessions/
│ ├── claude/<id>/
│ ├── codex/<id>/
│ └── copilot/<id>/
├── project-memory/
└── environment/

Export the current project, copy the directory to another machine, and verify it there:

Terminal window
asmith export . -o ~/exports/agentsmith
asmith verify ~/exports/agentsmith

Multiple session IDs or project directories can go into one bundle. Path selection is exact unless --recursive is explicit, which keeps a careless parent-directory export from swallowing every nested project.

Import is conservative. AgentSmith does not forge a Claude conversation into Codex’s private database and hope the schema remains stable. It prepares a readable, agent-neutral handoff from one or more bundles or old dumps. The destination agent reads that handoff and creates a real session of its own:

Terminal window
handoff=$(asmith import ~/exports/agentsmith -o ~/imports/agentsmith)
asmith launch codex "$handoff"

merge starts from live sessions instead of exported material:

Terminal window
handoff=$(asmith merge . -o ~/imports/combined-history)
asmith launch claude "$handoff"

The prepared directory remains inspectable before launch, and worth inspecting: launch starts the agent with its approvals off. Project context stays with the project. Global instructions, hooks, skills, and configuration have their own --global export, so a user-wide rule is not copied into every project bundle.

This is continuation with provenance. The source remains available, omissions are named, and the new agent owns the new session.

There is good prior art around this problem.

Agent Sessions is a polished, local-first macOS application for browsing, searching, analyzing, and resuming history from a wide range of agents. It covers more harnesses than AgentSmith and gives the work a proper visual cockpit.

Agent Capsule focuses on sharing a complete Codex or Claude conversation and continuing it as a native local session. codex-claude-transfer goes directly after translation, portable bundles, sync, and native import between those two agents. agent-session-resume approaches continuation as a reusable skill that reconstructs context for the next agent.

AgentSmith sits a little lower and wider in the toolbox. It is a scriptable CLI for three local stores, organized around directories, with inspection, cross-agent search, usage accounting, export and import, global and project context, cleanup, and shell-level resume in one place. Its transfer path deliberately favors a visible handoff over writing translated history into another vendor’s private store.

Different jobs want different tradeoffs. If you want a macOS session browser, use the good macOS session browser. If you want direct native translation between Claude and Codex, use a tool built for that. I wanted something I could pipe, audit, and teach to my shell.

AgentSmith is Python standard library only. You need python3, the agent CLIs you use, and ~/.local/bin on PATH.

The checkout can live anywhere. This uses the standard per-user data directory:

Terminal window
agentsmith_home="${XDG_DATA_HOME:-$HOME/.local/share}/AgentSmith"
mkdir -p "$(dirname "$agentsmith_home")"
git clone https://github.com/Kronuz/AgentSmith.git "$agentsmith_home"
"$agentsmith_home/install.sh"

The installer links the executable into ~/.local/bin. Add the optional shell integration to ~/.profile, ~/.zshrc, or ~/.bashrc for auto-resume wrappers, ascd, and tab completion:

Terminal window
agentsmith_home="${XDG_DATA_HOME:-$HOME/.local/share}/AgentSmith"
[ -r "$agentsmith_home/agentsmith.sh" ] &&
. "$agentsmith_home/agentsmith.sh"
unset agentsmith_home

Open a new shell, then start somewhere harmless:

Terminal window
asmith stats
asmith dirs
asmith tree
asmith ls --here

These commands only read the local stores. When you are ready, try asmith dump <id> and asmith resume codex.

AgentSmith also has sharp tools. rm shreds selected local session state, purge removes empty sessions, and redact scrubs a leaked value across mutable agent stores. They support previews and confirmations for a reason. Start with --dry-run.

Terminal window
asmith rm . --dry-run
asmith purge --dry-run
asmith redact 'example-leaked-value' --dry-run

The repository has the complete command reference and a copy-paste tutorial. Try it against the directory you are already working in. If one of the three agents has changed its private store again, bring a sample, an issue, or a hammer.