Progressive Disclosure: CLI Windows into Agent Systems

Numbers in this post reflect the system at publication (January 2026). See our team page for current figures.

Agent systems are opaque by design. They make decisions, invoke tools, and coordinate work across dozens of specialists. But when something goes wrong—or when you simply want to understand what’s happening—where do you look?

The answer is progressive disclosure: a layered interface that reveals exactly as much complexity as you need, exactly when you need it.

The Opacity Problem

A modern agent orchestration system might have:

• 40+ specialist agents, each with distinct capabilities
• 700+ skills spanning internal automation and vendor integrations
• 470+ architectural decisions shaping behavior
• Dozens of MCP tool servers providing external capabilities

This complexity is intentional. Agents need access to rich context—domain knowledge, code intelligence, database schemas—to make good decisions. But that same richness creates a visibility problem.

How do you know which agent handles database migrations? What decisions shaped the search system’s ranking behavior? Which tools does the architecture advisor have access to?

Without structured access, you’re left reading source code or hoping the documentation is current.

Progressive Disclosure as Architecture

Progressive disclosure isn’t just a UI pattern. It’s an architectural principle: organize information in layers, each deeper than the last, so users can stop at the level that answers their question.

For agent systems, this translates to CLI commands at increasing depths:

Level	Command	Question Answered
1	orkestra system status	Is everything healthy?
2	orkestra agents list	What agents exist?
3	orkestra agents info <name>	What does this agent do?
4	orkestra decisions search	Why does it work this way?
5	Maguyva MCP tools	Show me the code.

Each level answers a natural follow-up question. You rarely need to jump straight to level 5.

Level 1: System Health

The first question is always: is everything working?

$ orkestra system status

on
{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

One command. Four numbers. Enough to know the system is configured and the registries are populated.

If an agent count drops unexpectedly or skills fail to load, you see it here first. No log diving required.

Level 2: Agent Inventory

Once you know the system is healthy, the next question is: what’s available?

$ orkestra agents list

This returns structured data—agent names, descriptions, model preferences, domain coverage. The output is JSON by default, making it easy to pipe into jq for filtering:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Want agents that handle database work? The search command narrows it down:

$ orkestra agents search "database"

This scans names, descriptions, and capabilities. You find the right specialist without reading 40 agent definitions.

Level 3: Agent Deep Dive

Found an agent that looks relevant? The info command reveals everything:

$ orkestra agents info architecture-advisor

The output includes:

• Metadata: Name, category, model preference, description
• Domains: Which knowledge areas this agent covers
• Identity: Character traits (architect, strategist, knowledge-architect)
• Tool guides: Which tool documentation is injected into context
• Tools: The full list of MCP tools available to this agent

Here’s a sample of what you see:

on
{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

This tells you exactly what the agent can do. No source code required.

Level 4: Decision Archaeology

Agents behave according to documented decisions. When you need to understand why something works a particular way, the decisions registry is the source of truth.

$ orkestra decisions search "agent"

This returns matching architectural decisions:

on
{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Each decision has full provenance—when it was made, why, what trade-offs were considered, which commits implemented it:

$ orkestra decisions info DEC-SR-049

on
{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

This is architectural documentation that stays current because it’s mined from commits, not manually maintained.

Level 5: Direct Code Intelligence

When you need to see the actual implementation—not metadata about it—Maguyva’s MCP tools provide direct access.

From within an agent session:

mcp__maguyva__intelligent_search
  query: "agent context loading"

This auto-routes across semantic, text, and AST search to find relevant code. For specific symbols:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

For dependency analysis:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

These aren’t just grep replacements. They’re graph-aware, semantically indexed, and integrated with the same code intelligence that powers the agents themselves.

Unified Search Across Registries

Sometimes you don’t know which registry holds the answer. The unified search spans everything:

$ orkestra search "database" --summary

on
{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 matches across five registries. The summary tells you where to drill down. Remove --summary for detailed results, or add --limit 5 to keep output manageable.

Why This Matters

Progressive disclosure isn’t just about convenience. It changes how you interact with complex systems.

Debugging becomes tractable. When an agent makes an unexpected decision, you don’t grep through logs. You check which tools it has access to (agents info), what decisions shape its behavior (decisions search), and trace the implementation if needed (intelligent_search).

Onboarding accelerates. New team members don’t need to read the entire codebase. They start with system status, explore with agents list, and go deeper only when they hit something they don’t understand.

Documentation stays current. Because the CLI reads from the same registries that configure the agents, the output is always accurate. There’s no drift between what the docs say and what the system does.

The CLI as Interface

We could have built a web dashboard. We could have written extensive documentation. Instead, we built a CLI that reads from the source of truth.

The CLI has advantages:

• Composable: Pipe output through jq, integrate with scripts
• Scriptable: Automate checks, generate reports
• Fast: No page loads, no authentication flows
• Accurate: Reads the actual configuration, not a cached representation

For systems where correctness matters more than aesthetics, CLI wins.

Building Your Own Progressive Disclosure

If you’re building agent systems, consider how users will inspect them:

1. Start with health checks. One command that tells you if things are working.
2. Provide inventory views. List what exists before explaining what it does.
3. Enable targeted queries. Search beats browsing at scale.
4. Expose provenance. Let users trace decisions to their origins.
5. Connect to code intelligence. Eventually, users need to see the implementation.

Each layer answers a follow-up question. Build them in order of frequency—most users stop at layer 2 or 3. Only power users reach layer 5.

The goal isn’t to expose everything. It’s to expose exactly what’s needed, exactly when it’s needed. That’s progressive disclosure applied to agent architecture.