Philosophy: cli-printing-press

hypha is built to the principles laid out in cli-printing-press — a manifesto for agent-native CLIs. The relevant tenets and how hypha honours them:

cli-pp principlehypha
Agent-native by defaultCompact YAML is the default; --json is opt-in for pipelines.
Typed exit codes0 success, 2 user error, 3 not found, 4 network, 5 cache corruption, 7 environment, 8 tool missing — every failure is classifiable without parsing error text.
Local-first data layerSQLite caches (per-project + shared global), an on-disk Hoogle DB, ETag-revalidated Hackage HTTP cache, and a fuzzy index — all built so repeat queries stay off the network.
Compact mode for tokensCompact YAML is the default; --select f1,f2 projects fields; --full is opt-in. --json for machine pipelines. No HTML noise.
Human + machine output modesYAML for agents/terminals, --json for pipelines, HTMX-rendered HTML for the server UI — same data, three surfaces.
Actionable errorsEvery failure envelope carries a stable code and an actions map suggesting the next command to try.
Verified, not vibesProperty tests via falsify, golden output regressions via tasty-golden, edge cases via tasty-hunit. CI gates merges.
Non-obvious insightSymbols resolve to the canonical declaration across re-exports — through several modules, and into another package, so base's façades resolve into ghc-internal — which is the value raw Hackage HTML cannot give you. CPP is preprocessed with the macros the build plan implies, so #if-guarded code is read from the branch your compiler would compile rather than from whichever branch an empty macro environment happened to select; the few modules that still fail to parse are reported rather than guessed at.
Dual interface from one specThe hypha CLI, the hypha-mcp JSON-RPC shim, and the hypha server HTML UI share one library — no duplicated client/store code.

CLI vs MCP — the cli-pp split

cli-printing-press is explicit that CLIs win for agents (cheaper tokens, native to shell-trained LLMs) and MCP wins for IDE auto-discovery. hypha follows that split:

  • Agents should call hypha directly through a shell tool. The Claude Code skill (skills/hypha-haskell/SKILL.md) tells the model to prefer Bash hypha … over the MCP tools.
  • hypha-mcp exists for IDE/MCP-only harnesses (Claude Desktop, Cursor, opencode without a shell). It exposes one MCP tool per CLI subcommand (hypha.lookup, hypha.symbol, …) so IDE auto-discovery surfaces structured arguments; the generic hypha.exec remains as an escape hatch. See MCP Host Integration.