showagent

<!-- mcp-name: io.github.aytzey/showagent -->
<h1 align="center">showagent</h1>

<p align="center"><b>Switch coding agents. Bring the conversation.</b><br>
Find a local session and carry its user and assistant messages into another agent's native session format.<br>
Codex · Claude Code · Gemini CLI · OpenCode · jcode · Pi</p>

<p align="center">
<a href="https://github.com/aytzey/showagent/actions/workflows/ci.yml"><img src="https://github.com/aytzey/showagent/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://github.com/aytzey/showagent/releases/latest"><img src="https://img.shields.io/github/v/release/aytzey/showagent" alt="Release"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
</p>

![showagent walkthrough using sample sessions and simulated agent output](docs/demo.gif)

*Sample sessions; simulated CLI output. The handoff uses the real showagent
binary; the target CLI is a labeled demo stub. See
[compatibility evidence](docs/compatibility.md) for what has been tested.*

Started debugging in Codex and want Claude's take? Find the old session,
preview the handoff, then create a new Claude Code session in the same workspace.
Your original session stays intact. Conversion carries transferable user and
assistant messages; tool calls/results, approval state, attachments, and other
agent runtime state are not carried over.

## Install

On **Linux or macOS**, install the latest GitHub release. The script checks
the archive against that release's `SHA256SUMS` and normally installs in
`~/.local/bin`:

```sh
curl -fsSL https://raw.githubusercontent.com/aytzey/showagent/main/scripts/install.sh | sh
```

If that directory is not on your `PATH`, run `~/.local/bin/showagent` directly
or add the directory to your shell's `PATH`.

