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) Run houmao-mgr system-skills install --tool claude, start your agent, invoke the houmao-touring skill — or read Easy Specialists for the manual path
From-source developer (pixi install && pixi shell) Quickstart — covers agents join and project-overlay build/launch with pixi run
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: Build a brain and start your first session.
  • Easy Specialists: The easy lane — specialists, optional easy profiles, and instances.
  • Launch Profiles: Reusable birth-time launch configuration — easy profiles, explicit launch profiles, 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 between the three loop skills, understand the pairwise-v2 routing-packet prestart model, and discover the graph tooling that supports plan authoring.

Reference

CLI Surfaces

  • houmao-mgr: Primary management CLI for agents, brains, and server control.
  • houmao-server: HTTP server for session management and TUI tracking.
  • houmao-passive-server: Registry-driven stateless server — no legacy dependencies.
  • houmao-mgr credentials: Dedicated top-level credential-management command family for Claude, Codex, and Gemini, with a matching project credentials wrapper.
  • system-skills: Install and inspect packaged Houmao-owned skill sets for resolved tool homes.
  • agents gateway: Gateway lifecycle and explicit live-gateway request commands.
  • agents turn: Managed headless turn submission and inspection.
  • agents mail: Managed-agent mailbox follow-up commands.
  • agents mailbox: Late filesystem mailbox registration for local managed agents.
  • admin cleanup: Registry and runtime maintenance commands.
  • internals graph: NetworkX-backed graph helpers for loop plan 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, and stop sessions.
  • Backends: Backend model — local interactive, headless, and server-backed.
  • 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.
  • 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.
  • Terminal Record: tmux session recording and replay.
  • System Files: Filesystem layout and owned paths.

Other Reference

Developer Guides

Resources

Examples

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