docs

One page. Everything it does.

ThreadHop is a terminal UI, a CLI and an agent plugin over one local SQLite store. This page lists all three surfaces. Nothing here leaves your machine.

Install

macOS. The installer brings in uv if you don't have it, clones to ~/.local/share/threadhop, and links threadhop into ~/.local/bin. Re-run it to update.

$ curl -LsSf https://threadhop.parzival.computer/install.sh | bash

Then, from inside any agent chat, add the plugin for the slash commands:

/plugin marketplace add parzival1l/threadhop
/plugin install threadhop@threadhop

Borrow context between sessions

The core move. In the chat that has the context:

!threadhop prepare
✓ ticket tk_1a2b3c4d · paste in the target chat: !threadhop receive tk_1a2b3c4d

In the chat that needs it:

!threadhop receive tk_1a2b3c4d

A ticket is a markdown file in ~/.config/threadhop/transfers/: a short summary of the conversation's head plus the last few exchanges verbatim. Reading one costs zero LLM calls. To just look without a ticket: !threadhop peek <session> --last 5.

TUI

Highlights

Select one message or a range, then copy, export, or bookmark it. Selection lives in the transcript pane.

l / h
focus transcript / back to session list
m
enter selection mode (starts at the last message)
j k
move between messages
v
anchor a range and extend it
y
copy the selection with source labels
e
export the selection to /tmp/threadhop/<id>.md
Esc
leave selection mode

Bookmarks

Pin a message for later. Two kinds: bookmark (keep) and research (follow up). One table shared by TUI, CLI and plugin.

Space
toggle bookmark on the selected message
L
edit the bookmark's note
b
open the bookmark browser
Enter · L · d
jump to message · edit note · delete

Board & status

Every session has a status. The sidebar groups by it; the board shows it as columns.

s S
cycle status forward / back — in_progress · in_review · done · archived
a A
archive session · show/hide archived
B
open the kanban board
h l · j k
move between columns · within a column
Shift+← Shift+→
move a card to the adjacent status

Sessions

The sidebar is live: it polls every 5 s and marks what's running (◐ working · ● active · ○ idle).

j k
move between sessions
Enter / /
reply in place (sent with claude -p --resume)
n
rename — the title is written back so the agent sees it too
g
copy the resume command
J K
reorder
[ ]
shrink / grow the sidebar
t T
next / previous theme — opencode, nord, gruvbox, catppuccin, tokyonight
?
help overlay

CLI

Every subcommand auto-detects the session you're in when run from inside an agent chat via ! bash passthrough. Pass --session <id> from anywhere else.

threadhop
open the TUI. --project <name>, --days <n> to filter
threadhop search '<terms>'
FTS search from the shell. --project, --limit, --json
threadhop peek <session> [--last N | --range A:B | --grep RE]
print cleaned exchanges from any session — no LLM call
threadhop prepare --session <id>
freeze a session into a ticket: summarised head + verbatim tail. One haiku call, cached
threadhop receive <tk_id>
print a ticket so the current chat can read it
threadhop tag <status>
set the current session's status
threadhop bookmark [research] [--note …]
bookmark the latest message in the current session
threadhop copy [N | all]
copy the last N cleaned turns to the clipboard
threadhop update · changelog · future
update in place · what's new · what's next

Plugin

Thin wrappers over the CLI, so they run instantly with no model turn. Requires threadhop on your $PATH.

/threadhop:tag <status>
tag the session you're in
/threadhop:bookmark [--note …]
bookmark the latest message
/threadhop:copy [N | all]
copy cleaned turns
/threadhop:handoff <session>
generate a handoff brief from another session

Where your data lives

~/.config/threadhop/sessions.db
SQLite — sessions, messages + FTS5 index, bookmarks, status
~/.config/threadhop/transfers/
tickets, one markdown file each
~/.config/threadhop/config.json
theme, sidebar width

Transcripts are read in place from each agent's own directory. ThreadHop never writes to them except when you rename a session.