Commands

hippo has 28 commands, in the groups hippo --help shows. Run hippo <command> --help for the same flags in short form.

Run hippo with no arguments first. With no config.toml it prints what hippo detect finds and offers to index that history (history only, no notes folder, nothing sent anywhere). On a terminal it asks Index it now? [Y/n]; with no terminal it prints run hippo start --yes to index it and exits 0. Once hippo is set up, hippo on its own runs an incremental ingest when the last one is older than ingest_interval_minutes, then shows the last active day: its sessions, merged pull requests, corrections, and four commands to try next.

Commands read $HIPPO_HOME/config.toml (by default ~/.hippo/config.toml) and work on the one workspace named there, never on the current directory. Before setup they print hippo is not set up yet and exit 1, naming hippo as the way to start. The exceptions are detect, start, eval without --with-model, packs check, packs test, schedule uninstall and schedule status, which read no configuration (init writes it). A history-only setup has no workspace; commands that need notes say so.

Unless a command says otherwise, an error prints to stderr and the exit code is 1. Set RUST_LOG (for example RUST_LOG=debug) to change the log level; the default is warn, and logs go to stderr.

Start here

Every day

Notes and dreaming

Packs

Setup and checks

Run by hippo itself. Hooks and jobs call these. You rarely type them.

hippo start

hippo start [--yes] [--add-root <path>]...

Finds your agents’ history and indexes it, history only: no notes folder is needed and nothing is sent anywhere. It prints what it found, asks Index it now? [Y/n] on a terminal, writes a history-only config.toml, ingests with progress, then shows the last active day. It never adopts a workspace from the current directory. When hippo is already set up it says so and shows the day.

With no terminal and no --yes it prints run hippo start --yes to index it and exits 0. When it finds no history it names the folders it looked in and exits 0.

hippo detect

hippo detect [--json]

Lists the agent history on this machine without indexing anything and without a configuration: each folder with its files (for OpenCode, the sessions in its database), size and newest day. --json prints one JSON object. hippo reads Claude Code and Codex transcripts, DeepSeek Harness (dsh) session logs and OpenCode’s database. It also reports Cursor and Gemini folders when it sees them, as agents with no adapter: hippo does not read them.

hippo ask

hippo ask <question> [--sources-only] [--limit <n>] [--json]

Has any agent already solved this? It ranks the indexed sessions that match the question, then asks the model for an answer that cites them.

Without --sources-only it runs your model_command (Security and privacy).

hippo fleet

hippo fleet [--json]

Today’s sessions: live, stopped at a usage limit, or finished, and the headroom left on each Claude profile. With no session today it says so and names hippo show day <date>. --json prints one JSON object.

hippo incidents

hippo incidents [--days <n>] [--all] [--json]

What went wrong, which agent did it, at which step, and why when a rule says so.

A check an agent said passed with no run of it after its last edit is listed apart, after the incidents, under Hints to check: a check claimed with no run after the last edit. It is a hint, not an incident: the rule is not yet precise enough to count, so these rows are not counted anywhere. The check counts a run that came through a wrapper script, a remote sandbox, a background task, CI on the pushed head, or a session the agent delegated to; hippo xray <session> shows the evidence it found. --json lists them with the incidents, kind unverified.

hippo xray

hippo xray <session> [--json]
hippo xray --fleet [--days <n>] [--json]
hippo xray unrequire <note> [--yes]

Shows what context a session was given and used, what it searched for, and the evidence for its claims. <session> is a full id or a unique prefix, as hippo fleet prints it.

xray unrequire removes a note from required_notes in .hippo/hippo.toml. It prints the change and writes it only with --yes.

hippo resume

hippo resume <id> [--on <profile>] [--json]

Prints the command that resumes a session, with a short handoff. <id> is a full id or a unique prefix of any indexed top-level session, not only today’s.

hippo brief

hippo brief --task <text> [--off <id>]... [--json]

The start block for a new agent on a task: required and relevant notes, past sessions and kept rules. --off <id> leaves out the part with that id (repeatable; --json lists the ids). --json prints the parts and the block as one JSON object.

hippo card

hippo card [--day <YYYY-MM-DD>] [--week] [--out <path>]

Your agents’ day as one 1200 x 675 PNG to share, and the same words on stdout. It shows the work time the overview shows, the threads and sub-agents, the pull requests merged, how long the agents waited on you and over how many questions, and how many times you corrected them. Nothing else: no project, session title, path, repository, account or profile name is ever drawn or printed, only numbers and a date. It reads the index and the rollup, calls no model and sends nothing anywhere.

A day with no session prints the last active day and exits 1. The card is drawn with an embedded subset of DejaVu Sans, so it looks the same on every machine; the font’s licence is LICENSE-DejaVu.txt beside the binary in a release.

