Skip to the content
hippo
Contents
  1. Introduction
  2. Install
  3. Quick start
  4. Concepts
  5. Architecture
  6. Packs
    1. Writing a pack
    2. First-party packs
    3. The registry
    4. Themes
  7. Commands
  8. Configuration
  9. Sharing a brain in a team
  10. Scheduling on macOS
  11. Measuring with hippo eval
  12. Troubleshooting with hippo doctor
  13. Security and privacy
  14. Roadmap
  15. Limits and known gaps
  16. Contributing and licence

Limits and known gaps

hippo is early software at version 0.4.1. This page lists what you should expect to go wrong or be missing.

Scope

  • Six tools. Only Claude Code and Codex transcripts, DeepSeek Harness (dsh) session logs, OpenCode’s database, Muse Code session logs and Command Code sessions are read. There are no adapters for other agents.
  • One workspace per configuration. config.toml names one workspace.
  • Sharing a brain is through git. Several people can commit one workspace; hippo init keeps per-person state out of git. Nothing syncs live, each person’s dreaming learns only from their own sessions, and hippo revert works only on the machine that dreamed the change (git is the undo elsewhere). See Sharing a brain in a team.
  • The desktop app is macOS only and early. Hippo.app (in app/, built from source) has been checked on synthetic data, not in daily use. Everything it shows is also on the command line.
  • The feed is not live. The hippo-feed crate and its deployment files exist. Nothing is deployed, so there is no feed to sign in to, vote on or read.
  • Hooks only for Claude Code and Codex. dsh, OpenCode, Muse Code and Command Code sessions are always derived records: no task, no declared notes, and so is a Codex session that did not run hippo’s hooks. Nothing should depend on one being declared. The dsh plugin gives a dsh session the start block, and the OpenCode plugin an OpenCode session, but neither records anything.
  • Codex runs hippo’s hooks only once you trust them. hippo hooks install --agent codex writes them to $CODEX_HOME/hooks.json; Codex lists them for review at its next start, and skips them until you trust them there or with /hooks. codex exec shows no review. A Codex session started before that is read by ingest as before. Windows is not tried.
  • Scheduling is installed only on macOS (launchd). Elsewhere hippo schedule install prints cron and systemd lines for you to install; hippo cannot see whether they run.
  • Not on crates.io. Install with the install script, the Claude Code plugin’s setup, or cargo install --git (Install).
  • Linux is tested in CI, not in daily use. The release has static Linux binaries (x86_64 and arm64) and the test suite passes on Linux in CI, but hippo is used day to day on macOS on Apple silicon (the Intel build passes the first-run check under Rosetta).
  • Words, not meaning. hippo recall matches the words of your query. A paraphrase that shares no words with the turn finds nothing. The eval set’s paraphrase queries hit 0 of 4. hippo has no embeddings or vector search.
  • Context ranking is by title and headings. The relevant-notes part scores a note by whether words of the task appear in its title or headings. A note whose title does not contain the task’s words may be missed.
  • Lone surrogates. A transcript line holding half of a UTF-16 surrogate pair, such as \ud83d with no partner, is rejected by the JSON parser and its turns are not indexed. hippo logs a warning.
  • Codex tool calls are unconfirmed. The mapping of Codex tool calls and their results follows the OpenAI Responses API schema, but the Codex rollouts checked so far contained no tool calls. Messages were checked against a real rollout. If a rollout’s tool calls do not appear in hippo recall, that is a bug worth reporting.
  • dsh is a developer preview. DeepSeek Harness says its log format will change. hippo reads log formats 3 and 4; a log in any other format is not read, and hippo doctor’s dsh logs row names it. Only dsh’s JSONL storage is read, and only the newest generation of each session. A compressed (.zstd) log is read whole each time it changes.
  • What hippo leaves out of a dsh log. Why a turn ended (turn/end), token counts and rate limits, team mode, workflows, jobs and plugin: records are not read. dsh’s core tools are stored under Claude Code’s names (bash as Bash, read as Read, …), and a failed result is written the way hippo reads a failure (Exit code N, <tool_use_error>), so recall shows those spellings. See the design.
  • OpenCode 2 only. hippo reads OpenCode 2’s tables (session_v2, session_message) and checks them before it reads; hippo doctor’s OpenCode database row says whether a database is read and, when its schema is newer than this hippo knows, says so. OpenCode 1’s tables and JSON files are not read (OpenCode 2 copies them into its own), nor is opencode-next.db. When OpenCode is not running, opening its database makes SQLite create an empty -wal and a -shm file beside it; the database itself is never written.
  • What hippo leaves out of OpenCode. Attachments’ contents (their name, type, size and path are indexed), text OpenCode adds for the model, commands run with !, cost, token counts other than a sub-agent run’s (which Fleet shows, as for Claude Code), and permission prompts (OpenCode keeps those in memory, so Fleet shows a call waiting for permission as running). OpenCode does not record who interrupted a run, so every interruption reads as stopped by you; a reply cut off at the model’s output limit is not shown. Core tools are stored under Claude Code’s names and argument names (shell as Bash, filePath as file_path, …). See the design.
  • Muse Code’s log is undocumented. Muse is closed source, and hippo reads what Muse 1.4.18 wrote in real sessions: prompts, assistant messages, tool calls and their results. A record in a version other than 1 is skipped with a warning in the ingest log. Sub-agent logs, prompts typed while a run is going, and large tool outputs Muse moves to tool-outputs/ are not read, and tool names are kept as Muse writes them. See the design.
  • Command Code: every branch, version 3 only. hippo reads every message of a Command Code session in file order, so a branch the person went back from is indexed with the one they kept. Version 1 and 2 files are reported as files hippo could not read; Command Code converts them when it next opens them. Compaction summaries and sub-agents are not read, tool names are kept as Command Code writes them, and its learned preferences (taste.md) are not read. See the design.
  • Index size. The index of a large transcript history can reach several gigabytes under $HIPPO_HOME. hippo ingest --full is the only maintenance it needs.

