Hop back into any coding-agent session
[Install] - [Quick start] - [Agents] - [Docs] - [Changelog]
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.
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 codexnarrows it to one agent, andhb . --printshows 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.
--yoloorhb config permission set normal|yolo|inheritchanges 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.
Enter puts you back in the agent, with the conversation where you left it:
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, andforked_fromin the JSON output.
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.
Search
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.
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)
| 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)
| File | Actions Reset | |||
|---|---|---|---|---|
| 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 logRelease 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 logRelease 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 logRelease 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 logRelease 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 logSecurity 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.
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 logA 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.