hippo init

hippo init [--workspace <path>] [--notes-dir <dir>] [--entry-note <file>] [--add-root <path>]... [--force]

Writes $HIPPO_HOME/config.toml and, if it does not exist, the workspace’s .hippo/. With no flags and outside a workspace it writes a history-only configuration, the same one hippo start writes.

--notes-dir and --entry-note must be given together. Without --force, init refuses (exit 1, naming the path) if config.toml exists, or if you give the two flags for a workspace that already has a .hippo/. It checks everything before it writes anything. It prints wrote <path> or kept <path> for each path. If .hippo/ exists and you give neither flag, it keeps .hippo/ and writes only config.toml. In a workspace that is already set up (its config.toml names this workspace), init with no flags does not refuse: it only adds the git rules below and says so.

Whenever it writes or keeps a workspace, init adds the lines that are missing (and only those) to .hippo/.gitignore (snapshots/, sessions/, reports/, dream-state.json), the workspace’s .gitignore (/<log_path>) and its .gitattributes (/<notes_dir>/**/*.md merge=union), printing updated <path> for a file that gained lines. See Sharing a brain in a team.

If the notes folder does not exist, init creates it (created <dir>/ (it did not exist)). If the entry note does not exist, it writes a starter entry note you can edit (wrote <note> (a starter entry note: edit it)). It never overwrites a file. When you add a workspace to a history-only setup whose index already holds sessions, it prints <n> sessions are indexed (sub-agents included): run hippo ingest --full to give the ones that belong to this workspace a session record.

hippo add

hippo add <source> [--registry <index.json>] [--dry-run]

Copies a pack into .hippo/packs/<name>/ after checking it and having it reviewed in a fresh context. <source> is a path (./dir, ../dir, /dir, ~/dir) or an https git URL, https://host/repo[//dir][@ref], or the name of a pack listed in a registry index.

It prints the summary (pack, source, a pass line for each pass, a template line for each template, files), then review <id> <verdict>: <notes>, then wrote .hippo/packs/<name>/. Exit 1 when the pack does not validate, when its name or a pass name is already used, when the reviewer rejects it, and when the review cannot run. Packs shows the output and what each step does.

hippo ingest

hippo ingest [--full]

Walks transcript_roots, indexes every transcript whose content changed, and creates a derived session record for every transcript that has no declared one and belongs to the workspace: the session ran inside the workspace’s folder (or one of its git worktrees), or read, edited or cited one of its notes. Other projects’ sessions are indexed but leave nothing in the workspace. Output: indexed <n> files, skipped <m>, derived <k> sessions; when it removed records of other projects’ sessions (a workspace written by an older version is cleaned once), a second line says how many and why. If another ingest is running it prints ingest already running and exits 0.

A transcript that fails to parse is recorded, skipped until it changes, and shown by hippo doctor. A line that is not valid JSON is skipped with a warning. Redaction runs before any text is indexed (Security and privacy).

hippo recall

hippo recall <query> [--limit <n>] [--json] [--raw]

Searches every indexed turn: user text, assistant text, tool calls and tool results. Results are ranked by relevance, newer turns first among equals.

Text output is one line per turn: <session> <tool> <ts> <role> [<tool_name>] <snippet>. The snippet has line breaks and runs of spaces folded into single spaces. <tool_name> appears only for tool turns. With no index, the command fails; run hippo ingest first.

hippo context

hippo context [--task <text>] [--session <id>] [--budget <bytes>] [--parts required|optional|all] [--json]

Prints the context block described in The context budget.

Parts that did not fit go to stderr as omitted: <part> (<bytes>). If the required parts exceed the budget, the command prints context over budget: <required> > <budget> and exits 1.

With --json the command prints one line with the block and how it was built: text (the block), bytes (its size), budget, omitted (a list of {"part", "bytes"} for each part that did not fit, which --json does not also print to stderr), required (the notes the block’s required: part names, as paths relative to the workspace) and relevant (the notes its relevant: part lists, in order, as paths). Each is empty when its part was not compiled or was omitted.

$ hippo context --task "how long do we keep the nightly backups" --json
{"budget":25600,"bytes":400,"omitted":[],"relevant":["notes/Search index.md","notes/Backups.md"],"required":[],"text":"# START HERE\n\nTern is an open-source, ... \nlinter: overdue=0 dangling=0\n"}

(The text is shortened here.)

hippo show

hippo show session <id> [--json]
hippo show proposal <id> [--json]
hippo show note <path> [--json]
hippo show day [YYYY-MM-DD] [--offset +01:00] [--json]

