houmao-mgr internals¶

Internal Houmao utility commands for agents and maintainers.

houmao-mgr internals exposes utility command families for maintainers and agent tooling. graph provides NetworkX-backed helpers for loop plan authoring, structural analysis, and low-level graph manipulation. native-agent exposes direct provider-aligned file-tree maintenance that is intentionally not ordinary project UX.

When to use these commands¶

graph high is designed for loop plan authoring and validation. When an agent is building or validating houmao-agent-loop-pro execplan topology artifacts, these commands give it deterministic structural facts — root reachability, packet expectations, validation errors, and Mermaid scaffolding — without requiring graph reasoning inside the skill prompt. Older mode names such as pairwise-v2 can still appear as graph-helper compatibility values; they are helper modes, not current loop skill names.

graph low is for generic graph construction and NetworkX algorithm access. Use it when you need to build or transform a graph from scratch, extract subgraphs, or run standard graph algorithms not covered by the high-level surface.

All graph commands accept a node-link JSON file via --input (or --graph where noted) and use - to read from stdin. Commands that produce a graph output emit NetworkX node-link JSON with nodes, edges, and graph keys.

native-agent¶

Direct native-agent commands operate on a selected native-agent root. Pass --native-agent-root <dir> on the leaf command or set HOUMAO_NATIVE_AGENT_ROOT to an absolute path. These commands do not discover or mutate a Houmao project catalog.

credentials¶

Manage direct native-agent credentials under tools/<tool>/auth/<name>/.

houmao-mgr internals native-agent credentials <tool> list|get|add|set|login|rename|remove --native-agent-root <dir>

Supported tool lanes are claude, codex, and gemini. The per-tool credential input flags match the corresponding project credential surface, including --auth-token, --oauth-token, and --config-dir for Claude credential commands. Use houmao-mgr project [--project-dir <dir>] credentials <tool> ... for project-backed credentials.

brain build¶

Build one brain home directly from native-agent material.

houmao-mgr internals native-agent brain build --native-agent-root <dir> --preset <name>

The internal build command accepts the retained direct build inputs: --preset, --tool, repeatable --skill, --setup, --auth, --runtime-root, --home-id, --reuse-home, --launch-overrides, --agent-name, and --agent-id. The maintained flag names are --preset, --setup, and --auth; retired top-level brain-build examples using --recipe, --config-profile, --cred-profile, or --agent-def-dir are not current. Ordinary project launches build brain homes internally through houmao-mgr project agents launch.

config-drafts¶

Generate concise YAML configuration drafts from sparse JSON intent without mutating project or native-agent state.

houmao-mgr internals config-drafts list
houmao-mgr internals config-drafts generate --id <draft-id> --intent '<json>'

Supported draft ids are project.specialist, project.profile, and internals.native-agent.launch-dossier. The --intent value accepts an inline JSON object, - for stdin, or a path to a JSON file. Intent JSON must be an object with a top-level fields mapping.

Examples:

houmao-mgr internals config-drafts generate --id project.specialist --intent '{"fields":{"name":"general-kimi","tool":"claude","credential":"kimi-coding"}}'
houmao-mgr internals config-drafts generate --id project.profile --intent '{"fields":{"name":"reviewer-fast","specialist":"reviewer","credential":"reviewer-creds"}}'
houmao-mgr internals config-drafts generate --id internals.native-agent.launch-dossier --intent '{"fields":{"name":"reviewer-native","recipe":"reviewer-codex","credential":"reviewer-creds"}}'

When intent JSON is invalid or has the wrong shape, the command prints a fix guide with the selected draft id, --intent source, JSON Schema-style expected shape, required fields.* paths, and a valid example.

graph high¶

Houmao-aware loop graph helpers.

analyze¶

Analyze Houmao loop graph structure. Reports root reachability, leaves, non-leaf (delegating) participants, immediate children, cycle or DAG posture, component summaries, branch points, and mode-specific shape warnings.

Synopsis:

houmao-mgr [--print-json] internals graph high analyze [OPTIONS]

Option	Required	Default	Description
`--input PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--root TEXT`	no	`graph.root`	Root node override.
`--mode TEXT`	no	`graph.mode`	Mode override (e.g. `pairwise-v2`, `generic`).
`--cycle-limit INT`	no	`20`	Maximum cycle examples to include in the result.

