Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

aasm topology

Visualize agent topology — fleet overview, delegation trees, teams, ancestry lineage, and aggregate statistics.

Synopsis

aasm topology <SUBCOMMAND> [OPTIONS]
SubcommandPurpose
overviewFleet-wide topology overview.
treeRender a subtree rooted at a given agent.
teamShow all agents in a team.
lineageShow the ancestry chain for a given agent.
statsShow aggregate topology statistics.

All subcommands accept the global options, including --output table|json|yaml. Only tree renders as a box-drawing tree; overview, team, lineage, and stats render as tables in the default table mode.

aasm topology overview

Show a fleet-wide topology overview across all teams and root agents.

FlagTypeDefaultDescription
--status <STATUS>string—Filter agents by status (active, suspended, deregistered).
--show-budgetflagoffRequest each agent’s governance level from the server. Only surfaced in --output json/yaml; the table view has no governance column, so this flag has no visible effect in table mode.
 
aasm topology overview --status active

aasm topology tree

Render a delegation subtree rooted at one agent, using box-drawing characters.

NameTypeDefaultDescription
<AGENT_ID>string (arg)—Root agent ID (hex-encoded UUID).
--max-depth <DEPTH>integer—Maximum traversal depth from the root. When omitted, the depth parameter is not sent and the server applies its own default (there is no client-side default). Must be at least 1.
--status <STATUS>string—Filter tree nodes by status.
--show-budgetflagoffRequest each node’s governance level from the server. Only surfaced in --output json/yaml; the tree view has no governance column, so this flag has no visible effect in table mode.
 
aasm topology tree a1b2c3… --max-depth 3

Each node prints as <name> [<status>] <<team_id>> (the <team_id> segment is shown only when the agent has a team). Agent IDs are not printed in tree mode — use --output json if you need them.

└── research-bot [active] <research>
    ├── fetch-worker [active] <research>
    │   └── parse-worker [active] <research>
    └── summarize-worker [active] <research>

aasm topology team

Show all agents belonging to a single team.

NameTypeDefaultDescription
<TEAM_ID>string (arg)—Team ID.
--status <STATUS>string—Filter members by status.
--show-budgetflagoffRequest each member’s governance level from the server. Only surfaced in --output json/yaml; the table view has no governance column, so this flag has no visible effect in table mode.
 
aasm topology team research --status active

aasm topology lineage

Show an agent’s complete ancestry chain, ordered root-first. In table mode the lineage renders as a flat table with columns DEPTH | AGENT_ID | NAME | TEAM | DELEGATION_REASON, followed by a (this is a root agent) note when the agent has no ancestors above it.

NameTypeDefaultDescription
<AGENT_ID>string (arg)—Agent ID (hex-encoded UUID).
--show-permissionsflagoffAfter the lineage, also print the agent’s effective capability set with cascade provenance.
 
aasm topology lineage 778899… --show-permissions

Agent: 778899…  |  Ancestors: 3

┌───────┬──────────┬──────────────┬──────────┬───────────────────┐
│ DEPTH ┆ AGENT_ID ┆ NAME         ┆ TEAM     ┆ DELEGATION_REASON │
╞═══════╪══════════╪══════════════╪══════════╪═══════════════════╡
│ 0     ┆ a1b2c3…  ┆ root-bot     ┆ research ┆ -                 │
│ 1     ┆ d4e5f6…  ┆ fetch-worker ┆ research ┆ fetch upstream    │
│ 2     ┆ 778899…  ┆ parse-worker ┆ research ┆ parse response    │
└───────┴──────────┴──────────────┴──────────┴───────────────────┘

aasm topology stats

Show aggregate topology statistics — total/root/active/suspended/deregistered counts, max depth, teams, orphans, and average children per parent. Takes no flags of its own (uses the global --output). In table mode each metric is its own row.

aasm topology stats --output json

┌─────────────────────┬───────┐
│ METRIC              ┆ VALUE │
╞═════════════════════╪═══════╡
│ Total agents        ┆ 42    │
│ Root agents         ┆ 5     │
│ Max depth           ┆ 4     │
│ Active              ┆ 38    │
│ Suspended           ┆ 3     │
│ Deregistered        ┆ 1     │
│ Teams               ┆ 5     │
│ Orphans             ┆ 0     │
│ Avg children/parent ┆ 2.31  │
└─────────────────────┴───────┘

When present, a Depth histogram (DEPTH | COUNT) and a Team-size histogram (TEAM_SIZE | COUNT) are printed as additional tables below the summary.

Last updated: 2026-07-19 by Bryant