Read-only. It prints what the desktop work needs to show: a session’s turns, a dreaming proposal with its receipts and evidence, and a note’s lint findings and receipts. It needs an index (run hippo ingest first). Text output folds each text onto one line; with --json each record is printed compact, as its file holds it.

<path> is relative to the workspace. An unknown session id exits 1 with no session <id>; an unknown proposal id exits 1 with no proposal <id>.

$ hippo show session eval-01
- 09:12 claude-code eval-01 — check how long backups are kept — ended 09:15 — turns 13 — notes: [[Backups]] — handoff: no — dreaming: 1 confirmed, 0 rejected
0 user can you check how long nightly backups are kept? i think the cron job prunes old dumps
1 assistant Looking at the prune job now. Nightly backups are still kept for 14 days in the config I remember.
...
$ hippo show proposal 01M6X6VZNF8X666HVGCVJZD4FE
proposal 01M6X6VZNF8X666HVGCVJZD4FE consolidate notes/Backups.md replace
old: Nightly backups are kept for 14 days.
new: Backups are now kept for 30 days after the retention change.
reason: stub
receipt 01M6X6VZNTGPYXYWFBCW5RQFXH confirm consolidate-reviewer applied 2026-11-08T09:12:13.258708Z stub
receipt 01M6X6VZSSTVQA135WF8HE5VW3 revert human applied 2026-11-08T09:12:13.363188Z 
evidence eval-01 7 assistant Backups are now kept for 30 days after the retention change.
$ hippo show note notes/Backups.md
receipt 01M6X6VZNTGPYXYWFBCW5RQFXH confirm 01M6X6VZNF8X666HVGCVJZD4FE 2026-11-08T09:12:13.258708Z
receipt 01M6X6VZSSTVQA135WF8HE5VW3 revert 01M6X6VZNF8X666HVGCVJZD4FE 2026-11-08T09:12:13.363188Z

(That run used the synthetic eval set and a stand-in model.)

hippo session

hippo session start --tool <claude-code|codex|dsh|opencode|muse|command-code> --session <id> [--task <text>]
hippo session end --session <id> [--note <path>]... [--handoff <file>|-] [--no-change <reason>]

Both subcommands print nothing on success.

start writes a declared session record, or reopens an existing declared one with the same id (its ended is cleared, and everything else, including the task, is kept). An id that is not 1 to 128 letters, digits, _ or - exits 1 with invalid session id.

If you give neither --note nor --handoff nor --no-change, the session records the reason unspecified.

hippo config

hippo config show
hippo config set <key> <value> [--yes]
hippo config unset <key> [--yes]
hippo config add <key> <value> [--yes]
hippo config remove <key> <value> [--yes]

Shows or changes one setting in config.toml or .hippo/hippo.toml. It prints the change and writes it only with --yes.

model_command takes a JSON array of strings or words separated by spaces, and is written as a one-line array:

hippo config set model_command '["claude","-p","--output-format","json"]' --yes
hippo config unset model_command --yes

The second command restores the default.

hippo hooks

hippo hooks install [--agent <claude-code|codex>] [--workspace <dir>]
hippo hooks uninstall [--agent <claude-code|codex>] [--workspace <dir>]
hippo hooks status [--agent <claude-code|codex>] [--workspace <dir>]

Adds, removes or checks hippo’s three hooks (SessionStart, UserPromptSubmit, SessionEnd). For Claude Code, the default, they go in the workspace’s .claude/settings.json (--workspace names another workspace). With --agent codex they go in $CODEX_HOME/hooks.json (~/.codex/hooks.json), which Codex runs for every session; the hooks themselves act only for sessions in the workspace. install adds each once and keeps everything else in the file. uninstall removes only hippo’s three. status says which of the three are there.

Codex runs a new hook only after you trust it: it lists hippo’s hooks for review the next time it starts, or use /hooks. hippo never writes that trust for you.

hippo hook

hippo hook session-start [--plugin] [--agent <claude-code|codex>]
hippo hook prompt [--agent <claude-code|codex>]
hippo hook session-end [--agent <claude-code|codex>]

For Claude Code hooks, and with --agent codex for Codex hooks (below). Each reads the hook’s JSON on stdin (it needs session_id; prompt also needs prompt). See Quick start for the settings to add. A hook always exits 0. On any error it prints hippo hook: <error> on one line to stderr.

With --agent codex each reads Codex’s hook input and does nothing at all unless hippo has a workspace and the input’s cwd is in it. The session id is codex-<session_id>, the id the Codex adapter gives the same session. session-start and prompt print the same parts as JSON Codex reads ({"hookSpecificOutput": {"hookEventName": …, "additionalContext": …}}); prompt passes over a sub-agent’s prompt (one with an agent_id). session-end records the last assistant message of the session’s transcript as a derived handoff, or ends it unspecified when the transcript cannot be read.

