-
Notifications
You must be signed in to change notification settings - Fork 4
CLI Reference
Longhand's commands, each with a one-line purpose. Current as of v1.2.0 — run longhand --help for the always-true list.
One-shot orchestrator: ingest + analyze + install hooks + register MCP + doctor. Run once after install.
Verify installation. Checks database, hooks, MCP registration, index health. First thing to run when something isn't working.
Discover and parse Claude Code JSONL files into SQLite + ChromaDB. Incremental by default.
Reconcile on-disk transcripts against the sessions table. Prints a bucket summary (fully indexed, partially indexed, null-project, oversize-skipped, missing) and, when a Codex home exists, the Codex rollouts on disk (captured and current, new or changed, subagent threads skipped, over the size bound). With --fix, re-ingests what's missing using current project-inference logic and captures new or changed Codex rollouts — useful any time you suspect a hook failure left gaps (the doctor freshness and hook-error rows will tell you). Idempotent; safe to run any time.
longhand codex-sync [--semantic] [--finalize-after SECONDS] [--no-finalize] [--watch] [--dry-run] [--include-subagents]
Capture Codex Desktop / CLI threads (the rollouts under ~/.codex/sessions) into the same archive, in two passes (1.2.0): exact records for every new or changed rollout — no vector model loaded — then the full pipeline for any rollout quiet for --finalize-after seconds (1800) so recall and semantic search see it; the model loads only when a quiet thread is waiting, one thread per run. --no-finalize skips the second pass; --semantic runs the full pipeline on everything now. Bounds per run: --limit 50, --max-file-kb 16384, --max-events 20000 (larger rollouts are deferred, never partially imported). --dry-run lists rollouts, sizes, and which are subagent threads without opening the archive; --watch polls every --interval seconds (60); --codex-home and --data-dir override the defaults. reconcile --fix runs both passes too. See Codex.
Re-run extractors and analysis on existing sessions. Use --all after upgrading to re-process historical data with new logic. It rebuilds outcomes, episodes, and project attribution but never embeds events — archived Codex threads are finalized on their own once quiet (codex-sync --semantic does it now).
List ingested sessions with event and edit counts.
List inferred projects with categories.
Semantic search across all events. Accepts filters for session, project, tool, file, event_type.
Storage footprint and indexing stats.
Chronological view of a session. Supports --offset, --tail, pagination.
Get surrounding context for a specific event.
Show before/after diff for a single edit event.
Proactive fuzzy recall. Time parsing + project match + episode search. The command you'll use most.
Three modes, plus --json on all of them:
-
bare
status— recent-work digest: sessions, outcomes, projects, first asks (--days N,-p <project>,--limit N) -
status <project-name>— where did we leave off on X. Git-aware. -
status --session <session-id>— the tail of one session so you can pick up where you left off (--events N)
longhand recap → bare status · longhand continue <id> → status --session <id> · longhand patterns → longhand recall "<topic>". All three still run through 0.x and print a pointer to their replacement.
Every edit to a file across all sessions, chronologically.
Reconstruct exact file state at a point in a past session.
Extract git operations (commits, pushes, checkouts) from one or all sessions.
Export a session or episode to a standalone markdown file.
Wire the SessionEnd auto-ingest hook into ~/.claude/settings.json.
Wire the UserPromptSubmit auto-injection hook.
Register Longhand's MCP server with Claude Code / Claude Desktop.
Run the shared-archive MCP server (stdio): four read-only keyword tools over the SQLite archive both Claude and Codex write, with no vector model loaded. Register it as longhand-shared in Claude Code (claude mcp add --scope user longhand-shared -- longhand shared-mcp) and as longhand in Codex. See Codex and MCP Tools Reference → The shared server.
View and tune hook behavior — relevance threshold, injection size, etc. See Configuration.