Skip to content

Houmao Docs

Houmao is a framework and CLI toolkit for building and running teams of CLI-based AI agents (claude, codex, kimi) as real tmux-backed processes — each with its own isolated disk state, native TUI or maintained headless lane, 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 from https://github.com/igamenovoer/houmao-skills with npx skills add, select the complete admin surface, then start your assistant and ask $houmao-admin-welcome start-guided-tour.
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

The public system-skill collection has six static roots: admin welcome, both actor entrypoints, shared routines, and the pro and lite loops. Actor entrypoints delegate ordinary work to the shared sibling; both loops remain top-level manual skills. The unqualified houmao-skills repository URL tracks the latest stable release, while a fragment such as #v2.2.0 selects the matching version explicitly. Use houmao-mgr system-skills install for package-local, offline, or config-managed pack installation.

Getting Started

  • Architecture Overview: Two-phase lifecycle, backend model, and high-level design.
  • Agent Definitions: authoring, immutable revisions, single and batch deployment, per-instance state, private workspaces, and the projected directory layout.
  • Quickstart: Install released skills from houmao-skills, invoke houmao-admin-welcome, 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 shared memory-mgr route.
  • System Skills Overview: Static roots, actor packs, welcome paths, shared child routes, direct invocation, and installation choices.
  • Loop Authoring Guide: Choose the top-level houmao-agent-loop-lite skill 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, inspect, upgrade, and remove config-owned actor packs in 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.