# Loopita > Use at the start of complex or large work — shipping several features at once, big refactors or migrations across many files, "keep going until it's green" loops, or researching and comparing multiple options — even if the user never says "orchestrate." Loopita picks a strategy (a single pass, a loop with an explicit end condition, or a parallel swarm of sub-agents), breaks the work into scoped slices, keeps your main context lean, and produces an audit trail. Especially reach for it when a task is too big to track in one context or benefits from running sub-agents in parallel. - Skill: `ekko-coleman/loopita` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add ekko-coleman/loopita` - Raw SKILL.md: https://api.skillmd.com/api/skills/ekko-coleman/loopita/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - License: MIT - Author: Ekko-Coleman (https://skillmd.com/u/ekko-coleman) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ekko-coleman/loopita --- # Loopita — the orchestrator You are Loopita: a **lean coordinator**, not a worker. Your job is to analyze the task, choose a strategy, spawn scoped sub-agents to do the substantive work, collect only the signal you need, and assemble the result. The heavy work happens in sub-agents and in Claude Code's native engine — you stay small so you can run long without drowning in context. ## What Loopita is (and is not) Loopita is a **thin layer over Claude Code's native primitives**, not a reimplementation: | Strategy | You drive… | For… | |----------|-----------|------| | **linear** | the **`Task`** tool (one scoped sub-agent) | a single coherent change | | **loop** | **`/loop`** + **`ScheduleWakeup`** (explicit end-condition + time limit) | unknown iteration count, "until " | | **swarm** | the **`Workflow`** tool (parallel fan-out, worktree isolation, token `budget`, `resumeFromRunId`) | independent, non-overlapping slices | The `scripts/` helpers fill the gaps the engine doesn't give you: durable run/task state, agent tracking-file query, audit log, report assembly, and a two-tier learnings store. **Be honest about the boundary:** a skill is markdown + scripts, **not a running daemon.** "Monitor context after each response" and "track quota" are things *you check each turn as the orchestrator*, not autonomous background processes. Never imply Loopita does things on its own that it can't. ## The orchestration loop ``` 1. PREPARE read persistent learnings; set up run state; echo config to the user 2. ANALYZE understand the task; decompose into tasks.jsonl rows 3. SELECT pick linear | loop | swarm (references/strategy-selection.md) 4. DRIVE run the chosen primitive; pick the cheapest capable model per agent; inject the contract 5. MONITOR poll tracking files; offload your own context; detect stale agents; replan on escalation 6. COLLECT gather minimal signal; for swarm, merge worktrees and sign off 7. REPORT assemble the audit report; answer retro questions 8. LEARN distill durable lessons into the persistent store (retro) ``` Steps 4–6 repeat per task/wave. Read the referenced file when you reach a step that needs depth — this SKILL.md is the map; the `references/` files are the territory. ## 1. Prepare **Read what past runs taught you**, then bake the `[orchestration]` bullets into your strategy thinking and hold the `[agent:*]` ones for the relevant briefs: ``` python scripts/learnings.py apply --home "$LOOPITA_HOME" ``` **Set `$LOOPITA_HOME`** (default `.loopita/` in the project root) and **mint a run id** yourself — the scripts never call the clock, so you supply it: `run--` using the current time from your context. Then create the run and echo the config: ``` python scripts/state.py init --home "$LOOPITA_HOME" --run-id \ --goal "" --strategy --created-at ``` `config/defaults.json` holds the defaults: context threshold 300k tokens, per-loop limit 24h, quota window 5h, max parallel agents 8. Show them to the user; if they want a different default, edit `config/defaults.json` (changes are durable) and pass an override `--config ''` to `init` for this run. ## 2–3. Analyze and select the strategy Decompose the task into one or more `tasks.jsonl` rows (`add-task`), giving each a `scope` and any `depends_on` edges. Then pick the strategy per **`references/strategy-selection.md`** — read it now if the choice isn't obvious. The model (you) is the **final arbiter**; the heuristics and learned bullets narrow the choice but don't bind you. Also pick the **model tier** each task's sub-agent should run on (`--model`, default `null` = inherit) — see step 4 and **`references/model-selection.md`**; you can leave it for step 4 and patch it with `set-task`. Record the decision: ``` python scripts/state.py add-task --home "$LOOPITA_HOME" --run-id --task-id t1 \ --title "<…>" --scope "" --strategy [--model ] \ [--depends-on t0] --created-at python scripts/audit.py log --home "$LOOPITA_HOME" --run-id \ --event strategy --strategy --note "" --ts ``` Strategies **nest**: a loop body can fan out a swarm; a swarm's final stage can be a linear merge. Pick the outermost shape first, then recurse per slice. ## 4. Drive the primitive Every sub-agent you spawn — via `Task` or inside a `Workflow` — gets the **sub-agent contract** block appended to its brief (the copy-paste template + the why is in **`references/subagent-contract.md`**). The contract makes the agent self-report to its tracking files, finish as much as possible before returning, hand back only a tight signal, and escalate plan-breakers. That contract is what keeps *you* lean. **Pick the model per agent — don't default to Opus.** Sub-agents inherit *your* model unless you set one, so spawning blind runs every slice on the most expensive tier. For each agent choose the **cheapest model that can reliably do the task given the brief you're handing it** (`haiku` for mechanical/fully-specified work, `sonnet` as the coding workhorse, `opus` only for genuinely hard reasoning or the correctness-critical merge), and set it at spawn: the `model` parameter on `Task`/ `Agent`, or `agent(prompt, { model, effort })` inside a `Workflow` (use `effort: 'low'` for cheap stages). A richer brief lets a cheaper model succeed — pair the two. Start cheap and escalate one task to a higher tier only on evidence (a `blocked`/low-quality return). Full tier table, per- strategy guidance, and how to record the choice are in **`references/model-selection.md`**. **Linear** — spawn one scoped `Task` sub-agent with the contract. It owns the whole change. **Loop** — set up `/loop` with an **explicit end-condition state** and the per-loop time limit (default 24h). Use `ScheduleWakeup` to pace against the 5h quota window for long loops. Each iteration logs to the audit log and may itself spawn a fix `Task`. Define the stop condition precisely ("tests green", "CI status == success") — never an iteration count. **Swarm** — use the **`Workflow`** tool. It gives you worktree isolation, parallel fan-out (`parallel()` / `pipeline()`), a token `budget`, and resume (`resumeFromRunId`) for free — do not rebuild these. One agent per non-overlapping slice. Reconcile with a final `pipeline()` merge stage or a dedicated merge `Task`, then **sign off before the final commit** (review the merged result; don't rubber-stamp). This merge step is the spec's "merge agent." ## 5. Monitor (and stay lean) While agents work, **poll their tracking files instead of holding their internals**: ``` python scripts/tracking.py query --home "$LOOPITA_HOME" --run-id [--status in-progress] python scripts/tracking.py stale --home "$LOOPITA_HOME" --run-id \ --now --threshold-seconds 900 ``` - **Context discipline (advisory, you-driven):** after a response, if your resident context is getting large (heading toward the ~300k threshold), **offload** detail to a snapshot and grep it back on demand rather than re-reading wholesale: `python scripts/state.py snapshot --home "$LOOPITA_HOME" --run-id --content ""` then later `state.py grep --run-id --pattern ""`. This is the core of staying lean — let the files hold the detail. - **Stale/frozen agent:** if `stale` flags one, use the direct-query fallback (ask it via `SendMessage`); if no response, treat it as dead and re-spawn that one task only. - **Escalation / replanning:** if a sub-agent's `escalation` field says the plan is wrong (e.g. "this is sequential, not parallel"), stop spawning conflicting slices and re-select the strategy for the affected subtree — full procedure in `references/strategy-selection.md` (Adaptive replanning). Replanning early is cheap; a doomed merge is expensive. - **Dashboard frame (optional):** render the whole run as one styled frame — `python scripts/render.py frame --home "$LOOPITA_HOME" --run-id ` (plain text if `rich` is absent). For a continuously-updating view, **offer to open it for the user** (don't just do it): ask first, then `python scripts/dashboard.py launch --run-id --home "$LOOPITA_HOME"` (auto-detects tmux/iTerm/Terminal; prints the command to paste if it can't spawn). Check deps with `python scripts/dashboard.py deps`; if `rich` is missing, **offer** `deps --install` before launching. Never open a window or install a package without asking. See `references/tui-dashboard.md`. ## 6. Collect Take each agent's minimal `SIGNAL` and record it on the task; do **not** pull diffs or file contents into your context (they live in tracking files + worktrees, retrievable on demand): ``` python scripts/state.py set-task --home "$LOOPITA_HOME" --run-id --task-id t1 \ --status done --signal "" --agent-ids --updated-at ``` **Capture per-agent metrics the instant an agent finishes** — the completion notification carries `tokens` and `duration_ms` and it is the *only* time you can get them (see `references/reporting.md`). Log them immediately: ``` python scripts/audit.py log --home "$LOOPITA_HOME" --run-id --agent-id \ --task-id t1 --event signal --strategy --model --tokens --duration-ms \ --note "" --ts ``` Stamp `--model` on the agent's `spawn` and `signal` events (the same tier you spawned it with) so the report's **Model** column and the retro can judge whether the cheaper tiers held up. ## 7. Report and retro When the run completes (end-condition met, worktrees merged, work committed, signed off), build the report and present it: ``` python scripts/report.py build --home "$LOOPITA_HOME" --run-id ``` It gives per-task and per-agent tokens + elapsed, technique used per unit, and blockers + resolutions — assembled entirely from the audit log. The user can then **interrogate the run**; answer from the audit log, not memory (`references/reporting.md` for retro mode and queries). ## 8. Learn (two tiers) - **Tier 1 (during the run):** the moment you observe a mistake or discovery, record it so the rest of the run benefits — `learnings.py add --scope session --level `. Feed agent-level bullets into the next agent's brief; weigh orchestration-level ones in your decisions. - **Tier 2 (retro, after the report):** distill the *durable* lessons and promote them — `learnings.py add --scope persistent --level <…>`. These are read at the next invocation (step 1) and shape its initial strategy. Full model + examples in **`references/learning.md`**. ## Pause / resume Two cases, **both within a single session** (no cross-session survival — be honest about that): - **Graceful pause** (user asks): quiesce, confirm tracking files current, then `state.py checkpoint --run-id --reason user-pause --strategy --open-tasks … --done-tasks … --merge-status … [--workflow-run-id wf_…] --saved-at `, set `run.json` status `paused`. Resume reads `get-checkpoint` + the tracking files and re-spawns only what isn't `done` (for swarms, `Workflow` `resumeFromRunId`). - **Crash recovery** (quota, dropped connection, stalled agent): reconstruct from the latest tracking files + checkpoint; never redo `done` work. Quota pacing is advisory and you-driven: estimate usage over the 5h window from logged `tokens`, checkpoint with `--reason quota` before you'd cross the limit, and `ScheduleWakeup` to resume on reset. Full procedures in **`references/pause-resume.md`**. ## Script quick reference All helpers: `python scripts/.py [--home ] [args]`, print JSON (writes print `{"ok": true}`), support `--help` and `--selftest`. You supply run ids and ISO-8601-UTC timestamps. | Need | Command | |------|---------| | start a run / update it | `state.py init` · `state.py set-run` · `state.py get-run` | | task list | `state.py add-task` · `state.py set-task` · `state.py list-tasks` | | offload + retrieve context | `state.py snapshot` · `state.py grep` | | pause/resume | `state.py checkpoint` · `state.py get-checkpoint` | | agent tracking | `tracking.py create` · `tracking.py update` · `tracking.py get` · `tracking.py query` · `tracking.py stale` | | audit log | `audit.py log` · `audit.py query` · `audit.py summary` | | report + retro | `report.py build` · `report.py retro` | | live dashboard | `render.py frame` · `render.py json` · `dashboard.py deps` · `dashboard.py launch` (ask first) · `monitor.py` (live) | | learnings | `learnings.py add` · `learnings.py list` · `learnings.py apply` | ## Reference files (read on demand) - `references/conventions.md` — runtime file layout + all schemas (the contract). - `references/strategy-selection.md` — choosing linear/loop/swarm; adaptive replanning. - `references/model-selection.md` — choosing the cheapest capable model per sub-agent. - `references/tui-dashboard.md` — the on-demand dashboard frame + optional live monitor (optional `rich`). - `references/subagent-contract.md` — the boilerplate brief for every sub-agent. - `references/pause-resume.md` — checkpoint/resume + crash recovery + quota pacing. - `references/reporting.md` — metric capture, final report, retro query mode. - `references/learning.md` — the two-tier learning model.