Skip to content

Houmao Docs

Houmao is a framework and CLI toolkit for building and running teams of CLI-based AI agents (claude, codex, gemini) as real tmux-backed processes — each with its own isolated disk state, native TUI, and gateway sidecar. Houmao also supports copilot as a system-skill install target. This site covers the full reference, getting-started guides, and developer internals for installed users, with additional material for contributors.

Who you are Where to start
Installed user (uv tool install houmao) Install system skills with npx skills add igamenovoer/tool-skills/houmao when npx and internet are available; use houmao-mgr system-skills install for offline/package-local or customized installs. Then start your agent and invoke houmao-touring or ask $houmao-touring help.
From-source developer (pixi install) Quickstart - agent-driven first-run guide with source-checkout pixi run houmao-mgr ... launcher notes
Contributor to Houmao CLAUDE.md or AGENTS.md for repo conventions and development commands

Getting Started

  • Architecture Overview: Two-phase lifecycle, backend model, and high-level design.
  • Agent Definitions: Agent definition directory layout — tools, roles, recipes, launch profiles, and skills.
  • Quickstart: Start with Houmao system skills, invoke houmao-touring, and run your first managed-agent workflow through your CLI agent.
  • Easy Specialists: The easy lane — specialists, optional project profiles, and instances.
  • Launch Profiles: Reusable birth-time launch configuration — project profiles, native launch dossiers, and the precedence chain.
  • Managed Agent Memory: Per-agent memory roots, free-form memo files, pages, the default memo cue, and the houmao-memory-mgr skill.
  • System Skills Overview: Narrative tour of every packaged Houmao-owned system skill, when each one fires, and how managed-home auto-install differs from explicit CLI-default install.
  • Loop Authoring Guide: Choose houmao-agent-loop-lite for Markdown/direct-SQL loops or houmao-agent-loop-pro for schema-rich topology loops, then discover the graph tooling that supports pro generated execplan authoring.

Reference

CLI Surfaces

  • houmao-mgr: Primary management CLI for agents, projects, mailbox, system skills, internals, and local workflow control.
  • houmao-passive-server: Maintained registry-driven API server for discovery, observation, request submission, gateway proxying, mail proxying, and managed-headless agents.
  • system-skills: Install and inspect packaged Houmao-owned skill sets for resolved tool homes.
  • agents gateway: Scoped agents single ... gateway and agents self gateway lifecycle and request commands.
  • agents external: Local imports for remotely owned communication-only managed agents.
  • agents turn: Scoped managed headless turn submission and inspection.
  • agents mail: Scoped managed-agent mailbox follow-up commands.
  • agents mailbox: Scoped late filesystem mailbox registration for local managed agents.
  • admin cleanup: Registry and runtime maintenance commands.
  • internals: Native-agent internals plus NetworkX-backed graph helpers for pro loop execplan authoring, structural analysis, and packet validation.
  • CLI Entrypoints: Module-level entry points and common runtime flags.

Build Phase

Run Phase

  • Launch Plan: Composing manifest + role into a backend-specific launch plan.
  • Session Lifecycle: Start, resume, prompt, stop, and relaunch sessions — including the 0.8.0 --reuse-home fresh launch mode that reuses an existing brain home for fast restarts without rebuilding.
  • Degraded and Stale Active Recovery: Probe-first dispatch and recovery paths for local tmux-backed managed agents whose registry record claims active but whose tmux session is broken.
  • Backends: Backend model — local interactive, headless, and legacy/internal compatibility paths.
  • Role Injection: Per-backend role injection strategies.
  • Managed Launch Prompt Header: Houmao-owned prompt header with six independently controllable sections prepended to every managed launch by default — memo cue, content, per-section control, composition, opt-out flags, and stored launch-profile policy.

Subsystems

  • Gateway: Per-agent FastAPI sidecar for session control and mail. Includes control-intent coalescing so multiple rapid control requests collapse into a single dispatch, and a mail-notifier context-recovery policy (context_error_policy and pre_notification_context_action) for handling degraded TUI posture before wake-up delivery.
  • Mailbox: Unified mailbox protocol — filesystem and Stalwart JMAP.
  • TUI Tracking: State machine, detectors, and replay engine.
  • Lifecycle: Turn-anchored readiness and completion detection.
  • Agent Registry: Session discovery and managed agent records — now lifecycle-aware so records track active, stopped, relaunching, and retired states across stop-and-relaunch workflows.
  • Terminal Record: tmux session recording and replay.
  • System Files: Filesystem layout and owned paths.

Other Reference

Developer Guides

Resources

Examples

  • Writer Team: A complete tree loop example — three agents (story-writer, character-designer, reviewer) collaborating on a multi-chapter story. Contains role prompts, a tree loop plan, start charter, and local setup commands.