Examples:

houmao-mgr --print-json internals graph high analyze --input graph.json
houmao-mgr internals graph high analyze --input graph.json --root master --mode pairwise-v2

packet-expectations¶

Derive pairwise-v2 routing-packet expectations from graph topology. Returns the expected root packet shape, one child packet expectation per pairwise edge, non-leaf dispatch-table expectations, and freshness-marker requirements. Use the output to author or audit routing packets before a pairwise-v2 run.

Synopsis:

houmao-mgr [--print-json] internals graph high packet-expectations [OPTIONS]

Option	Required	Default	Description
`--input PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--root TEXT`	no	`graph.root`	Root node override.

Examples:

houmao-mgr --print-json internals graph high packet-expectations --input graph.json
houmao-mgr internals graph high packet-expectations --input graph.json --root master

validate-packets¶

Validate pairwise-v2 routing packets against graph-derived expectations. Checks for missing root packets, missing child packets, stale revisions or digests, intended-recipient mismatches, immediate-driver mismatches, missing dispatch tables, and missing exact child packet text or references. Returns a structured validation result with any errors.

Packet JSON shape: root_packet plus child_packets, where each packet includes intended_recipient, immediate_driver, freshness markers, and optional child_dispatch_table entries with packet_text or packet_ref.

Synopsis:

houmao-mgr [--print-json] internals graph high validate-packets [OPTIONS]

Option	Required	Default	Description
`--graph PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--packets PATH`	yes	—	Pairwise-v2 routing packet JSON document.
`--root TEXT`	no	`graph.root`	Root node override.

Examples:

houmao-mgr --print-json internals graph high validate-packets --graph graph.json --packets packets.json
houmao-mgr internals graph high validate-packets --graph graph.json --packets packets.json --root master

slice¶

Extract an authoring-time graph slice as node-link JSON. Supports four slice directions: ancestors, descendants, reachable (all nodes reachable from root), and component (a named component subgraph). Emits a node-link JSON graph preserving all node, edge, and graph metadata for the included elements.

Synopsis:

houmao-mgr [--print-json] internals graph high slice [OPTIONS]

Option	Required	Default	Description
`--input PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--root TEXT`	yes	—	Root node for ancestor, descendant, or reachable slices.
`--direction CHOICE`	yes	—	One of `ancestors`, `descendants`, `reachable`, `component`.
`--component-id TEXT`	no	—	Component ID required when `--direction component`.

Examples:

houmao-mgr --print-json internals graph high slice --input graph.json --root agent-a --direction descendants
houmao-mgr --print-json internals graph high slice --input graph.json --direction component --component-id c1 --root master

render-mermaid¶

Render deterministic Mermaid scaffolding from graph structure. Produces a Mermaid flowchart based on node and edge types in the graph. This is a structural scaffold — final semantic review of loop logic and edge labels belongs in the owning Houmao skill.

With --print-plain (the default), emits the Mermaid text directly. With --print-json, emits a JSON payload with a mermaid field.

Synopsis:

houmao-mgr [--print-json | --print-plain] internals graph high render-mermaid [OPTIONS]

Option	Required	Default	Description
`--input PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--root TEXT`	no	`graph.root`	Root node override.
`--mode TEXT`	no	`graph.mode`	Mode override.

Examples:

houmao-mgr internals graph high render-mermaid --input graph.json
houmao-mgr --print-json internals graph high render-mermaid --input graph.json --mode generic

graph low¶

Constrained NetworkX-style low-level graph primitives. These commands emit node-link JSON graphs and accept node-link JSON as input.

create¶

Create an empty supported NetworkX graph.

Option	Required	Default	Description
`--type CHOICE`	no	`multidigraph`	One of `multidigraph`, `digraph`, `multigraph`, `graph`.

houmao-mgr --print-json internals graph low create --type multidigraph

mutate¶

Apply constrained graph mutation operations. The ops JSON must have an ops array; each op must have an op field (e.g. add_node, add_edge, remove_node, remove_edge, set_node_attr, set_edge_attr, set_graph_attr).

Ops JSON shape: { "ops": [{ "op": "add_node", "node": "agent-a", "attrs": {"kind": "agent"} }] }.

Option	Required	Description
`--input PATH`	yes	NetworkX node-link JSON graph file; use `-` for stdin.
`--ops PATH`	yes	Mutation ops JSON file.

