Splay

Splay runs bounded coding tasks through an eligible local coding agent, isolates its changes, verifies the result, and retains the evidence.

Install and connect

Install Codex and sign in with an eligible personal subscription, then:

pip install splay-router
splay setup --qualify

For this checkout, use uv sync followed by uv run splay setup --qualify.

Setup registers the MCP service in Codex, installs the Splay skill and activation instructions, and checks the connection. --qualify authorizes one small, bounded subscription task with an independent verifier. Setup reports ready only when the installed worker has a verified qualification. Changed account, installation, version, or model bindings require qualification again. Credentials stay with Codex.

Upgrade an installed copy in place:

splay update

The command updates splay-router in the Python environment that owns the running splay command. It supports normal pip installs, pipx environments with pip, uv tool installs, and other uv-managed environments. For uv tools, it retains the owning tool and executable directories and replaces an old version pin; for other uv environments, it targets the exact running interpreter. Editable installs and source checkouts are refused so a development tree is never replaced unexpectedly. Updating leaves Splay configuration, task history, workspaces, and Codex integration files in place. Installer errors are shown and their nonzero status is returned. Restart active Codex sessions after an update.

Restart existing Codex sessions after setup. Ordinary bounded implementation, fix, and review requests should use Splay automatically. You can also choose Splay through /skills, or type $splay. You do not need to remember MCP tool names. Activation is mediated by the host; it is not a guarantee that every model response invokes Splay. The supported integration is Codex, not every agent host.

The installer enables automatic calls only for the six bounded task tools: delegate, review, status, explain, cancel, and apply. Other tools retain prompt approval. No tool can enable paid fallback, raise server ceilings, or bootstrap qualification. Normal implementation requests authorize the host to apply a verified result through the apply tool, which checks the original repository and exact candidate; reviews never promote.

Use from the terminal

From a clean Git repository:

splay run "Fix the failing parser test" --repo . --verify "python -m pytest tests/test_parser.py"
splay explain task-...
splay apply task-...

Use your project's actual verification command. Worker completion alone is not success. A passing candidate stays in its worktree until applied; promotion checks the exact verified tree and refuses a changed or dirty canonical repository. It never runs blanket git reset --hard or git clean.

splay status
splay profiles
splay doctor
splay policy
splay configure --help
splay update
splay task cancel task-...
splay uninstall --yes

Uninstall disconnects the owned host integration and preserves history. --purge is a separate operation that refuses active work, active workspaces, a running daemon, or unowned files. Modified user configuration is preserved. --home and --state-dir support isolated setup testing.

Supported execution and current limits

The supported live path is Codex SINGLE execution with an included personal subscription, fresh account/rate-limit checks, bounded resources, isolated worktrees, independent verification, durable results, cancellation, and explicit safe promotion. Unknown or paid channels block by default. MCP starts a local daemon on demand; work survives the submitting MCP client's exit. Restart blocks interrupted work for review and terminates workers whose saved process identity still matches.

This is not full implementation of every requirement in the draft specification. Remaining gaps include a second qualified live worker family, quality-calibrated multi-model routing, automatic bounded escalation/handoff, project-specific policy overlays, and the draft's newer MCP Tasks extension. ACP and parallel strategy experiments remain diagnostics/research. Hard no-network verification requests block when no qualified isolation backend can enforce them. Portable verification commands run locally with a filtered environment; they are not an OS sandbox for hostile repositories.

MCP uses supported revision negotiation and durable Splay task handles rather than claiming Tasks-extension certification. Synthetic evaluations and one small live qualification do not establish general coding quality or optimal routing. See the original audit and remediation evidence. Historical phase documents describe component milestones and are not current product certification.

Development and acceptance

Build release artifacts with make build, publish them using UV_PUBLISH_TOKEN from .env with make publish, or do both with make release. See build and publish instructions.

uv sync
uv run pytest
uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run mypy

An opt-in live acceptance test creates a disposable repository, delegates through MCP, verifies, promotes, restarts the daemon, and checks durable results:

uv run python scripts/live_acceptance.py --live --state-dir /path/to/qualified/state
uv run python scripts/host_acceptance.py --live --state-dir /path/to/qualified/state

Research commands are explicitly diagnostic: splay route plan --diagnostic --prompt "...", splay profile probe (stub by default), and splay eval routing. They do not qualify production routing.

Apache-2.0 — see LICENSE.