🔁 simplicio-loop

🇬🇧 English | 🇧🇷 Português | 🇪🇸 Español | 🇫🇷 Français | 🇩🇪 Deutsch | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇨🇳 简体中文 | 🇷🇺 Русский | 🇵🇱 Polski | 🇹🇷 Türkçe | 🇳🇱 Nederlands | 🇮🇳 हिन्दी | 🇸🇦 العربية

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

Loading

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"]

Loading

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"]

Loading

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"]

Loading

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"]

Loading

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"]

Loading

The 50 extension points

pie showData title Extension points in the 24/7 path (of 50)
  "Wired" : 19
  "Partial" : 29
  "Absent" : 2

Loading

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

• INSTALL.md · docs/CLI_COMMANDS.md · docs/WATCHER_247.md
• docs/MODEL_ROLES.md · docs/DASHBOARD.md · CHANGELOG.md
• Everything else: docs/GUIDE.md (skills, runtimes, the loop, token economy, safety, tests)