agenthop

Hop AI coding sessions between agents — browse, preview, migrate, and resume across Claude Code, Codex, Cursor, OpenCode, and more.

Install · Quick start · TUI · Providers · CLI · Architecture

Why agenthop?

You hit a rate limit mid-task, or you want a different model for the next step. agenthop keeps your context: it reads sessions from one coding agent and writes them in another agent's native format so you can resume where you left off.

Install

# Recommended: install script (linux / macOS)
curl -fsSL https://raw.githubusercontent.com/CyrusSE/agenthop/main/scripts/install.sh | bash

# Go toolchain
go install github.com/CyrusSE/agenthop/cmd/agenthop@latest

# From source
git clone https://github.com/CyrusSE/agenthop.git
cd agenthop && make install

Requires Go 1.22+ for building from source. The install script places agenthop on your PATH (typically ~/.local/bin).

Quick start

1. Open the TUI (indexes in the background on first run):

agenthop

2. Or use the CLI:

# Sessions in the current directory (and subfolders)
agenthop list --cwd

# All indexed sessions (default: no limit)
agenthop list

# Cap output if you prefer
agenthop list --limit 20

# Preview a session
agenthop show <session-id> --limit 15

# Migrate Claude → Codex and get resume command
agenthop migrate <session-id> --from claude-code --to codex -y
agenthop resume <session-id> --from claude-code --to codex

3. Refresh the index when you've created new sessions in your agents:

agenthop index update          # incremental
agenthop index rebuild         # full rebuild
agenthop list --refresh        # rescan then list

list reads from the cached index by default. Use --refresh only when you need a live rescan.

TUI

The default interface is a Codex-style session browser: one list for all agents, scoped to your cwd by default.

   ╭──────◆──────╮
   │  agenthop   │     cwd  all
   ╰─────────────╯
  session browser    ~/projects/my-app

  3d ago  Fix auth bug          Claude Code · 67417609 · …/my-app
  1h ago  Refactor API           Codex · 8a2f1c3e · …/my-app
  …

  ↑↓ navigate · enter actions · w cwd · a all · [/] page · p agent · r refresh

Actions menu (after Enter on a session): preview messages, migrate, copy session ID, copy resume command.

Providers

Check that agent data paths are discoverable:

agenthop providers
agenthop providers doctor

Add a new provider: docs/adding-a-provider.md

CLI

agenthop list [--cwd] [--provider ID] [--limit N] [--refresh]
agenthop show <id> [--provider ID] [--limit N]
agenthop migrate <id> --to <provider> [--from ID] [--dry-run] [-y]
agenthop resume <id> --to <provider> [--from ID]
agenthop index {status|rebuild|update} [--provider ID]
agenthop export <id> -o session.agenthop.json
agenthop import session.agenthop.json --to <provider> [-y]
agenthop providers [doctor]
agenthop tui                    # explicit TUI (default when no subcommand)

Portable bundles — export a session to JSON, import on another machine:

agenthop export abc123 -o backup.agenthop.json
agenthop import backup.agenthop.json --to codex -y

Development

git clone https://github.com/CyrusSE/agenthop.git
cd agenthop
make build test      # compile + unit tests
./scripts/smoke.sh   # integration smoke test
make install         # install to ~/go/bin or GOBIN

Contributing: CONTRIBUTING.md · Provider guide: docs/adding-a-provider.md

Limitations

• Cursor GUI chat history uses different storage than Cursor CLI (cursor-agent); agenthop indexes CLI sessions.
• Tool and system messages may not round-trip perfectly on every target provider.
• Claude Code resume may require cd to the original project directory.

License

MIT