ZeroTurn

ZeroTurn is a deterministic fast-path layer for local agents. It makes obvious local actions feel instant by routing explicit, parameter-complete user requests directly to local tools instead of spending a full model turn deciding whether a known capability exists.

In the latest sanitized local benchmark proof run, ZeroTurn deterministic dispatch handled the covered fast-path cases with a 29.641 ms median latency versus 3,789.852 ms for a Codex model-turn classification baseline: a 127.86x median speedup for explicit browser-open, file-create, and no-match requests.

Path	Median latency	p95 latency
ZeroTurn parse	0.012 ms	0.063 ms
ZeroTurn deterministic dispatch dry-run	29.641 ms	31.803 ms
ZeroTurn CLI dry-run	64.043 ms	65.476 ms
Codex model-turn classification	3,789.852 ms	3,935.602 ms

See docs/BENCHMARK_RESULTS.md for the measurement contract, summarized results, and scope.

Copyright (c) 2026 ZeroTurn contributors. Released under the MIT License.

The first standalone package includes:

• short-lived capability inspection caching
• direct browser URL open dispatch
• direct text file creation dispatch
• success handling for router responses such as status=opened
• focused parser, command wiring, cache, and confirmation tests
• the cross-platform app-control-router tool used for the side effects

Why It Exists

Local agent bridges are slow and fragile when every simple command goes through a general model loop. If the intent is explicit and all required parameters are present, the bridge can safely own recognition and side effects:

open https://example.com in Safari -> browser.open
create file report.md with body hello -> file.create

The model remains available for interpretation, missing parameters, and complex work. ZeroTurn takes the obvious actions off the model path.

Install For Development

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

CLI

Parse a request without running side effects:

zeroturn parse "open https://example.com in Safari"
zeroturn parse "create file report.md with body hello" --cwd /tmp/workspace --chat-id 42

Dispatch through the bundled router:

zeroturn dispatch "open https://example.com in Safari" --dry-run
zeroturn dispatch "create file report.md with body hello" --cwd /tmp/workspace

Show the bundled router catalog:

zeroturn capabilities

Library Use

from zeroturn import Profile, ZeroTurnBridge

bridge = ZeroTurnBridge(Profile(cwd="/tmp/workspace"), chat_id=42)
request = bridge.parse("create file report.md with body hello")

if request is not None:
    payload = bridge.dispatch(request, dry_run=True)

Run Before Codex

ZeroTurn becomes automatic when your bridge calls it before the model:

if zeroturn parse "$USER_TEXT" --cwd "$PWD" >/tmp/zeroturn.json; then
  zeroturn dispatch "$USER_TEXT" --cwd "$PWD" --reply
else
  codex "$USER_TEXT"
fi

See docs/CODEX_AUTOMATION.md for the Python integration pattern.

MCP Server

ZeroTurn can also run as a local stdio MCP server for Codex:

[mcp_servers.zeroturn]
command = "python3"
args = ["-m", "zeroturn.mcp_server"]
cwd = "/absolute/path/to/Zeroturn"

Installed packages can use command = "zeroturn-mcp" instead. See docs/MCP_SERVER.md for the exposed tools and configuration details.

Benchmark

Run the local fast-path benchmark:

zeroturn benchmark --iterations 100 --cli-iterations 20

Add a real Codex model-turn baseline when Codex CLI is authenticated:

zeroturn benchmark --include-codex --codex-iterations 3 --output benchmarks/results/local-codex.json

See docs/BENCHMARKS.md for the measurement contract and docs/BENCHMARK_RESULTS.md for the latest local proof run.

Current Fast Paths

User request	Direct action	Notes
open https://example.com in Safari	browser.open	Optional browser app selection.
create file report.md with body hello	file.create	Text-file extensions only; relative paths stay under allowed roots.
/capabilities, /skills, /apps style inspection	cache wrapper	force_refresh=True bypasses the TTL cache.

Roadmap

The next simple additions are intentionally narrow:

1. Direct screenshot.capture for "take a screenshot" / "send screenshot".
2. Direct "send latest artifact" and "send " relay without a model turn.
3. Read-only contacts.lookup.
4. Explicit calendar.create_event with required title/date/time.
5. Allowlisted mcp.call with schema validation.

Validation

python -m unittest discover -s tests
python tools/app-control-router/tests/test_smoke.py
python -m zeroturn.app_control_router.tests.test_smoke
zeroturn parse "open https://example.com in Safari"
zeroturn dispatch "create file report.md with body hello" --cwd /tmp --chat-id 42 --dry-run