hippo log

hippo log [--stdout]

Writes the session log to log_path and prints the path. With --stdout it prints the log and writes nothing. The log lists sessions newest first, grouped by day, with their task, turn count, notes, whether a handoff exists, and how many dreaming changes were confirmed and rejected. A session with no indexed transcript, such as a declared one whose transcript is not under transcript_roots, shows ? for its turns.

hippo doctor

hippo doctor [--model]

Prints a table check | status | detail, one row per check. Status is ok, warn or problem. Exits 1 if any row is a problem, else 0. A healthy new setup passes: a schedule or a dreaming run that does not exist yet is an ok row whose detail starts not set up yet:. See Troubleshooting.

Without --model the model row says not checked, or warns when the program is not on PATH.

The git row reads git (it never writes through it): when the workspace is in a git work tree, it warns when git tracks a per-person file (.hippo/sessions/, reports/, snapshots/, dream-state.json, the session log), naming them and the two commands that stop tracking them, or when one is not ignored, naming hippo init. See Sharing a brain in a team.

hippo dream

hippo dream [--pass <name>] [--dry-run] [--no-lessons]

Runs the dreaming passes over the window since the last success. See Dreaming.

On success it prints one line: the report’s path, then the counts of the run.

/home/you/work/.hippo/reports/2026-11-08-dream.md: 9 chunks, 1 proposals, 0 validation failures, 1 confirmed, 0 rejected, 1 applied

It prints each pass’s skip reason (consolidate: no note to work on) and, when nothing was proposed, what dreaming needs: notes that the window’s sessions touched. The window is the last 24 hours on a first run.

Exit codes: 0 on success; 2 when the run fails, for example when the model cannot be reached. A failed run still writes its report, with status: failed.

hippo lessons

hippo lessons [--all] [--json]
hippo lessons scan [--days <n>] [--dry-run] [--candidates] [--json]
hippo lessons keep <id> [--text <text>] [--title <title>]
hippo lessons dismiss <id>
hippo lessons propose --question <q> --answer <a> [--note] [--json]
hippo lessons propose --miss <session>:<turn> [--json]

Corrections and repeated failures, proposed as rules. With no subcommand it lists the lessons waiting in the Inbox; --all lists every lesson and --json prints one JSON object.

hippo review

hippo review --ok <receipt>...

Marks applied dreaming changes as read and right. <receipt> is the id of a confirm receipt. --ok is the only mark there is.

hippo revert

hippo revert <receipt> [--force]

Restores a note from the snapshot of an applied change and writes a revert receipt. <receipt> is the id of the confirm receipt (the file name in .hippo/receipts/ without .json, also listed under ## Applied in the report).

restored notes/Topic A.md from .hippo/snapshots/01M6X4WX5356BKSXXW2CDBY5Z8/notes/Topic A.md; revert receipt 01M6X4WX8PG69HNXDWZAQK7H5X

Exit 1 when the id is not a receipt id, when the note was edited since the change (without --force), and when the receipt is not an applied confirm receipt, its snapshot is outside .hippo/snapshots/, or the snapshot does not match its recorded hash (even with --force).

hippo eval

hippo eval <set> [--with-model]

Measures context, recall and dreaming on an eval set directory and prints a Markdown report. See Measuring with hippo eval.

Exit 1 after printing the report if a suite failed. Without --with-model it reads no configuration and runs no model.

hippo schedule

hippo schedule install [--job ingest|dream]
hippo schedule uninstall [--job ingest|dream]
hippo schedule status

Schedules ingest and dreaming. On macOS it manages two launchd jobs; see Scheduling. On any other system it writes nothing and prints what to copy. --job limits install and uninstall to one job.

Exit 0 elsewhere. Without a notes folder, install schedules the ingest job only.

hippo packs

hippo packs check <dir>
hippo packs test <dir> [--case <name>]
hippo packs list
hippo packs diff <name> [--ref <ref>]
hippo packs update <name> [--ref <ref>] [--keep-local] [--accept-reads]
hippo packs remove <name> [--force]

check and test read only the pack directory <dir>: no configuration and no workspace, and test uses a stand-in model, never your model_command. check validates the pack and prints skipped, error and warning lines, then ok <name> <version>; it exits 1 on any error and 0 with warnings alone. test runs the pack’s fixture tests, prints ok <pack>/<case> or FAIL <pack>/<case>: <reason> for each, and exits 1 on any failure. --case <name> runs one case.

list, diff, update and remove read config.toml and work on .hippo/packs/ of the workspace. They finish an interrupted update first.

--ref <ref> reads another branch, tag or commit of a git source. diff, update and remove exit 1 on a refusal. Packs shows the output of each, and Writing a pack gives the rules for check and test.