Skip to main content

hopback: find, resume and fork coding-agent sessions from one terminal

Hop back into any coding-agent session

crates.io downloads npm downloads per week

[Install] - [Quick start] - [Agents] - [Docs] - [Changelog]

crates.io version CI Platforms: macOS and Linux License: MIT


hb finds your Claude Code, Codex, Antigravity and other agents' sessions in one list, resumes the one you pick in its own folder, and can fork a Claude Code session into Codex or back.

hopback browsing the sessions of four agents, searching them, resuming one in Claude Code, and forking it into Codex

Install

Pick one. Each installs two commands that are the same program: hopback and the short hb.

Homebrew

macOS and Linux.

brew install avgvi/tap/hopback

Shell installer

A prebuilt binary for macOS or Linux, arm64 or x86_64.

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/avgvi/hopback/releases/latest/download/hopback-installer.sh | sh

Cargo

cargo install hopback

That builds from source. To download the release binary instead:

cargo binstall hopback

npm

npm install -g hopback

Or run it once without installing, with npx hopback.

Python tools

uv tool install hopback

With pipx it is pipx install hopback.

Nix

nix run github:avgvi/hopback

Or add the flake to your profile.

mise

mise use -g ubi:avgvi/hopback

Quick start

hb .              # continue the newest session of this folder, whatever the agent
hb "auth bug"     # search, then resume or fork
hb                # browse the newest sessions
  • hb . skips the list. It resumes the most recently used session whose folder is the current one, or the closest parent folder that has one. hb . --agent codex narrows it to one agent, and hb . --print shows the folder and command instead of running them.
  • In the list, start typing to search titles, messages and paths. Press Enter to resume the selected session with its own agent, in the folder it ran in, and in the permission mode it was started with. --yolo or hb config permission set normal|yolo|inherit changes that.
  • Tab steps through the agents. It writes the filter into the search line (agent:claude), so what you see there is always what is being filtered.

The session list of hopback, with a pinned session, a fork, and the preview of the selected session

Enter puts you back in the agent, with the conversation where you left it:

Claude Code reopened on the selected session, showing the end of the conversation and its prompt

Translated forks: move a session to another agent

Press Ctrl+F on a Claude Code session and pick "translated codex fork". hopback reads the conversation, writes it as a new Codex session in the same folder, and opens Codex on it. The same works from Codex to Claude Code. You keep the context when you switch agents: the fork holds the conversation as it was, and the only thing hopback adds is [hopback] in front of its title.

hb fork --to codex claude:5f0c2a9e-...            # same thing from the command line
hb fork --to codex --dry-run claude:5f0c2a9e-...  # see what would be written
hb fork claude:5f0c2a9e-...                       # native fork: the agent forks its own session
  • Translated forks exist between Claude Code and Codex.
  • Native forks are available where the agent has one: Claude Code, Codex, OpenCode and Goose.
  • A forked session shows a ↳ mark in the list, and forked_from in the JSON output.

The fork menu on a Claude Code session, with the translated Codex fork selected

Supported agents

Agent Tab Resumes with Native fork Translated fork
Claude Code claude claude --resume <id> yes to and from Codex
Codex codex codex resume <id> yes to and from Claude Code
Antigravity agy agy --conversation <id> no no
OpenCode opencode opencode <dir> --session <id> yes no
Kimi Code kimi kimi --session <id> no no
Kiro CLI kiro kiro-cli chat --resume-id <id> no no
Goose goose goose session --resume --session-id <id> yes no
Pi pi pi --session <id> no no
Cursor CLI cursor agent --resume <id> no no
Grok Build grok grok --resume <id> no no
Gemini CLI gemini gemini --resume <id> no no
GitHub Copilot CLI copilot copilot --resume <id> no no
Copilot in VS Code vscode code <dir> no no
Crush crush crush --session <id> no no
Mistral Vibe vibe vibe --resume <id> no no

hopback only reads the agents' files. Subagent sessions and sessions with no prompt are left out.

The Goose desktop app on macOS does not put goose on PATH. When it is missing there, hopback runs the copy inside Goose.app.

Keys

Typing always goes to the search, so actions use a modifier.

Key Does
Enter Resume the selected session
↑ ↓, PgUp, PgDn Move
Tab / Shift+Tab Next or previous agent tab. Tab first finishes a suggested filter value
Ctrl+T Pin to the top, or unpin
Ctrl+R or F2 Rename inside hopback
Ctrl+F Fork
Ctrl+Y Copy the resume command
Ctrl+X Hide from hopback (asks first)
Ctrl+O Menu of the five actions above, each with its key
Ctrl+P Preview on or off
F1 Help: every key on one screen
Esc Clear the search; quit when it is already empty
← → Home End, Ctrl+A, Ctrl+E, Ctrl+W, Ctrl+U, Delete Edit the search text
Mouse Click selects, double-click resumes, right-click opens the actions menu, the wheel scrolls the list or the preview