Redaction

Redaction is best-effort pattern matching, in both directions: it can miss a secret, and it can redact harmless text. See Security and privacy.

Dreaming

  • A model reviews a model. The reviewer is isolated from the proposer, but both are language models. Dreaming can propose and confirm a wrong change. Every change has a snapshot, a receipt and a revert, and the first runs should use --dry-run.
  • Prompt injection is reduced, not removed. Transcript text reaches the model. See Security and privacy.
  • Notes have many writers. Agents edit notes at any time. hippo guards a write by checking the note has not changed since the prompt was built, but an agent can still overwrite a dreamed change later. The change keeps its receipt and snapshot.
  • The model channel can fail. The default claude command depends on your login and your usage limits. A failed run exits with code 2, writes a failed report, and hippo context warns every agent within 36 hours. The window does not advance past a failed day.
  • It is not measured on your notes. The eval harness measures the shipped set, which is small, invented and has one author. Its numbers describe that set, not your workspace.
  • Whether hippo’s results hold on real daily use is not established. It is early; treat results as unproven until you have measured them on your own notes.

Packs

  • Not measured. None of the 23 first-party packs has been run against real notes with a real model, and the eval set does not cover them. A pack’s fixture test uses a stand-in model, so it shows the wiring and nothing about quality.
  • No hosted index of packs. The 26 first-party packs are listed in the registry, and no hosted index is published. You build the index and the site from a checkout, and hippo add <name> --registry <index.json> reads a file on your disk (The registry). Without one, hippo add takes a path or a git URL.
  • No pack by another author. Every pack so far is by the project’s author.
  • A review is a model’s review. A pack is listed only with a fresh-context review. It is a language model’s judgement and not a guarantee.
  • Web themes load nowhere yet. The three theme packs install with hippo add, and Hippo.app’s theme picker lists their desktop themes, but no running site offers their web themes (Themes).
  • A pack’s reviewer is hippo’s, not the pack’s. A pass outside the core pack is reviewed by hippo’s own persona, and the pack’s persona can only add reasons to reject. Its appends are capped at 2,048 bytes.
  • Validation is pattern matching. hippo packs check warns about links, shell-shaped text and phrases that look like prompt injection. It cannot tell whether a prompt is wise. Read a pack’s prompt before you copy it.

Operations

  • Session handoffs depend on your instructions. hippo cannot make an agent run hippo session end --handoff. Without handoffs, consolidate has nothing to work from and hippo doctor reports a problem.
  • A one-time prompt on external volumes. macOS may block the first scheduled run until you answer a permission prompt. See Scheduling.
  • hippo init --force overwrites your core pack edits.
  • A crash between applying a change and writing its receipt leaves a snapshot with no receipt. hippo doctor reports it as a problem.
  • The YAML parser is unmaintained upstream. Note frontmatter is parsed with serde_yaml_ng, which uses unsafe-libyaml, listed by RustSec as unmaintained (RUSTSEC-2024-0449). The repository’s deny.toml ignores that one advisory until the project decides whether to keep or replace it.