threadhop

ThreadHop

Persistent, searchable, cross-session memory for Claude Code — a TUI, a CLI, and a Claude Code plugin that share one SQLite store.

Each Claude Code session ships as an isolated JSONL transcript. ThreadHop indexes them into SQLite with FTS5, runs a Haiku-powered sidecar that extracts TODOs and decisions per session, a reflector that surfaces decision conflicts across sibling sessions, and a handoff skill that compresses a session into a brief. The TUI is the main browser; most day-to-day capture happens from inside the Claude Code chat via !threadhop … bash passthrough or the /threadhop:* plugin commands.

What's in the box

• TUI — two-column browser over ~/.claude/projects/**/*.jsonl, with FTS search, bookmarks, status tags, message-range selection, AI-generated session titles.
• CLI — threadhop tag / bookmark / todos / decisions / observations / conflicts / observe, all auto-detecting the current session from the parent process tree so they work inside a live claude chat.
• Observer + reflector — background extractors that append structured JSONL per session and cross-compare decisions across sessions in a project (ADR-018 – ADR-020).
• Claude Code plugin (plugin/) — /threadhop:handoff skill plus /threadhop:observe, /threadhop:tag, /threadhop:bookmark commands under the /threadhop: namespace.

Install

macOS only. The installer handles everything — including installing uv if you don't have it.

Quick install (recommended)

curl -LsSf https://raw.githubusercontent.com/parzival1l/threadhop/main/install.sh | bash

This clones the repo to ~/.local/share/threadhop, installs uv if missing, and symlinks threadhop into ~/.local/bin. Re-run the same command any time to update.

Manual install

If you'd rather not pipe curl to bash, the same three steps by hand:

# 1. Install uv (skip if you already have it)
brew install uv    # or: curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone and link
git clone https://github.com/parzival1l/threadhop.git ~/.local/share/threadhop
mkdir -p ~/.local/bin
ln -s ~/.local/share/threadhop/threadhop ~/.local/bin/threadhop

# 3. Make sure ~/.local/bin is on your PATH (add to ~/.zshrc if not)
export PATH="$HOME/.local/bin:$PATH"

Verify with threadhop --version.

Claude Code integration

Once the CLI is installed, add the plugin to get the /threadhop:* slash commands and the handoff skill. From inside any claude session:

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

That registers the four primitives — /threadhop:handoff, /threadhop:tag, /threadhop:observe, /threadhop:bookmark — persistently across all future sessions. The plugin is a thin wrapper over the CLI, so the threadhop command must already be on your $PATH (see above) for the slash commands to do anything.

Skill-only alternative: if you only want /threadhop:handoff and not the three commands, you can install just the skill via Vercel's skills CLI:

npx skills add parzival1l/threadhop

Dev / local-testing path: if you've cloned the repo and want to load the plugin against a working-tree copy for one session, claude --plugin-dir ~/.local/share/threadhop/plugin loads it for that invocation only (no persistence).

Usage

TUI

threadhop                              # all sessions
threadhop --project myproject          # filter by project
threadhop --days 7                     # last 7 days only

CLI

All subcommands accept --project and --session; without them they auto-detect the current session.

threadhop tag <status>            # backlog | in_progress | in_review | done | archived
threadhop bookmark [kind]         # bookmark | research — against the latest indexed message
threadhop todos                   # open TODOs extracted by the observer
threadhop decisions               # decisions extracted by the observer
threadhop observations            # raw observation JSONL, newest first
threadhop conflicts [--resolved]  # cross-session decision conflicts from the reflector
threadhop observe [--once|--stop|--stop-all] [--watch-backend auto|poll|fsevents]

Keybindings

Navigation

Key	Action
j / k	Navigate sessions (in session list)
h / l	Focus session list / transcript
left / right	Focus session list / transcript
PageUp / PageDn	Scroll transcript
Home / End	Jump to top / bottom of transcript

Sessions