{"id":51140644,"url":"https://github.com/wesleysimplicio/simplicio-loop","last_synced_at":"2026-06-25T22:30:22.940Z","repository":{"id":366706915,"uuid":"1273614552","full_name":"wesleysimplicio/simplicio-loop","owner":"wesleysimplicio","description":"🔁 Finishes your entire backlog while you sleep. The AI orchestrator that DOES the work end-to-end on ANY LLM — discover → implement → verify → merge → 24/7 — behind safety gates, at up to 96% fewer tokens. 43 extension points. Not a chatbot. A worker.","archived":false,"fork":false,"pushed_at":"2026-06-23T06:50:36.000Z","size":2536,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T08:26:01.820Z","etag":null,"topics":["agentic-ai","ai","ai-agent","anthropic","automation","autonomous-agents","claude-code","codex","devtools","gemini","llm","mcp","orchestrator","skill","token-optimization"],"latest_commit_sha":null,"homepage":"https://simpleti.com.br/simplicio","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wesleysimplicio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-18T17:40:17.000Z","updated_at":"2026-06-23T06:50:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wesleysimplicio/simplicio-loop","commit_stats":null,"previous_names":["wesleysimplicio/simplicio-tasks","wesleysimplicio/simplicio-loop"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/wesleysimplicio/simplicio-loop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesleysimplicio%2Fsimplicio-loop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesleysimplicio%2Fsimplicio-loop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesleysimplicio%2Fsimplicio-loop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesleysimplicio%2Fsimplicio-loop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wesleysimplicio","download_url":"https://codeload.github.com/wesleysimplicio/simplicio-loop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesleysimplicio%2Fsimplicio-loop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34795436,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai","ai-agent","anthropic","automation","autonomous-agents","claude-code","codex","devtools","gemini","llm","mcp","orchestrator","skill","token-optimization"],"created_at":"2026-06-25T22:30:21.892Z","updated_at":"2026-06-25T22:30:22.927Z","avatar_url":"https://github.com/wesleysimplicio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔁 simplicio-tasks — The Universal Looping AI Orchestrator\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/simplicio-loop-hero.jpg\" alt=\"simplicio-loop\" width=\"920\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/wesleysimplicio/simplicio-loop/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/wesleysimplicio/simplicio-loop?style=social\" alt=\"Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"#-the-11-skills--accelerators\"\u003e\u003cimg src=\"https://img.shields.io/badge/skills-11-7C3AED\" alt=\"11 skills\"\u003e\u003c/a\u003e\n  \u003ca href=\"#-source-adapters\"\u003e\u003cimg src=\"https://img.shields.io/badge/source%20adapters-5-00E08A\" alt=\"5 source adapters\"\u003e\u003c/a\u003e\n  \u003ca href=\"#-11-runtimes-one-protocol\"\u003e\u003cimg src=\"https://img.shields.io/badge/runtimes-11-2563EB\" alt=\"11 runtimes\"\u003e\u003c/a\u003e\n  \u003ca href=\"#-the-48-extension-points\"\u003e\u003cimg src=\"https://img.shields.io/badge/extension%20points-48-00E08A\" alt=\"48 extension points\"\u003e\u003c/a\u003e\n  \u003ca href=\"#-token-economy\"\u003e\u003cimg src=\"https://img.shields.io/badge/tokens-up%20to%2096%25%20fewer-green\" alt=\"Up to 96% fewer tokens\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/wM6tr7xVb\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-Join%20Simplicio-5865F2?logo=discord\u0026logoColor=white\" alt=\"Join the Simplicio Discord\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-tldr\"\u003eTL;DR\u003c/a\u003e ·\n  \u003ca href=\"#-the-11-skills--accelerators\"\u003e11 Skills\u003c/a\u003e ·\n  \u003ca href=\"#-source-adapters\"\u003eSource Adapters\u003c/a\u003e ·\n  \u003ca href=\"#-11-runtimes-one-protocol\"\u003e11 Runtimes\u003c/a\u003e ·\n  \u003ca href=\"#-the-loop\"\u003eThe Loop\u003c/a\u003e ·\n  \u003ca href=\"#-token-economy\"\u003eToken Economy\u003c/a\u003e ·\n  \u003ca href=\"#-token-economy\"\u003eCapture Engine\u003c/a\u003e ·\n  \u003ca href=\"#-install--use\"\u003eInstall\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e🌍 Languages:\u003c/strong\u003e\u003cbr\u003e\n  \u003ca href=\"README.md\"\u003e🇬🇧 English\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.pt-BR.md\"\u003e🇧🇷 Português\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.es-ES.md\"\u003e🇪🇸 Español\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.fr-FR.md\"\u003e🇫🇷 Français\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.de-DE.md\"\u003e🇩🇪 Deutsch\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.it-IT.md\"\u003e🇮🇹 Italiano\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.ja-JP.md\"\u003e🇯🇵 日本語\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.ko-KR.md\"\u003e🇰🇷 한국어\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.zh-CN.md\"\u003e🇨🇳 简体中文\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.ru-RU.md\"\u003e🇷🇺 Русский\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.pl-PL.md\"\u003e🇵🇱 Polski\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.tr-TR.md\"\u003e🇹🇷 Türkçe\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.nl-NL.md\"\u003e🇳🇱 Nederlands\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.hi-IN.md\"\u003e🇮🇳 हिन्दी\u003c/a\u003e |\n  \u003ca href=\"READMEs/README.ar-SA.md\"\u003e🇸🇦 العربية\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## ⚡ TL;DR\n\n**simplicio-tasks** is a runtime-agnostic **super-plugin** — one autonomous looping\norchestrator (invoked as **`/simplicio-tasks`**) plus **five satellite skills** — that turns any\nstrong LLM (Claude, Codex, Copilot, Gemini, Cursor, local models) into a self-driving worker. You\npoint it at a body of work — *\"finish all the open issues\"*, *\"clear the CI queue\"*, *\"drain the Jira board\"* — and it\nruns the whole lifecycle on its own:\n\n\u003e **discover → understand → decide → act → verify → correct → record → repeat**\n\nIt discovers work from any source (GitHub Issues, Jira, Azure DevOps, agentsview sessions, and\nmore), dedups, auto-scales an agent fleet to your machine, implements each item through a quality\nloop that **runs the code (not just compiles it)**, opens PRs, resolves CI/review feedback, merges,\nand keeps watching **24/7** for new work — all behind safety gates and a hard cost kill-switch.\n\n```text\n/simplicio-tasks finish all open issues\n→ identity + pre-flight (kill-switch, auth, watcher)\n→ discover 50 issues · dedup · build dependency DAG\n→ autoscale fleet = 14 · pipeline implement→review→merge\n→ each item: read body+ACs → orient code → plan → edit → run → verify → PR\n→ merge · close with evidence · rollback if main breaks\n→ keep looping every ~2 min until the queue is dry (evidence-gated, never a false \"done\")\n```\n\nThree things make it different: it is a **super-plugin of focused skills**, it runs the **same\nprotocol on 11 runtimes**, and it does all of this with **aggressive, honest token economy**.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/simplicio-loop-infographic.png\" alt=\"simplicio-loop — the whole system at a glance: 6 core skills, 5 satellites, 5 accelerators, 48 extension points, 11 runtimes, up to 96% fewer tokens\" width=\"920\" /\u003e\n\u003c/p\u003e\n\n---\n\n## 📘 Official capability record (v3.10.2)\n\nThe complete, official roster of what `simplicio-tasks` ships — every capability below is **real,\nrunnable, and tested** (`python3 scripts/check.py`: claims-audit 4/4 + 28 tests). Each links to its\ndeep section and its worker.\n\n| Capability | What it does | Proof / worker | Details |\n|---|---|---|---|\n| 🎬 **Video evidence** (`video_evidence`) | Records the **real browser session** as moving proof a UI change works (Playwright, default); renders a **deterministic captioned MP4** with [hyperframes](https://github.com/heygen-com/hyperframes) for an explicit explainer request (`/simplicio-tasks make a video of screen X`) | `scripts/video_evidence.py` · BLOCKED (never fake-pass) without the toolchain | [§ Video evidence](#-video-evidence--playwright-by-default-hyperframes-on-request) |\n| 🧠 **Attempt memory + stall detector** | A durable run-journal (`.orchestrator/loop/journal.jsonl`) + a stall detector so the loop **changes strategy instead of oscillating**; incremental triage (`since`) reads only the delta each turn | `scripts/loop_journal.py` · `selftest` 9/9 | [§ Anti-oscillation](#-attempt-memory--stall-detector-anti-oscillation) |\n| 🧭 **Repo conventions** (`repo_conventions`) | **Learns the repo's own playbook** — mines git history + merged PRs + static config into `.orchestrator/conventions.json` so every new branch/commit/PR mirrors the team's established style; worktree-per-item isolation is the default | `scripts/repo_conventions.py` · `selftest` 19/19 | [§ The full flow](#️-the-full-flow--from-demand-to-delivery) |\n| 🔒 **Fail-closed safety gate** (`action_gate`) | A `PreToolUse`/git-pre-push hook that **mechanically blocks** force-push, history rewrite, mass-delete, destructive DDL, infra teardown, and secret-laden commits/pushes — Step 5 made executable, not prose | `hooks/action_gate.py` · `selftest` 15/15 | [§ Safety](#-safety-non-negotiable) |\n| 🔬 **Local verification** | A test suite (worker selftests + an **e2e of the loop driver** proving evidence-gated exit) + a **claims-audit** (referenced scripts exist · counts consistent · `_bundle ≡ source`) — all local, **no paid CI** | `scripts/check.py` · `scripts/claims_audit.py` · `tests/` | [§ Tests \u0026 local checks](#-tests--local-checks-no-paid-ci) |\n| ✅ **Honest savings** | The savings line is now **evidence-gated, not mandatory** — a number is shown only with a measured receipt (clamp/signatures/cache/`deterministic_edit`/ledger); never fabricated | token-economy contract | [§ Token economy](#-token-economy) |\n\nTwo loop **modes** make termination explicit: **converge** (a single hard task — ends on the\nevidence-gated `\u003cpromise\u003e` or a stall escalation) vs **drain** (a queue — ends when the source\nre-query stays empty K rounds). Both still obey the universal exits (promise+evidence,\n`max_iterations`, budget, STOP).\n\n\u003e Loop scoring across this line of work: **7.5** (strong design, unproven) → **9** (attempt memory +\n\u003e anti-oscillation) → **9.5** (reproducible local proof) → **~10** (enforced safety + complete loop\n\u003e semantics). The verification infra now catches the project's own regressions as it grows.\n\n---\n\n## 🧠 The 11 skills \u0026 accelerators\n\nThe orchestrator core + five satellites + five accelerators/integrations. Each satellite is\n**optional** — when loaded, the orchestrator delegates to it (richer + cheaper); when absent, the\ninline protocol covers 100%. Accelerators are **auto-detected** — present = used, absent = LLM\nfallback.\n\n| # | Capability | Absorbs | What it does | Token impact |\n|---|---|---|---|---|\n| 1 | 🔁 **simplicio-tasks** | — | The orchestrator loop: 48 extension points, dual-path router, self-audit convergence | Core |\n| 2 | ♾️ **simplicio-loop** | [ralph-loop](https://github.com/cursor/plugins/tree/main/ralph-loop) | Hardened Ralph loop: evidence-gated `\u003cpromise\u003e` exit, max_iterations cap | Loop drive |\n| 3 | 🧱 **simplicio-orient** | [rtk](https://github.com/rtk-ai/rtk) + [caveman](https://github.com/JuliusBrussee/caveman) | Terminal-first execution, output-reduction catalog, tee-cache, signatures-read | L0 deterministic |\n| 4 | 🔥 **simplicio-review** | [thermos](https://github.com/cursor/plugins/tree/main/thermos) | Parallel adversarial review on distinct rubrics → deduped verdict | Quality gate |\n| 5 | 🗜️ **simplicio-compress** | [caveman](https://github.com/JuliusBrussee/caveman) | Output + memory compression, fail-closed `transform_guard` | 40-60% fewer |\n| 6 | 🎓 **simplicio-learn** | [teaching](https://github.com/cursor/plugins/tree/main/teaching) | Post-run retrospective → durable, deduped lessons in memory | Smarter each run |\n| 7 | 🧭 **Understand Anything** | [Egonex-AI](https://github.com/Egonex-AI/Understand-Anything) | Knowledge graph orient: semantic search, guided tours, dependency graph | **L0 zero tokens** |\n| 8 | 📊 **agentsview** | [kenn-io](https://github.com/kenn-io/agentsview) | Session analytics, cost tracking, stalled-session discovery | **L1** SQL only |\n| 9 | ⚡ **LMCache** | [LMCache](https://github.com/LMCache/LMCache) | KV cache between loop turns — 40-70% TTFT reduction on local models | GPU time ↓ |\n| 10 | 🗜️ **Simplicio capture engine** | `engine/simplicio_engine.py` (native, stdlib-only; savings-schema compatible with the OSS [headroom](https://github.com/headroomlabs-ai/headroom) project) | Transparent capture proxy: forwards to the real provider, measures + deterministically compresses, writes `proxy_savings.json` | **deterministic** |\n| 11 | 🎬 **video_evidence** | Playwright (default) · [hyperframes](https://github.com/heygen-com/hyperframes) (on request) | Records the **real session** as moving proof of a UI change (Playwright); renders a **deterministic captioned MP4** explainer with hyperframes when the video IS the deliverable | Evidence producer |\n\nEach skill lives under [`.claude/skills/`](.claude/skills); each accelerator has a reference doc\nunder `.claude/skills/simplicio-tasks/references/` (the video producer:\n[`video-evidence.md`](.claude/skills/simplicio-tasks/references/video-evidence.md), worker\n[`scripts/video_evidence.py`](scripts/video_evidence.py)).\n\n---\n\n## 📡 Source adapters\n\nThe orchestrator discovers work from any source via pluggable adapters. Each exposes six verbs:\n`list_ready`, `get_details`, `claim`, `update_status`, `attach_evidence`, `close`.\n\n| Source | Adapter | Purpose |\n|---|---|---|\n| GitHub Issues/PRs | `gh` CLI (native) | Primary work-item source |\n| Jira / Asana / ClickUp / Linear / Notion | host connector | Board/project management |\n| Trello / Azure DevOps | `az boards` adapter | Azure work tracking |\n| **agentsview sessions** | `scripts/agentsview_adapter.py` | Stalled session recovery + cost observability |\n| Local files / CI queue | filesystem / CI API | Internal work tracking |\n\nSee each adapter's reference doc under `.claude/skills/simplicio-tasks/references/`.\n\n---\n\n## 🌐 11 runtimes, one protocol\n\nOne universal skill core + one set of hooks drives every runtime. An adapter is thin: it tells a\nruntime *where to load the skills*, *how to arm the loop*, and *how to bind native speed*. **The\nskill names no runtime; the runtime detects the skill.**\n\n| Runtime | Skill load | Loop drive | Native bind |\n|---|---|---|---|\n| **Claude Code** | `.claude/skills/` + plugin | `Stop` hook | MCP |\n| **Codex** | `AGENTS.md` | self-paced | MCP / adapter |\n| **VS Code (Copilot)** | `copilot-instructions.md` | tasks | MCP |\n| **Cursor** | `.cursor-plugin/` | `stop`+`afterAgentResponse` | MCP / rules |\n| **Antigravity** | rules / `AGENTS.md` | self-paced | MCP |\n| **Kiro** | `.kiro/steering/` | specs | MCP |\n| **OpenCode** | `AGENTS.md` | self-paced | MCP |\n| **Gemini** | `GEMINI.md` | self-paced | MCP / adapter |\n| **Aider** | `CONVENTIONS.md` | self-paced | — (LLM fallback) |\n| **Hermes** | native recall | native loop | **native** |\n| **OpenClaw** | plugin SDK | native scheduler | **native** |\n\nThe promise: **same protocol, same gates, same safety on all 11 — only the speed differs.**\n`orient_clamp.py` (token economy) works on every runtime with zero wiring. See\n[`adapters/MATRIX.md`](adapters/MATRIX.md).\n\n---\n\n## 🗺️ The full flow — from demand to delivery\n\nEvery layer the orchestrator acts on, in order — from reading the demand (issues, tasks, assigns)\nto delivering merged, evidenced work, then looping 24/7 for more.\n\n```mermaid\nflowchart TD\n  subgraph SRC[\"1 · Demand sources (any adapter)\"]\n    direction LR\n    S1[\"GitHub Issues / PRs / CI\"]\n    S2[\"Jira · Azure DevOps · Linear · ClickUp · Notion · agentsview · Understand Anything (orient)\"]\n    S3[\"Assigns · TODO/FIXME · CVE · local files · LMCache (inference accelerator)\"]\n  end\n  SRC --\u003e PF\n  subgraph PF[\"2 · Pre-flight gates\"]\n    direction LR\n    P1[\"cost kill-switch budget · agentsview cost check\"]\n    P2[\"source auth + scopes\"]\n    P3[\"arm 24/7 watcher\"]\n  end\n  PF --\u003e DISC\n  subgraph DISC[\"3 · Discover + normalize\"]\n    direction LR\n    D1[\"source_adapter: list metadata only\"]\n    D2[\"normalize to canonical schema\"]\n    D3[\"dedup id+title+fingerprint+branch/PR\"]\n    D4[\"dependency DAG\"]\n  end\n  DISC --\u003e INTK\n  subgraph INTK[\"4 · Deep intake (per item)\"]\n    direction LR\n    I1[\"body + ALL comments\"]\n    I2[\"extract acceptance criteria\"]\n    I3[\"orient code · signatures-only reads or Understand Anything knowledge graph\"]\n    I4[\"plan + AC checklist + complexity\"]\n  end\n  INTK --\u003e RT{\"5 · Route\"}\n  RT --\u003e|\"small and every item complexity at most 3\"| FAST[\"Fast-path: solo, one targeted test\"]\n  RT --\u003e|\"large queue or any medium+\"| POOL\n  subgraph POOL[\"6 · Continuous worker pool (autoscaled, conflict-aware)\"]\n    direction LR\n    W1[\"claim · branch · worktree if overlap\"]\n    W2[\"deterministic_edit\"]\n    W3[\"quality loop: edit-lint-test-fix\"]\n  end\n  FAST --\u003e QG\n  POOL --\u003e QG\n  subgraph QG[\"7 · Quality gates\"]\n    direction LR\n    Q1[\"AC gate = real DoD\"]\n    Q2[\"WORKS not just compiles · web_verify (Playwright) · video_evidence (Playwright recording · hyperframes on request)\"]\n    Q3[\"adversarial review · thermos rubrics\"]\n  end\n  QG --\u003e SG\n  subgraph SG[\"8 · Safety gates (non-negotiable)\"]\n    direction LR\n    G1[\"secret-scan\"]\n    G2[\"irreversible-op human gate\"]\n    G3[\"4-state verdict · attestation\"]\n  end\n  SG --\u003e DEL\n  subgraph DEL[\"9 · Deliver\"]\n    direction LR\n    L1[\"commit · push · Draft PR\"]\n    L2[\"close in-source + evidence\"]\n    L3[\"verify reality, not self-report\"]\n  end\n  DEL --\u003e FB\n  subgraph FB[\"10 · Feedback loop to merge-ready\"]\n    direction LR\n    F1[\"CI fail -\u003e fix root cause\"]\n    F2[\"review comments -\u003e adjust\"]\n    F3[\"branch behind main -\u003e additive rebase\"]\n  end\n  FB --\u003e|\"merged and closed\"| DONE([\"done + evidence + measured savings (only if a receipt exists)\"])\n  WATCH[\"11 · 24/7 watcher · simplicio-loop evidence-gated promise · max-iterations cap · cost kill-switch · LMCache KV cache warm\"]\n  FB -. \"poll new work / comments / checks\" .-\u003e WATCH\n  DONE -. \"idle until new work\" .-\u003e WATCH\n  WATCH -. \"re-feed the goal\" .-\u003e DISC\n```\n\n---\n\n## 🔁 The loop\n\nThe **Evidence-Gated Loop** is the core mechanism. It re-feeds the same goal each turn so the\nagent sees its own prior work. Exit is ONLY via:\n\n1. **Evidence-gated `\u003cpromise\u003e`** — the turn that emits the promise MUST also carry concrete\n   proof (passing test, merged PR, closed-item re-query). A promise with no evidence = ignored.\n2. **`max_iterations` cap** — hard safety backstop\n3. **Budget kill-switch** — `daily_usd_ceiling` halts the loop when spent\n4. **STOP signal** — `.orchestrator/STOP` or channel command\n\nBetween turns, LMCache (when available) caches the KV state so re-feed costs near-zero prefill.\n\n### 🧠 Attempt memory + stall detector (anti-oscillation)\n\nA re-feed loop that remembers nothing oscillates — try X, fail, try X again — until the cap burns.\nsimplicio-loop keeps a **durable run-journal** (`.orchestrator/loop/journal.jsonl`, append-only:\n`iteration · action · hypothesis · gate · error-fingerprint`) and a **stall detector**\n([`scripts/loop_journal.py`](scripts/loop_journal.py), deterministic + model-free):\n\n- **Error fingerprint** — the failing gate output is reduced to a stable hash with line numbers,\n  paths, hex/uuids, timestamps and durations normalized away, so the *same* bug is recognized\n  across turns even when the incidental text differs.\n- **Stall = K identical-fingerprint failures in a row** (default K=3). A changing fingerprint means\n  the loop is moving (PROGRESS); the same one K times means it is spinning (STALLED).\n- On STALLED the loop does **not** re-feed the same goal — it names the **dead-end actions** to\n  avoid, then **switches strategy** or **escalates to the human gate** with the fingerprint.\n- `loop_journal.py resume` is read at the top of every turn, so a fresh process continues without\n  re-deriving prior attempts (real resume) and never retries a known dead-end.\n\n```bash\nloop_journal.py resume                       # what was tried + dead-ends to avoid\nloop_journal.py record --iteration N --action \"…\" --gate fail --gate-output test.log\nloop_journal.py stall --k 3 --exit-code      # PROGRESS → re-feed · STALLED → switch/escalate\n```\n\n---\n\n## 🎬 Video evidence — Playwright by default, hyperframes on request\n\nThe loop produces **demo videos** as proof a change works — **two engines**, one `video_evidence`\nextension point (worker [`scripts/video_evidence.py`](scripts/video_evidence.py), contract\n[`references/video-evidence.md`](.claude/skills/simplicio-tasks/references/video-evidence.md)):\n\n1. **Default — the normal evidence flow uses Playwright.** After a UI change, `video_evidence`\n   records the **real browser session** driving the screen (Playwright native video → `.webm`, →\n   `.mp4` with FFmpeg) — the strongest \"works, not just compiles\" receipt (Step 4b) and a valid\n   evidence-gated `\u003cpromise\u003e`.\n\n   ```bash\n   python3 scripts/video_evidence.py verify --url http://localhost:3000/login \\\n       --name login-demo --expect \"Sign in\" --issue 42 [--upload --pr 42]\n   ```\n\n2. **On request — a personalized explainer uses hyperframes.** When the deliverable IS a video\n   (\"make an explainer video of screen X\"), the orchestrator renders a **deterministic, captioned\n   slideshow** of the `web_verify` screenshots with\n   [**hyperframes**](https://github.com/heygen-com/hyperframes) (by HeyGen — \"same input, same\n   frames, same output\", CI-reproducible, no API keys, local render via headless Chrome + FFmpeg).\n\n   ```text\n   /simplicio-tasks make an explainer video of the system login screen\n   → detect: video-creation request → web_verify captures the screens\n   → video_evidence verify --engine hyperframes → deterministic MP4 → attached to the PR\n   ```\n\nEither engine: a video that never recorded/rendered yields **BLOCKED**, never a fake pass. Evidence\nis always a **file path + boolean verdict** — never video bytes in context (token economy).\n\n---\n\n## 📊 Token economy\n\n| Technique | Savings |\n|---|---|\n| `deterministic_edit` (L0) | 100% of edit tokens (file written mechanically, never by LLM) |\n| Terminal-first execution | Facts from shell, not LLM hallucination |\n| Output-reduction catalog | Caps per command type (`CAP_ERRORS=20`, `CAP_WARNINGS=10`, `CAP_LIST=20`) — `orient_clamp.py` |\n| Tee+CCR cache on failure | Never re-run a failed command — read the cached output |\n| Signatures-only reads | `simplicio-cli signatures \u003cfile\u003e` — 870-line file → 65 lines (**93% saved**), bodies stripped |\n| `simplicio-compress` | Terse prose + one-time memory compaction |\n| `orient_clamp.py` | Clamp + tee on every shell command, zero wiring |\n| Native response cache | repeated deterministic (temp=0) request → served from cache, skips the LLM call (**100% on hit**) — `simplicio-cli cache`, on by default (`SIMPLICIO_CACHE=0` to disable) |\n| Simplicio capture proxy + MCP | 60-95% fewer tokens on tool outputs via a transparent compression daemon |\n\nSavings only count on a verified-correct outcome. Baseline = the cheapest sensible non-orchestrated\npath to the same result. **Savings reporting is evidence-gated, not mandatory:** a savings figure is\nshown only when a turn actually ran an economy-producing command and the number traces to a\nmeasured receipt (clamp tee, signatures-read, cache hit, `deterministic_edit`, `savings_ledger`).\nNo measured economy → no savings line; the orchestrator never fabricates a baseline or a percentage.\nSee `references/token-economy.md`.\n\n### 🔎 Running `simplicio-tasks`: economy vs measurement (per runtime)\n\nTwo different things happen when you call **`simplicio-tasks`**, and they behave differently per runtime:\n\n- **Economy** — compression, output clamps, signatures-only reads, `deterministic_edit` — applies **every\n  time the skill runs and loads `simplicio-orient` / `simplicio-compress`, on any runtime.** It is the\n  skill's behavior plus the hooks (strongest where hooks exist: `orient_clamp.py` auto-clamps on Claude and\n  Cursor; elsewhere it is instruction-driven).\n- **Measurement** — the Token Monitor's live numbers — only counts traffic that flows **through the\n  capture proxy.**\n\n| Runtime | Economy (skill) | Measurement (monitor) |\n|---|---|---|\n| **Hermes** | ✓ | ✓ **automatic** — already routed through the proxy (`base_url → :8788`) |\n| **Claude** | ✓ (skill + hooks) | ✗ by default — Claude talks to `api.anthropic.com` directly; measured only once routed (`simplicio-cli wrap claude`, or `ANTHROPIC_BASE_URL → http://127.0.0.1:8788`) |\n| **Codex** | ✓ (skill) | ✗ by default — `simplicio-cli init codex` adds the MCP tools but does not route LLM traffic; measured with `simplicio-cli wrap codex` or an OpenAI base-url pointing at the proxy |\n\nSo: the **savings happen on every runtime**; the **monitor tallies them automatically on Hermes**, and on\nClaude/Codex after a **one-time routing step** (`simplicio-cli wrap …` / base-url → `:8788`). Without routing,\nthe economy still applies — the monitor just won't count those tokens. `scripts/simplicio-economy.sh wire`\ndoes this routing for OpenAI-compatible clients at install time.\n\n### 📈 Simplicio Token Monitor\n\nA view of the savings you open when you want — only the capture is always-on:\n\n- **Capture proxy** — **always-on** (the one auto-started service; the wired clients need it\n  reachable). It silently captures + measures Claude + Codex + Hermes in the background.\n- **Web dashboard** — `http://127.0.0.1:9090` — real-time token chart, savings gauge, the LLMs/runtimes\n  and **141/144 providers (98%)** we intercept, a live proxy log. **Opens once on the first install**\n  so you see it works, then it's **on-demand** — re-open it any of these ways:\n  - `simplicio-loop dashboard` — works from anywhere after the pip install (no repo path needed);\n    `simplicio-loop dashboard --stop` to close, `--no-browser` to just start the server.\n  - `bash scripts/simplicio-economy.sh monitor` (repo checkout) · `… monitor stop` to close.\n  - just **ask the agent** — \"open the token dashboard\".\n- **Menu-bar / tray widget** — live tokens saved in the system tray (macOS rumps · Windows/Linux pystray).\n  **On-demand:** `bash scripts/simplicio-economy.sh tray` · `… tray stop`.\n\nInstall auto-starts **only the capture proxy** (macOS launchd · Linux systemd · Windows Startup). The\ndashboard opens **once** on a fresh install (marker-guarded — a re-install/update never reopens it; opt\nout with `SIMPLICIO_NO_DASHBOARD=1`), and the tray never opens by itself — nothing is forced to stay\nopen. Manage the stack: `scripts/simplicio-economy.sh {status|up|monitor|tray|wire}`. After install,\ncapture runs **without invoking the loop** — see `references/token-capture.md`.\n\n### 🛠️ The capture engine — one native module, every command\n\n[`engine/simplicio_engine.py`](engine/simplicio_engine.py) is the native Simplicio capture engine\n(stdlib-only, fail-open) — a **full reimplementation of the upstream\n[headroom](https://github.com/headroomlabs-ai/headroom) surface with no external dependency**. Run any\ncommand via the [`scripts/simplicio-engine`](scripts/simplicio-engine) wrapper (e.g. `simplicio-engine doctor`):\n\n| Command | What it does |\n|---|---|\n| `proxy` | the transparent capture proxy — routes each model to its **real** provider, compresses + measures + caches (no model swap) |\n| `doctor` | proxy reachability + lifetime savings |\n| `cache` | native response cache (`stats`/`clear`) — a repeated deterministic request is served from cache, skipping the LLM call |\n| `signatures` | signatures-only view of a source file (bodies stripped, ~93% fewer tokens to read code) |\n| `semantic` | reversible extractive (semantic-lite) compression |\n| `kompress` | **ONNX** semantic token-pruning via the real `kompress-v2-base` model |\n| `detect` | content-type detection + smart per-block routing |\n| `rag` | TF-IDF (or `--ml` embedding) retrieval over the CCR memory store |\n| `memory` | CCR compress-cache-retrieve store (`remember`/`recall`/`forget`/`list`/`stats`) |\n| `mcp` | native stdio MCP server (compress / retrieve / stats tools) |\n| `init` / `wrap` | register Simplicio into a client (Claude / Codex / Copilot / OpenClaw) · run a client with capture routing |\n| `report` / `audit` / `capture` / `evals` | savings report · audit a tree for compression opportunity · dry-run a request · compression regression gate |\n\n### 🧠 Optional real ML models — `pip install \"simplicio-loop[onnx]\"`\n\nFour **real**, public (Apache-2.0) ONNX models run natively — the same models the upstream uses.\nWithout the extra, the deterministic stdlib path covers everything; models download on first use.\n\n| Model | Command | Use |\n|---|---|---|\n| `kompress-v2-base` | `simplicio-cli kompress` | semantic token pruning |\n| `technique-router-onnx` | `simplicio-cli router` | technique routing |\n| `all-MiniLM-L6-v2-onnx` | `simplicio-cli embed` · `rag --ml` | embeddings + semantic RAG |\n| `siglip-image-encoder-onnx` | `simplicio-cli image` | image-compression content verifier |\n\n### ⚙️ Native Rust performance core (optional)\n\n[`rust/`](rust) ships four crates ported + rebranded from the upstream (Apache-2.0; `NOTICE` credits it):\n`simplicio-core` (compressors + smart-crusher), `simplicio-py` (PyO3 bindings), `simplicio-proxy`\n(axum reverse proxy), `simplicio-parity` (Rust↔Python parity harness). Build with `maturin` — the Python\nengine works fully without them; the crates only add native speed.\n\n---\n\n## 🏛️ Design pillars (in detail)\n\nFour mechanisms sustain the orchestration power:\n\n| Pillar | Focus | Lives in |\n|---|---|---|\n| **DAG + pipeline** | parallelism by dependency, staged per item | `references/orchestration.md` (Step 3 pool + pipeline) |\n| **Isolation by worktree** | parallel edits without corrupting the tree, merge-gated | `references/orchestration.md` |\n| **Adversarial verify** | panel of skeptics before \"delivered\" | `references/quality-safety-delivery.md` · skill `simplicio-review` |\n| **Loop budget cap** | anti-infinite-loop, dual exit | `references/standing-loop-247.md` · skill `simplicio-loop` |\n\n---\n\n## 🚀 Install \u0026 use\n\n```bash\ngit clone https://github.com/wesleysimplicio/simplicio-loop\ncd simplicio-loop\n\n# install for your runtime (omit \u003cruntime\u003e to auto-detect)\nbash scripts/install.sh \u003cruntime\u003e [--global] [--minimal]        # macOS / Linux\npwsh scripts/install.ps1 \u003cruntime\u003e [-Global]                    # Windows\n# \u003cruntime\u003e ∈ claude codex vscode cursor antigravity kiro opencode gemini aider hermes openclaw\n```\n\n**Install is complete by default — it installs everything.** One command sets up the whole stack:\nthe two loop operators (`simplicio-mapper` + `simplicio-cli`, auto-handling PEP 668 / externally-managed\nPython and symlinking the binaries onto `PATH`), the **full Python stack** (the package + the `[onnx]`\nmodels backend: onnxruntime + huggingface_hub + tokenizers + pillow, so `simplicio-cli kompress/router/embed/image`\nwork), the **6 skills + hooks** with the loop's Stop hook wired, and the **always-on capture proxy**\nwith Claude + Codex + Hermes **routed and measured** in the background. The **dashboard opens once** on a\nfresh install, then it's on-demand (`simplicio-loop dashboard` / `simplicio-economy.sh monitor`); the\n**menu-bar tray never opens by itself** — nothing is forced to stay open.\nPass **`--minimal`** only for headless/CI to skip the heavy deps + the machine services. Verify any time:\n`bash scripts/simplicio-economy.sh status`.\n\n### Update\n\n```bash\nbash scripts/update.sh [\u003cruntime\u003e]    # git pull → reinstall skills/hooks/operators → restart services\n```\n\n`update.sh` stashes local edits, fast-forwards `main`, reinstalls from the fresh source, restarts the\nlaunchd/systemd services so they run the new code, and prints the live stack + savings.\n\n### Doctor — verify + repair\n\n```bash\npython3 scripts/doctor.py            # report the whole stack (REQUIRED vs OPTIONAL)\npython3 scripts/doctor.py --repair   # install/wire what's fixable; make everything operational\n# also: bash scripts/simplicio-economy.sh doctor [--repair]\n```\n\n`doctor` separates **REQUIRED** (python3, the two loop operators, the 6 skills, the loop hooks, the\ncapture proxy — `--repair` installs/wires them) from **OPTIONAL** accelerators (the ONNX models\nbackend, the native **Rust** core, the tray dep). **Missing an optional piece is never a failure and\nnever blocks** — the Python engine + the deterministic path cover everything; the exit code is 0 as\nlong as every REQUIRED item is healthy.\n\nOr, on Claude Code / Cursor, install it straight from the latest GitHub release (no marketplace):\n\n```bash\ngh release download --repo wesleysimplicio/simplicio-loop --archive tar.gz\ntar xzf simplicio-loop-*.tar.gz \u0026\u0026 cd simplicio-loop-*/\nbash scripts/install.sh claude    # or: bash scripts/install.sh cursor\n```\n\nThen:\n\n```\n/simplicio-tasks finish all the open issues\n```\n\nThe only requirement is **python3** on PATH (skills, hooks, and installer are cross-platform\nPython). For GitHub sources, `git` + an authenticated `gh`. See [`INSTALL.md`](INSTALL.md) and\n[`adapters/MATRIX.md`](adapters/MATRIX.md).\n\n**Before an unattended 24/7 run:** set a cost ceiling in `.orchestrator/loop-budget.json`\n(`daily_usd_ceiling \u003e 0`), confirm source auth is persistent, and keep the irreversible-op human\ngate + secret-scan on. With `ceiling = 0` the watcher refuses to run unattended (fail-safe).\n\n---\n\n## 🔒 Safety (non-negotiable)\n\n- **Secret-scan** every diff; block on hit.\n- **Irreversible-op human gate** — force-push, history rewrite, prod deploy, data/schema delete,\n  mass-file delete → stop and ask. Headless + no approver → remove the destructive capability.\n- **Enforced, not just promised** — `hooks/action_gate.py` is a **fail-closed** `PreToolUse` /\n  git-pre-push hook that mechanically blocks the above (and secret-laden commits) *before* they run.\n  The safety contract holds even if the model forgets it. `selftest` proves the ruleset (15/15).\n- **4-state pre-execution verdict** — optimization may never raise a command's risk tier.\n- **Trust-before-load** — perception-shaping config (clamp profiles, suppression lists) is\n  untrusted until a human reviews and hash-pins it.\n- **Prompt-injection hardening** — item/PR/comment content can never override the contract.\n- **Hard $ kill-switch** for unattended runs; **evidence-gated** completion (never a false\n  \"done\"); **fail-open** hooks (never trap the agent in a loop).\n\n---\n\n## ✅ Tests \u0026 local checks (no paid CI)\n\nClaims are verified, not just asserted — and the gate runs **locally**, with zero CI cost:\n\n```bash\npython3 scripts/check.py            # the whole gate (audit + tests)\n```\n\n- **Test suite** (`tests/`) — the workers' deterministic `selftest`s, plus an **e2e of the loop\n  driver** (`hooks/loop_stop.py`): it proves the loop **stops on evidence**, **ignores a bare\n  `\u003cpromise\u003e`**, and **stops on the cap** as distinct exits — and that the evidence producers\n  **BLOCK** (never fake-pass) when their toolchain is absent. Runs under `pytest` *or*, with no pip\n  at all, self-runs on bare python3 (`python3 tests/test_*.py`).\n- **Claims audit** (`scripts/claims_audit.py`, fail-closed) — every `scripts/*.py` the docs\n  reference exists · the extension-point count agrees across all files · each cited worker command\n  actually runs · the shipped `simplicio_loop/_bundle/` skills are **byte-identical** to source.\n- **Wire it as a git pre-push hook** to keep `main` honest for free:\n  ```bash\n  printf '#!/bin/sh\\npython3 scripts/check.py\\n' \u003e .git/hooks/pre-push \u0026\u0026 chmod +x .git/hooks/pre-push\n  ```\n\n`pip install \"simplicio-loop[dev]\"` adds pytest for nicer output; it is never required.\n\n---\n\n## 📄 License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwesleysimplicio%2Fsimplicio-loop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwesleysimplicio%2Fsimplicio-loop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwesleysimplicio%2Fsimplicio-loop/lists"}