On **Windows**, download and extract the `windows_amd64.zip` archive from the
[latest release](https://github.com/aytzey/showagent/releases/latest), then run
`.\showagent.exe` in PowerShell from the extracted directory. Windows support
is **experimental**; see [platform and native-resume evidence](docs/compatibility.md).

Homebrew and Go installation remain available under
[other installation options](#other-installation-options).
[Distribution details](docs/distribution.md) explain version differences between channels.

## Quick start

You need an existing local session, the target agent's CLI on `PATH`, and its
normal sign-in/setup completed. Keep the original workspace available.

```sh
showagent
```

1. Press `/` and search for the workspace or a phrase in the session's first
   or latest user prompt. Press `enter` to finish searching, then select the
   session you want to continue.
2. Press `o` until the target is `claude` (or another installed agent).
3. Press `x` to review the workspace, message scope, and state that will be
   dropped. Press `x` again to write and select the new session.
4. Press `enter` to open that new session in the target CLI.

Prefer commands? The [Codex → Claude handoff guide](docs/handoff-guide.md)
walks through selecting an explicit session ID, previewing, converting, and
resuming it. It also explains the reverse direction and what conversion preserves.

Star showagent to keep it handy for your next agent switch.

## Why

Each coding agent keeps its own local session store. showagent reads the
supported stores and brings their sessions into one terminal picker:

- **Find a past session** — group by workspace and fuzzy-search agent, session
  ID, paths, and first/latest user prompts. This is not full-transcript search.
- **Resume or branch** — reopen a session in its own CLI, or copy its
  transferable conversation into a new native session to try another direction.
- **Switch agents** — preview what will carry over, then write a new session
  for the target agent. File-backed copies are private and written atomically;
  OpenCode imports go through its own CLI. Originals are preserved.
- **Keep your history local** — no hosted service, telemetry, or showagent
  account. The optional updater uses the network; an MCP client may send
  requested transcript content to its model provider. See the [privacy FAQ](#faq).

## Supported agents

| Agent | CLI | Sessions read from | Env override | Convert from | Convert to |
|---|---|---|---|:---:|:---:|
| Codex | `codex` | `~/.codex/sessions/**/*.jsonl` | `CODEX_HOME` | ✅ | ✅ |
| Claude Code | `claude` | `~/.claude/projects/**/*.jsonl` | `CLAUDE_HOME` | ✅ | ✅ |
| Gemini CLI | `gemini` | `~/.gemini/tmp/<project>/chats/` | `GEMINI_CLI_HOME` | ✅ | ✅ |
| OpenCode | `opencode` | `opencode.db`, via the `opencode` CLI | `OPENCODE_DATA_HOME` | ✅ | ✅ |
| jcode | `jcode` | `~/.jcode/sessions/*.json` | `JCODE_HOME` | ✅ | ✅ |
| Pi | `pi` | `~/.pi/agent/sessions/**/*.jsonl` | `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR` | ✅ | ✅ |

Notes:

- The table describes implemented adapters, not a claim that every provider
  version and conversion direction has passed a real CLI test. See the
  [compatibility record](docs/compatibility.md).
- OpenCode stores sessions in a SQLite database, so every OpenCode operation
  (discover, export, import, delete) goes through your own `opencode` CLI —
  showagent never writes into the database directly. OpenCode and jcode only
  appear when their CLI is installed.
- The picker only offers hand-off targets whose CLI is on `PATH`.
  Scripted conversion to file-backed agents can still
  prepare a session before their CLI is installed; OpenCode always requires
  its CLI because imports go through OpenCode itself.
- jcode is a niche, experimental agent CLI. Its support is auto-hidden: if no
  `jcode` binary is on `PATH`, showagent never shows it.
- Pi sessions are versioned JSONL trees. showagent follows Pi's active leaf
  through `parentId` links, so abandoned branches are not previewed or moved
  into another agent. Converted sessions use Pi's native v3 format; the
  [compatibility record](docs/compatibility.md) distinguishes file conversion
  from native loader and model-continuation checks.
- A project-local Pi `sessionDir` is visible when showagent is launched from
  that project. Like Pi itself, showagent cannot discover arbitrary custom
  session roots belonging to other projects unless one is selected globally
  with `PI_CODING_AGENT_SESSION_DIR`.
- Platforms: Linux and macOS (amd64 + arm64). Windows (amd64) builds are
  released but **experimental**: resume runs the agent as a child process
  instead of replacing showagent.

## Other installation options

```sh
# Homebrew (Linux/macOS)
brew install aytzey/tap/showagent

# Go 1.25.13+
go install github.com/aytzey/showagent/cmd/showagent@latest
```

Homebrew, GitHub releases, Go module versions, and MCP bundles can update on
different schedules. Go's `@latest` follows module version resolution, which
can differ from GitHub's latest release; check `showagent --version` and
`showagent --help` after installing. See [distribution details](docs/distribution.md)
for channel-specific features and update instructions.

Archives are also available for `linux`/`darwin` amd64 + arm64 and `windows`
amd64 (experimental) on the [releases page](https://github.com/aytzey/showagent/releases/latest).

## More commands

```sh
showagent                  # open the interactive picker
showagent list             # plain table of every session
showagent list --json      # the same, machine-readable
showagent transcript latest --max-turns 50 --json
                           # bounded, secret-redacted context for local handoff
showagent resume latest    # reopen the most recent session, any agent
showagent convert SOURCE_SESSION_ID --to claude --dry-run
                           # preview exactly what a hand-off would carry/drop
showagent info latest      # exact resume command + storage location
showagent mcp              # serve session history to MCP-capable agents (stdio)
showagent mcp --read-only  # same search/transcript tools, without tools that write copies
showagent mcp --allow-secrets
                           # explicitly allow verbatim secret-like transcript values
showagent update           # update a standalone install (Homebrew: brew upgrade aytzey/tap/showagent)
showagent --help           # full CLI help
```

Replace `SOURCE_SESSION_ID` with the ID you selected from `showagent list`.
The `transcript` command is not present in older builds such as v0.11.0;
check [distribution details](docs/distribution.md) if your help output differs.

### Keybindings

| Key | Action |
|---|---|
| `↑/k`, `↓/j`, `pgup/pgdn` | Move through sessions |
| `/` | Fuzzy search across agent, session id, paths, and first/latest user prompts |
| `enter` | Resume the selected session in its own CLI |
| `1`..`9` | Toggle provider visibility, numbered as listed in the header bar |
| `p` | Cycle the preview column: first → latest → first + latest message |
| `space` | Collapse or expand the selected workspace group |
| `o` | Cycle the convert target for the selected session |
| `t` | Cycle the convert scope: all turns, or latest 200/100/50/20/10 |
| `x` | Preview convert; press `x` again to write and select the new session |
| `n` | Branch: copy the transferable conversation to a new session in the same agent |
| `y` | Toggle the provider's yolo resume mode (jcode/Pi add no flag) |
| `C` | Compound: resume with a learnings-capture prompt (see below) |
| `d`, `del`, `backspace` | Delete the session — second press confirms, moving disarms |
| `r` | Rescan session stores (keeps cursor, search, and filters) |
| `?` | Toggle the full keybinding overlay |
| `esc` | Clear search / close overlay / cancel an armed delete (never quits) |
| `q`, `ctrl+c` | Quit |

## Scripting

`showagent list --json` emits an array sorted newest-first — the field names
are a stable contract:

```json
[
  {
    "id": "1f7c9a2e-4b31-4c8e-9d02-8a5e3f6b1c44",
    "provider": "codex",
    "workspace": "/home/you/code/api-server",
    "updated": "2026-0