Ambu (agentctl) is a small CLI for bounded, check-driven repair with OpenCode. It runs a user-supplied verification command, limits repair attempts, stops on repeated failures, and records each run. It is not a replacement for OMO/Slim orchestration, an operating-system sandbox, or a general-purpose acceptance judge.
Running autonomous coding agents in a repository often hits two key walls:
- Blind runaway loops: Agents hitting an environment bug or impossible constraint retry repeatedly, producing identical errors and burning quota.
- Missing verification boundaries: Agents report that a task is "done" without executing the project's test suite or verification commands.
Ambu wraps opencode run with bounded oversight: it dispatches tasks, validates every modification against your provided test command, enforces preflight policy gates, and stops when errors repeat.
When code changes fail to resolve an issue, Ambu hashes the normalized test failure output. If the identical blocker recurs, it halts early instead of burning rounds:
$ agentctl iterate coder "Fix auth token expiration" \
--check "pytest tests/test_auth.py" \
--max-rounds 5 \
--max-same-failure 2[Round 0] Evaluating initial check: pytest tests/test_auth.py
FAIL: test_token_expiration (AssertionError: 401 != 200)
Fingerprint: sha256:7f4a3b8c (gap: execution)
[Round 1] Dispatching OpenCode agent (fixer · grok-4.7-build-fast)...
Workspace modified. Running verification check...
FAIL: test_token_expiration (AssertionError: 401 != 200)
Fingerprint: sha256:7f4a3b8c (seen 2x)
[HALT] [ANTI-LOOP HALT] Identical blocker sha256:7f4a3b8c recurred 2 times.
Status: BLOCKED (exit code 3) — Prevented 4 runaway rounds. Quota saved.
Ambu uses word-boundary intent classification to route prompts to the right specialist station:
| Prompt Intent | Specialist Station | Autonomy | Responsibility |
|---|---|---|---|
| "Review database migrations for lock risks" | oracle |
read_only |
Architectural audit & diagnosis |
| "Fix the broken auth login logic" | fixer |
workspace_write |
Fast bug repair & patch |
| "Implement Stripe webhook billing endpoint" | coder |
workspace_write |
Feature implementation |
| "Make navbar responsive with CSS layout" | designer |
read_only |
UI/UX design & styling |
| "Find documentation for Upstash Redis" | librarian |
read_only |
Docs & reference research |
- Negation Safety: "Do not fix this, just review why it broke" detects negation and suppresses write permissions.
- Fail-Safe Fallback: Any ambiguity or tied score strictly defaults to safe
read_only(oracle).
- Output Normalization: Strips wall-clock timings (
in 0.42s), ISO timestamps, memory addresses (0x7f...), PIDs, and temp directories while preserving exact test failure line numbers. - Gap Diagnosis: Categorizes failures into
execution(code bugs),environment(missing dependencies),check_rubric(invalid test command), andtransient(rate limits). - Artifact Verification (
--eval-artifact): Verifies required output files exist and are non-empty before marking a task complete.
High-risk actions (git_push, deploy, secrets, global_config, destructive_delete) are blocked unless explicitly passed with --approve <capability>.
- oh-my-opencode-slim (OMO): Ambu's
slim_bridgeautomatically inspects~/.config/opencode/oh-my-opencode-slim.json, inheriting model assignments, reasoning variants (xhigh,max), and skill bindings with zero manual setup. - Agent Memory Bridge (AMB): Connects Ambu to durable memory. Pre-queries project gotchas before tasks, and shares discovered fixes across stations so no agent repeats a past mistake.
- Michelin Kitchen Brigade Guide: Detailed breakdown of the Head Chef, Expeditor Pass, and station roles.
- AMB Memory Integration Guide: Deep guide on auto-recall mechanics and shared incident logs.
git clone https://github.com/zzhang82/ambu-runtime-agents.git
cd ambu-runtime-agents
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
agentctl doctor# Natural language dispatch (auto-routes to oracle in read-only mode)
agentctl do "Review database schema for missing foreign key indexes"
# Code repair with automated test verification
agentctl do "Fix the broken user registration endpoint" --check "pytest tests/test_user.py"
# Bounded iteration with anti-loop protection (exit code 3 if repeated failure)
agentctl iterate coder "Fix billing calculation" --check "pytest" --max-same-failure 2
# Inspect guardrails and routing without running
agentctl do "Push commit to production remote" --dry-run --jsonLooking for a hands-free OpenCode / Codex skill with automated milestone streaming and token spend telemetry? Check out ambu-skill.
Run all 288 tests:
python3 -m unittest discover -s testsReleased under the MIT License. Copyright © 2026 Frank Zhang.