🔁 simplicio-loop
simplicio-loop ships three deterministic operators that any agent harness can call as plain tools: simplicio-mapper surveys a repo, simplicio-dev-cli applies an edit plan exactly, and impact-based test selection (scripts/impact_tests.py) runs only the tests a change can reach. The loop that turns GitHub issues into tested PRs is one consumer of them.
The operators
Looping an agent is no longer the hard part: agent SDKs and frameworks now ship it. The part that must not be probabilistic is reading the repo, writing the edit and choosing the tests. These three tools do that work, none of them provisions a model, and each prints machine-readable output. Your agent (Claude Code, Codex, Cursor, a LangGraph graph, a shell script) decides; they execute.
| Operator | What it does | Call it from any harness |
|---|
simplicio-mapper (survey) | Walks the repo locally, without an LLM, and returns a bounded context pack for a goal instead of the whole tree. Docs | simplicio-mapper handoff . --goal "trace the authentication flow" --token-budget 1200 --json |
simplicio-dev-cli (deterministic apply) | Applies a find/replace edit plan where each find must match exactly once, runs a scoped verification and prints one JSON receipt. It never provisions an LLM, per its README. Docs | simplicio-dev-cli edit --root . --plan plan.json --apply --check "<tests>" --json |
| Impact-based test selection | scripts/impact_tests.py diffs the working tree against a base ref at symbol level and selects the test files that reach a changed function, class or assignment. scripts/check.py uses it, so a change runs only the tests it can affect. Docs | python3 scripts/impact_tests.py --base origin/main --json |
pip install simplicio-loop puts simplicio-mapper and simplicio-dev-cli on your PATH (one wheel, Python 3.11+). scripts/impact_tests.py is a standard-library script with no install step: run it from a checkout or copy it into your repo.
This README quotes no savings figure. Measurements live in bench/llm_ab, where the raw per-run results are in bench/llm_ab/results/ (small A/B, a single model), and anything not measured there is not claimed.
The loop is one consumer of them
The loop is the reference consumer: it takes a GitHub issue, has the mapper survey the repo, lets a planner in a sandbox write a JSON plan, hands that plan to simplicio-dev-cli, then runs the tests (in this repo, scripts/check.py runs the impact-selected subset) before it opens a PR. Swap the loop for any other harness and the operators work the same.
flowchart LR
I["GitHub issue"] --> M["simplicio-mapper<br/>maps files, symbols, tests"]
M -->|"map slice"| P["Planner in a sandbox<br/>claude / codex / grok / gemini<br/>plans, never writes"]
P -->|"JSON plan"| D["simplicio-dev-cli<br/>deterministic apply"]
D --> T["tests verify<br/>simplicio-loop turbo --apply - --verify"]
T -->|"green"| S["secret scan"] --> PR["PR with evidence"]
T -.->|"2 failures"| E["escalate the model role"] -.-> P
Install
Needs Python 3.11+, git, and an authenticated gh for GitHub issues.
pip install simplicio-loop
simplicio-loop install # skills + hooks in this project (--global: user-wide, --host <name>: another host)
simplicio-loop login # sign in; shares the login with simplicio-runtime
simplicio-loop doctor # check the installed stack
Use it
In Claude Code or VS Code:
/simplicio-loop finish all the open issues
flowchart LR
A["1. You write /simplicio-loop and the goal"] --> B["2. Mapper maps, planner plans, dev-cli applies, tests verify"]
B --> C["3. PR with evidence"]
As a 24/7 watcher (a service that watches simpletibr/simplicio-* repos and opens PRs):
simplicio-loop watch247 --once --dry-run # one simulated tick, changes nothing
simplicio-loop watch247 login-check # are the exec CLIs logged in?
# from a repo checkout, as root, after creating the non-root user simplicio-loop:
sudo cp packaging/systemd/simplicio-loop-247.service /etc/systemd/system/
sudo cp packaging/systemd/simplicio-loop-247.env.example /etc/simplicio-loop-247.env # edit it, then chmod 600
sudo systemctl enable --now simplicio-loop-247
flowchart LR
R["repo opts in<br/>.simplicio-loop/loop.toml<br/>enabled = true"] --> L["issue opts in<br/>label loop:auto<br/>owner / member / collaborator"]
L --> W["worker loop"] --> PR["PR opened"]
PR -.->|"auto-merge off by default"| H["squad / human merges"]
Details: docs/WATCHER_247.md.
Live Dashboard (Simplicio Live):
simplicio-loop dashboard # start or reuse dashboard on 127.0.0.1:8765
simplicio-loop dashboard --status # check dashboard status
simplicio-loop dashboard --stop # stop the dashboard
Remote access routes:
- Local / SSH tunnel (recommended):
ssh -L 8765:127.0.0.1:8765 user@remote then open http://127.0.0.1:8765/?t=<token>.
- Tailscale: Connect via Tailscale MagicDNS (
http://<node>.ts.net:8765/?t=<token> or HTTPS https://<node>.ts.net/?t=<token>) with a valid access token.
- Custom host: Allow specific Host headers with
--allow-host <hostname> (e.g. simplicio-loop dashboard --allow-host mybox.internal).
How it works
flowchart LR
H["Haiku<br/>mechanical, 1 module"] -->|"2 failures"| S["Sonnet<br/>integration, security"] -->|"2 failures"| O["Opus / Fable<br/>replan only, never executes"]
flowchart LR
A["PR A ✓"] & B["PR B ✓"] & C["PR C ✓"] & D["PR D ✓"] --> G{"test the batch once"}
G -->|"green"| M["merge all into main"]
G -->|"red"| X["bisect"] --> BAD["PR C out, back to its squad"]
X --> OK["A, B and D merge"]
flowchart TD
G["General coordinator<br/>Opus / Fable: plans, never executes"] --> S1["Squad 1<br/>Sonnet coordinator"] & S2["Squad 2<br/>Sonnet coordinator"] & S3["Squad 3<br/>Sonnet coordinator"]
S1 --> W1["up to 4 Haiku workers"]
S2 --> W2["up to 4 Haiku workers"]
S3 --> W3["up to 4 Haiku workers"]
S1 & S2 & S3 -.->|"APPROVED BY SQUAD"| MC["Merge coordinator<br/>Sonnet: merges in series"] --> MAIN["main"]
The 50 extension points
pie showData title Extension points in the 24/7 path (of 50)
"Wired" : 19
"Partial" : 29
"Absent" : 2
docs/EXTENSION_POINTS_SERVICE.md · #1509
Runtimes
- 6 wired adapters ship code in
adapters/ and a host test: Claude Code, Codex, Cursor, Grok, Kiro and VS Code.
- 29 listed hosts are catalog entries with a README and no adapter code; 28 of them also have a generic installer target that writes the skills and the host's entry file. A listing is not proof that the host runs the loop.
- The operators above are plain commands, so they work from any harness, wired or not. Per-host status: adapters/MATRIX.md and simplicio_loop/_catalog/harnesses.json.
Learn more
