xcaffold graph

Parses .xcaf manifests and renders a visual dependency graph.

The graph command builds a directed acyclic graph (DAG) of the current configuration scope, showing how agents relate to skills, rules, MCP servers, memory, policies, hooks, and workflows. Output can be rendered as a terminal tree, Mermaid diagram, Graphviz DOT file, or JSON edge list.

Usage:

xcaffold graph [file] [flags]

Flags

Behavior

Terminal tree

The default terminal format renders each agent as a tree node with its tools, linked skills, rules, MCP servers, and memory entries nested beneath it. Branch glyphs use │, ├──, and └── aligned at column 2:

  ● agent-name
  │   tools    Read  Bash
  │
  ├── skills
  │    ├── skill-a
  │    └── skill-b
  │
  ├── rules
  │    └── rule-a
  │
  └── memory  (2 entries)
       ├── project-context
       └── coding-standards

The header breadcrumb uses · as a separator (falls back to . when --no-color is set or NO_COLOR is set). Kinds with zero resources are omitted from the header count. The count includes agents, skills, rules, MCP servers, policies, and hooks.

Output formats

• terminal — Default. Stylized tree view suitable for interactive inspection.
• mermaid — Mermaid.js compatible markdown block. Pipe to a file or include in docs.
• dot — Graphviz DOT format. Combine with dot -Tsvg to produce network diagrams.
• json — Machine-readable array of nodes and edges. Suitable for CI/CD integration.

All non-terminal formats include policy, hook, and workflow nodes when present in the configuration.

Scope

By default, xcaffold graph operates on the project-level manifest in the current directory. Pass a file path as a positional argument to target a specific .xcaf file directly. Use --global to switch to the user-wide global scope, --project to target a registered project by name, or --all to render global topology plus all registered projects.

Scanning undeclared artifacts

When --scan-output is provided, the command scans the compiled output directory for files that are present on disk but not declared in the current manifest. Undeclared entries are included in the disk_entries array in JSON mode and as additional nodes in mermaid and dot modes. This flag has no effect in terminal mode.

Sample output

Terminal — project graph

sandbox  ·  2 agents  ·  3 skills  ·  4 rules

  ● auth-specialist
  │   tools    Read  Bash
  │
  ├── skills
  │    ├── feature-lifecycle
  │    └── commit-changes
  │
  ├── rules
  │    └── secure-coding
  │
  └── memory  (2 entries)
       ├── project-context
       └── coding-standards

Mermaid output

xcaffold graph --format mermaid

Exit codes

Examples

Display the full project dependency graph:

xcaffold graph

Inspect a single agent's dependency tree:

xcaffold graph --agent auth-specialist

Target a registered project by name:

xcaffold graph --project my-api

Show global topology and all registered projects:

xcaffold graph --all

Export a Mermaid diagram:

xcaffold graph --format mermaid > architecture.md

Export a Graphviz DOT file:

xcaffold graph --format dot | dot -Tsvg > graph.svg

Inspect the global scope graph:

xcaffold graph --global

Scan for undeclared output artifacts:

xcaffold graph --scan-output

Show expanded topology for a project:

xcaffold graph --full

Export machine-readable JSON for CI:

xcaffold graph --format json | jq .