Pinned sessions (★) stay at the top. A rename changes the title only inside hopback. Hiding removes a session from hopback's list and nothing else.

The Ctrl+O menu: pin, rename, fork, copy the resume command, hide

Free text matches titles, messages and folders. Keywords narrow it. They are colored as you type, and a value hopback does not know turns red.

Keyword Example Matches
agent: agent:claude, agent:claude,codex, agent:!codex sessions of those agents, or of all but one
dir: dir:backend sessions whose folder contains the text
date: date:today, date:yesterday, date:week, date:month, date:<3d, date:>2w sessions by age

While you type an agent or a date, the rest is suggested after the cursor (agent:cl shows aude). Tab or → takes it, and the list already shows the suggested filter.

A search for "discount date:week": four sessions from three agents, with the matches highlighted in the preview

Scripts and agents

hb --json --limit 10 "agent:codex api error"   # one JSON object on stdout
hb --json --include-messages --limit 1 "auth"   # with the conversation text
hb pin claude:5f0c2a9e-...                      # also: unpin, rename, hide, unhide
hb fork --json --to codex claude:5f0c2a9e-...   # the new session as JSON, nothing launched
hb --agent-context                              # instructions for a coding agent

--json has a versioned schema with paging, and every session carries the exact resume_command. See docs/json.md. hb --agent-context prints an Agent Skill that tells a coding agent how to search, page and resume safely; llms.txt has the short version.

Shell completions and the man page come from the binary:

hb completions zsh > ~/.zfunc/_hb     # bash, fish, elvish and powershell too
hopback man > hopback.1

Build from source

git clone https://github.com/avgvi/hopback
cd hopback
cargo install --path .       # installs hopback and hb into ~/.cargo/bin

AGENTS.md describes the code layout and the checks to run. docs/packaging.md covers how releases are built, and CHANGELOG.md what changed.

License

MIT. See LICENSE.

Metadata

Release files for hopback 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hopback 0.2.0
File Size Uploaded Provenance Actions
hopback-0.2.0.tar.gz 263.1 kB With provenance Details for hopback-0.2.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for hopback 0.2.0
File Actions
hopback-0.2.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for hopback-0.2.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
hopback-0.2.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for hopback-0.2.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
hopback-0.2.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for hopback-0.2.0-py3-none-macosx_11_0_arm64.whl
hopback-0.2.0-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for hopback-0.2.0-py3-none-macosx_10_12_x86_64.whl

Total release size: 18.8 MB

Release files / hopback-0.2.0.tar.gz

Download URL hopback-0.2.0.tar.gz
Size 263.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a0b3e20a6add15b7b6a75481cd9d19ae760efb571144b0c611a421a427341963
BLAKE2b-256 checksum
How to use checksums
8e479b1931977c2a98d647ca85e4de855e60871f15e44348114b8045f2fcff9c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / hopback-0.2.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL hopback-0.2.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 4.9 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
e2656bcd1248d529675ef61665cd106e3bae83baab6a9c9d3de77661d5adaf92
BLAKE2b-256 checksum
How to use checksums
2a151cdbe5b3acd24075407e86a8bfa3d1256db8d1dbed9c9c08e8e80f14a1bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / hopback-0.2.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL hopback-0.2.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 4.5 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
00efef0149566d7f0027ab9436779731c6f4866d2d9ae57f1c5ddfe4f63f3f70
BLAKE2b-256 checksum
How to use checksums
d235ab6fead046aa8d9a3a970f1069b5e1adb8ffb053199c30dcd6c2f65dd523
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / hopback-0.2.0-py3-none-macosx_11_0_arm64.whl

Download URL hopback-0.2.0-py3-none-macosx_11_0_arm64.whl
Size 4.5 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
3eefe94ba7a28edd80154a689582d787a95bf1db7b6c460534b4d17fd21f32c7
BLAKE2b-256 checksum
How to use checksums
d742501113361893bfe8a8c42510a443d206d5feef9619ab89c663a816812d1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / hopback-0.2.0-py3-none-macosx_10_12_x86_64.whl

Download URL hopback-0.2.0-py3-none-macosx_10_12_x86_64.whl
Size 4.7 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
fb5f97df203a214157ece3a8531d4ef6bd17b3c197de11d4520114f1565283b6
BLAKE2b-256 checksum
How to use checksums
a67a33bc06eb55100b1f064b3209c49c03fbacd10d8be10a4561afd21a230af7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for hopback 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for hopback-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

5 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page