Architecture
X4 is organized around a few stable boundaries.
Main Components
| Component | Location | Responsibility |
|---|---|---|
| X4 CLI | src/cli.ts | Workspace, registry, sandbox, remote, control, GitHub, issue, PR, and orchestration commands. |
| Registry | registry/*.yaml | Repo sets, sandbox profiles, env bundles, and validation commands. |
| Execution model | infra/execution/x4-execution-model.yaml | Control nodes, workers, SSH users, worker classes, and state roots. |
| Codex plugin | plugins/x4-codex/ | Codex skills that route agents through the X4 CLI. |
| VS Code adapter | extensions/vscode-x4/ | IDE commands for X4 workspace and validation flows. |
| Mastra orchestrator | apps/mastra-orchestrator/ | GitHub bot workflows for planning, implementation, PR follow-up, testing, and triage. |
| Scripts | scripts/ | Install, update, bootstrap, and smoke helpers for devboxes/control/workers. |
Runtime Topology
Mastra Orchestrator Topology
Boundary Rules
- The CLI owns deterministic workspace operations.
- Mastra owns GitHub event orchestration and bot state.
- Codex owns agentic inspection and edits when explicitly invoked by Mastra or a human/agent workflow.
- Remote workers own execution artifacts, not policy decisions.
- GitHub comments and checks should be generated from structured X4 evidence.