AgentSwitch

Synopsis

ax [pick]
ax new
ax list
ax models update

Description

AgentSwitch is a local session index and launcher for command-line coding agents. It is written in Go and distributed as the ax binary. It reads transcript stores written by configured harnesses, presents sessions in a searchable picker, and resumes selected sessions by invoking each harness's own resume command.

AgentSwitch does not replace the harness. It operates on local files, databases, tmux metadata, and live-session heartbeat state where available. When a matching session is already open, the picker can jump to the existing tmux window instead of starting a duplicate resume.

Installation

Releases

Prebuilt binaries are published on GitHub. The latest release page always resolves to the newest release.

Download the archive for your platform, place ax on your PATH, and run ax.

Manual binary installs are the initial distribution path. Package manager installs, such as Homebrew, Chocolatey, and apt repositories, may be added after the release process is settled.

Go Toolchain

If your environment allows the Go toolchain but blocks downloaded release binaries, install from the module source:

go install github.com/noahirzinger/agentswitch@latest

This builds ax locally and writes it to Go's binary directory, usually $(go env GOPATH)/bin or $(go env GOBIN). Make sure that directory is on your PATH.

To install a specific documented version, replace @latest with the release tag:

go install github.com/noahirzinger/agentswitch@v0.1.0

Source Checkout

Source checkouts are intended for development and are documented in the GitHub README.

Runtime Requirements

Program	Requirement	Use
fzf	required	Displays the interactive picker.
ripgrep	required	Searches extracted transcript text.
tmux	optional	Creates, locates, and switches session windows.

tmux Bindings

The following bindings open AgentSwitch in a tmux popup:

bind-key a display-popup -E -B -s 'bg=terminal' -w 100% -h 100% "ax pick"
bind-key A display-popup -E -B -s 'bg=terminal' -w 100% -h 100% "ax new"

Use -w 85% -h 80% for a smaller popup. The bundled tmux/ax.tmux file provides equivalent bindings.

Layout

Each configured harness specifies where its transcripts are stored, how a session id is extracted, which parser is used, and which commands launch or resume sessions. AgentSwitch scans these stores and builds a list containing harness, window, model, age, context use, cost, directory, and title fields where available.

Content search uses a plain-text copy of each transcript under ~/.local/state/ax/text/. The copy is rebuilt when the source transcript changes, so searches operate on conversation text rather than raw JSON fields.

Rendered Picker

The picker is a terminal table with a preview pane. The example below uses the same visible row layout as ax list, with public sample data.

+-- ax v0.1.0 ----------- INSERT ----------- 4 sessions - $56 - 1 live  ? help --+
| filter ❯ shell
| HARNESS  MODEL        AGE  CTX  COST     DIR                    WIN       TITLE
| claude   opus-4-8     3m   6%   $4.33    ~/.dotfiles             main:2.0  fix shell wrapper symlink
| codex    gpt-5.5      now  44%  $4.45    ~/src/site                        landing page documentation
| opencode gpt-5.5      1d   0%   $0       ~/src/agentswitch                  session database check
| pi       gpt-5.5      6h   23%  $46.39   ~/src/example-app                  video pipeline work
|
+--------------------------------------------------------------------------------+
| claude  opus-4-8  ~/.dotfiles
| transcript preview:
|   fix the broken bin symlink and verify the shell picks up the new target
|
| enter opens the selected session     tab marks multiple sessions
| / searches transcript text           ctrl-n starts a new session
+--------------------------------------------------------------------------------+

Field	Description
HARNESS	The command-line agent or harness that owns the transcript.
MODEL	Model recovered from transcript metadata.
AGE	Time since the last recorded session activity.
CTX	Estimated context-window use, based on harness token counts and model context size.
COST	Recorded harness cost when available; otherwise an estimate from token counts and model pricing.
DIR	Project directory associated with the session.
WIN	Live tmux location when the session is already open. Blank means no matching window was found.
TITLE	Session title or inferred summary, depending on the harness transcript format.

Controls

The picker opens in normal mode. The prompt switches between metadata filtering and transcript content search.

Mode	Keys	Action
movement	j, k, g, G, d, u	Move by row, jump to top or bottom, or move by half-page.
sorting	H, L, s	Select a column and sort by it. Press s again to reverse direction.
filtering	i, a, Esc	Filter metadata rows and return to normal mode.
content search	/, n, N	Search transcript text and move between matches in the preview.
preview	J, K	Scroll the transcript preview.
session	Enter, Tab, Ctrl-N	Open a session, mark multiple sessions, or start a new session.
exit	q	Quit the picker.

Commands

Command	Description
ax	Open the picker. Equivalent to ax pick.
ax pick	List indexed sessions and resume the selected entries.
ax new	Select a harness and directory, then start a new session.
ax list	Print indexed sessions, one per line.
ax models update	Refresh model price and context data from models.dev.

Configuration File

Built-in harness definitions are used when no configuration file is present. To override a built-in harness or add another one, copy config.example.toml to ~/.config/ax/config.toml.

# ~/.config/ax/config.toml

[[harness]]
name = "myagent"
glob = "~/.myagent/sessions/*/*.jsonl"
id_regex = "_(?P<id>[0-9a-f-]{36})\\.jsonl$"
format = "pi"
resume = "cd {dir} && myagent --resume {id}"
launch = "myagent"

Field	Description
name	Harness name. A built-in name replaces that built-in definition.
glob	Transcript file pattern.
db	Database path for database-backed harnesses.
id_regex	Regular expression used to extract the session id from a path.
format	Transcript parser, such as claude, pi, or codex.
resume	Resume command. Supports {id}, {dir}, and {model}.
launch	Command used to start a new harness session.

Supported Harnesses

Harness	Session store	Resume command
Claude Code	~/.claude/projects/<mangled-cwd>/<uuid>.jsonl	claude --resume <id> --model <model>
OpenAI Codex CLI	~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-<ts>-<uuid>.jsonl	codex resume <id>
opencode	~/.local/share/opencode/opencode.db	opencode --session <id>
pi coding agent	~/.pi/agent/sessions/<mangled-cwd>/<ts>_<uuid>.jsonl	pi --session <id>

Model Data

Context sizes and prices are read from models.dev. A snapshot is embedded in the binary for offline use. ax models update writes an updated copy to ~/.local/state/ax/models.json, which takes priority at runtime.

Cost columns in the picker are informational. When a harness records cost directly, AgentSwitch displays that value. Otherwise it estimates cost from transcript token counts and the current models.dev pricing table. These numbers are useful for comparing sessions in the UI, but they may not match what a user actually pays when the harness is backed by a subscription plan, bundled usage, credits, discounts, or another provider-specific billing arrangement.