houmao-mgr --print-json internals graph low mutate --input graph.json --ops ops.json

relabel¶

Relabel graph nodes with a JSON object mapping old node IDs to new node IDs.

Option	Required	Description
`--input PATH`	yes	NetworkX node-link JSON graph file; use `-` for stdin.
`--mapping PATH`	yes	JSON object mapping old node IDs to new IDs.

houmao-mgr --print-json internals graph low relabel --input graph.json --mapping mapping.json

compose¶

Compose two node-link graphs (NetworkX compose semantics — nodes and edges from both graphs are merged; right-graph attributes override on conflict).

Option	Required	Description
`--left PATH`	yes	Left graph JSON.
`--right PATH`	yes	Right graph JSON.

houmao-mgr --print-json internals graph low compose --left a.json --right b.json

subgraph¶

Extract a node-induced subgraph. The nodes JSON must have a nodes array of node IDs.

Option	Required	Description
`--input PATH`	yes	NetworkX node-link JSON graph file; use `-` for stdin.
`--nodes PATH`	yes	JSON file with a `nodes` array.

houmao-mgr --print-json internals graph low subgraph --input graph.json --nodes nodes.json

reverse¶

Reverse directed graph edges.

Option	Required	Description
`--input PATH`	yes	NetworkX node-link JSON graph file; use `-` for stdin.

houmao-mgr --print-json internals graph low reverse --input graph.json

ego¶

Compute an ego graph (a subgraph centered on one node within a given radius).

Option	Required	Default	Description
`--input PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--node TEXT`	yes	—	Center node.
`--radius INT`	no	`1`	Ego radius (hop count).
`--undirected`	no	off	Treat graph as undirected for ego expansion.

houmao-mgr --print-json internals graph low ego --input graph.json --node agent-a --radius 2

graph low alg¶

Whitelisted low-level graph algorithm wrappers. All algorithm subcommands share the same option schema; only the options relevant to each algorithm need to be supplied.

Shared option schema¶

Option	Description
`--input PATH`	NetworkX node-link JSON graph file; use `-` for stdin. Required for all alg commands.
`--node TEXT`	Node argument for node-centered algorithms.
`--source TEXT`	Source node for path algorithms.
`--target TEXT`	Target node for path algorithms.
`--distance INT`	Exact-distance value for distance-bounded algorithms.
`--cutoff INT`	Path length cutoff for path-enumeration algorithms.
`--length-bound INT`	Cycle length bound for cycle-enumeration algorithms.
`--limit INT`	Maximum result count for expansive algorithms. Default: `50`.

Subcommand summary¶

Subcommand	Required options (beyond `--input`)	Description
`ancestors`	`--node`	Return all NetworkX ancestors of a node.
`descendants`	`--node`	Return all NetworkX descendants of a node.
`descendants-at-distance`	`--node`, `--distance`	Return descendants at an exact hop distance.
`topological-sort`	—	Return a deterministic topological ordering. Graph must be a DAG.
`is-dag`	—	Report whether the directed graph is acyclic.
`cycles`	—	Return bounded simple cycle examples. Use `--length-bound` and `--limit` to bound results.
`weak-components`	—	Return weakly connected component sets.
`strong-components`	—	Return strongly connected component sets.
`condensation`	—	Return NetworkX condensation graph summary.
`transitive-reduction`	—	Return a transitive-reduction adjacency summary. Graph must be a DAG.
`dag-longest-path`	—	Return a DAG longest path. Graph must be a DAG.
`shortest-path`	`--source`, `--target`	Return one shortest path between source and target.
`all-simple-paths`	`--source`, `--target`	Return bounded simple paths between source and target. Use `--cutoff` and `--limit` to bound results.

Examples:

houmao-mgr --print-json internals graph low alg ancestors --input graph.json --node agent-b
houmao-mgr --print-json internals graph low alg descendants-at-distance --input graph.json --node master --distance 2
houmao-mgr --print-json internals graph low alg cycles --input graph.json --length-bound 6 --limit 10
houmao-mgr --print-json internals graph low alg shortest-path --input graph.json --source master --target agent-b
houmao-mgr --print-json internals graph low alg all-simple-paths --input graph.json --source master --target agent-b --cutoff 5 --limit 20