Skip to main content

What Is X4?

X4 is an engineering orchestration framework for work that spans repositories, machines, agents, and GitHub. It is designed around one principle: humans and agents should use the same commands and evidence paths instead of inventing separate automation for each tool.

Core Capabilities​

X4 provides:

  • Multi-repo workspaces: bootstrapped repo sets with shared branch naming, status, validation, commit, PR, and cleanup flows.
  • Sandbox and preview workflows: private tailnet-only preview links and backend evidence without leaking localhost or container-only URLs.
  • Remote validation: control/testbox scheduling for deterministic test jobs, logs, artifacts, leases, and cleanup.
  • GitHub automation: issue creation, PR comments, check runs, /x4 command polling, and evidence publishing.
  • Agent adapters: Codex skills and IDE adapters that direct agents to call the X4 CLI rather than reimplementing X4 logic.
  • Mastra orchestration: a GitHub bot that plans issues, implements approved work, runs deterministic tests, triages failures with Codex, and opens draft PRs.

Current Proof Status​

The current X4 POC is past the "does the idea work?" stage for the first vertical slice:

  • local onboarding, complex multi-repo workspace proof, and editor adapter proof are executable from this repo;
  • single-control and single-worker remote validation has been proven for the pilot repo set;
  • PR/issue evidence comments, GitHub check runs, linked issues, and tailnet-only preview evidence have been proven in live smokes;
  • X4's safety checks cover no secret printing, no production-like env copying, no localhost tester links, dry-run planning, and cleanup previews.

The remaining work is hardening and scale-out. Real multi-worker scheduling with a second physical testbox is not yet proven, and preview delivery still needs an X4-owned gateway/router so tester URLs do not depend on app repos knowing X4-specific hostnames.

What X4 Does Not Own​

X4 does not replace Git, package managers, CI, product runtime ownership, cloud secret stores, or human review. It coordinates those systems through registry policy, workspace state, deterministic commands, remote execution records, and machine-generated evidence.

Why X4 Exists​

Without X4, multi-repo work tends to fragment:

  • each agent creates worktrees differently;
  • each repo has different validation and preview habits;
  • PR evidence is manually written and hard to trust;
  • remote test infrastructure lacks a consistent state model;
  • issue-to-PR automation has no shared guardrails.

X4 centralizes those concerns into repo policy, registry files, control-plane state, and CLI/Mastra workflows.

High-Level Lifecycle​

Relationship To Mastra Code Assist​

The Mastra orchestrator is the GitHub-facing automation layer. It uses Codex for agentic reasoning, but keeps deterministic execution in services that X4 can audit. Mastra owns event routing and state transitions; X4 owns workspace, remote execution, and evidence primitives.

For details, read Mastra overview.