Architecture Deep-Dive

System Overview

The Cursor Agent Triad system is a multi-agent architecture that combines Claude Code’s reasoning capabilities with Cursor CLI’s code generation. It uses a three-legged execution pattern for maximum quality and cost efficiency.

Core Components

1. CLI Layer (`bin/`)

bin/
├── cursor-agent          # Main CLI wrapper with model policy enforcement
├── cursor-agent-status   # Discovery and health verification
├── subagent-router       # Keyword-based auto-routing
└── cursor-dispatch.sh    # Tier-to-model mapper for swarm agents

cursor-agent is the heart of the system. It:

Reads configuration from etc/cursor_config.json
Enforces model policies (allowed models, composer-only mode)
Resolves the native Cursor CLI binary
Applies profiles for different task types
Manages timeouts and structured output

subagent-router classifies tasks by keyword analysis:

Cursor keywords: fix, edit, rename, implement, test, lint
Claude keywords: design, architect, plan, reason, analyze
High-tier keywords: security, audit, optimize, critical

2. Agent Layer (`agents/`)

agents/
├── claude/              # Strategy agents (Opus/Sonnet)
│   ├── api-designer.md
│   ├── test-engineer.md
│   └── sequence-analyst.md
├── cursor/              # Bridge agents (Haiku dispatchers)
│   ├── api-designer-cursor.md
│   ├── test-engineer-cursor.md
│   ├── sequence-analyst-cursor.md
│   ├── CURSOR_CLI_ENFORCEMENT.md
│   └── swarm/           # Tier agents
│       ├── swarm-router.md
│       ├── codex-standard.md
│       └── codex-high.md
├── multi-agent-orchestrator.md
└── documentation-keeper.md

3. Configuration Layer (`etc/`)

etc/
├── cursor_config.json      # Model policy, allowed models, enable/disable
└── agent_pool_config.json  # Pool sizing, budget allocation, routing rules

Data Flow

Triad Execution

User Task
    |
    v
[Claude Strategy Agent]  (Opus/Sonnet)
  - Analyzes requirements
  - Designs approach
  - Chooses parameters
    |
    v
[Cursor Bridge Agent]  (Haiku)
  - Receives strategy
  - Synthesizes CLI prompts
  - Dispatches via Bash
    |
    +---> [cursor-agent --model codex-standard]  Step 1: Generate
    |         |
    |         v
    +---> [cursor-agent --model composer-1.5]    Step 2: Review
              |
              v
[QC-Validated Output]
    |
    v
[Claude Strategy Agent]
  - Receives results
  - Interprets output
  - Delivers to user

Swarm Routing

Task Prompt
    |
    v
[subagent-router]
  - Keyword classification
  - Tier selection
    |
    +---> [cursor-dispatch.sh codex-standard]  General tasks
    |
    +---> [cursor-dispatch.sh codex-high]      Security/complex
    |
    +---> [cursor-agent --model composer-1.5]  Simple edits

Model Hierarchy

                    Cost / Quality
                         ^
                         |
              +----------+----------+
              |    codex-high       |  Security, algorithms
              |    (5% budget)      |
              +----------+----------+
                         |
              +----------+----------+
              |  codex-standard     |  General implementation
              |    (15% budget)     |
              +----------+----------+
                         |
              +----------+----------+
              |   composer-1.5      |  Quick edits, iteration
              |    (80% budget)     |  <-- DEFAULT
              +----------+----------+

Configuration Reference

cursor_config.json

Field	Type	Description
`enabled`	boolean	Master enable/disable switch
`model_override`	string	Force all requests to this model
`default_model`	string	Model when none specified
`allowed_models`	string[]	Whitelist of permitted models
`composer_only`	boolean	Force everything to composer-1.5
`credit_target_monthly`	number	Budget target in credits

agent_pool_config.json

Section	Description
`budget.allocation`	Per-tier credit allocation percentages
`routing.keyword_overrides`	Keywords that trigger specific tiers
`triads`	Triad definitions with agent paths and keywords
`swarm_tiers`	Tier definitions with model mappings