meow-swarm 0.3.0 → 0.5.0

package/.claude/scheduled_tasks.json

@@ -0,0 +1,3 @@
+{
+  "tasks": []
+}

package/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"8ee49b11-9dbb-4c1b-8ed5-82d6e9023eaa","pid":492208,"procStart":"639150108404627040","acquiredAt":1779526818153}

package/.claude/settings.local.json

@@ -0,0 +1,45 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh pr *)",
+      "Bash(npx vitest *)",
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git push *)",
+      "Bash(git checkout *)",
+      "Bash(git rm *)",
+      "Bash(npm run *)",
+      "Bash(npm test *)",
+      "Bash(echo \"EXIT:$?\")",
+      "Read(//c/Users/stanc/github/meow/src/**)",
+      "Read(//c/Users/stanc/github/meow/src/ai_loop/**)",
+      "Bash(git -C ~/github/meow status --short)",
+      "Bash(git -C \"C:\\\\Users\\\\stanc\\\\github\\\\meow\" status)",
+      "Bash(git -C \"C:\\\\Users\\\\stanc\\\\github\\\\meow\" log --oneline -3)",
+      "Bash(git -C \"C:\\\\Users\\\\stanc\\\\github\\\\meow\" checkout -b docs/refactor-structure)",
+      "Bash(git -C \"C:\\\\Users\\\\stanc\\\\github\\\\meow\" log --oneline -5)",
+      "Bash(git -C \"C:\\\\Users\\\\stanc\\\\github\\\\meow\" push --no-verify -u origin docs/refactor-structure)",
+      "Bash(git -C \"C:\\\\Users\\\\stanc\\\\github\\\\meow\" diff README.md)",
+      "Bash(git commit --no-verify -m 'docs: simplify README to plain description *)",
+      "Bash(meow -p \"Create a repository map document and save it to docs/repo-map.md. The map should cover the top-level directories and key files, their purpose, and how they relate to each other. Format it as a clear reference guide for someone reading the codebase.\")",
+      "Bash(node dist/bin/meow.js -p \"Fix BUG-01: vec_memory integer primary key crash. Symptom: 'SqliteError: Only integers are allowed for primary key values on vec_memory' fires 7-10x per session. Root cause: the vec_memory table \\(sqlite-vec\\) requires integer PKs but inserts are passing a non-integer \\(UUID/string\\). Fix: use INTEGER PRIMARY KEY AUTOINCREMENT for the vec_memory table, store the UUID as a separate column. File: src/agent/memory.ts or wherever vec_memory rows are inserted. After fixing: run npm test to confirm no regressions, then mark BUG-01 closed in docs/STATUS.md and check its checkbox in docs/ROADMAP.md.\")",
+      "Bash(node dist/bin/meow.js --tui)",
+      "Read(//tmp/**)",
+      "Bash(xargs wc -l)",
+      "Bash(ls -lah /c/Users/stanc/AppData/Local/Temp/claude/*/tasks/bze8v5iiq.output 2>/dev/null | head -5 && echo \"---\" && wc -l /c/Users/stanc/AppData/Local/Temp/claude/*/tasks/bze8v5iiq.output 2>/dev/null)",
+      "Bash(git commit -m 'fix: resolve BUG-01 vec_memory integer PK crash by using correct sqlite-vec API vec0_insert\\(\\) *)",
+      "Bash(git commit -m 'fix: resolve BUG-02 fixMeow\\(\\) timeout on Windows by using exec\\(\\) instead of spawn\\(\\) *)",
+      "Bash(git commit -m 'docs: remove BUG-02 warning from CLAUDE.md \\(fixed in e0cfe07\\) *)",
+      "Bash(git commit -m 'chore: clean up .env — remove duplicate and non-standard variables *)",
+      "Bash(python3 -c ' *)",
+      "Bash(git clone *)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" https://biosphere-gateway-24qvfiqipa-uc.a.run.app/anthropic/v1/messages)",
+      "Bash(curl -s https://biosphere-gateway-24qvfiqipa-uc.a.run.app/)",
+      "Bash(curl -s -X POST https://biosphere-gateway-24qvfiqipa-uc.a.run.app/anthropic/v1/messages -H 'Authorization: Bearer sk-ant-api03-y7XcGi4-O5TQQIxzDR9OEWSQaIf9Lx5NPlSBsTPEj4BdjSljxUJCfSsdHQi4UvYy7KOizFUKv3GLmkyZ9-wVhFj4LZOsfP4' -H 'Content-Type: application/json' -H 'anthropic-version: 2023-01-01' -d '{\"model\":\"MiniMax-M2.7\",\"max_tokens\":10,\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}')",
+      "Bash(curl -s -X POST https://biosphere-gateway-24qvfiqipa-uc.a.run.app/anthropic/v1/messages -H 'Authorization: sk-ant-api03-y7XcGi4-O5TQQIxzDR9OEWSQaIf9Lx5NPlSBsTPEj4BdjSljxUJCfSsdHQi4UvYy7KOizFUKv3GLmkyZ9-wVhFj4LZOsfP4' -H 'Content-Type: application/json' -H 'anthropic-version: 2023-01-01' -d '{\"model\":\"MiniMax-M2.7\",\"max_tokens\":10,\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}')",
+      "Bash(curl -s -X POST https://biosphere-gateway-24qvfiqipa-uc.a.run.app/anthropic/v1/messages -H 'Authorization: Bearer sk-ant-api03-y7XcGi4-O5TQQIxzDR9OEWSQaIf9Lx5NPlSBsTPEj4BdjSljxUJCfSsdHQi4UvYy7KOizFUKv3GLmkyZ9-wVhFj4LZOsfP4' -H 'Content-Type: application/json' -H 'anthropic-version: 2023-01-01' -d '{\"model\":\"MiniMax-M2.7\",\"max_tokens\":5,\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}')",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\('OK:', d.get\\('type', d\\)\\)\")",
+      "Bash(curl -s -X POST https://biosphere-gateway-24qvfiqipa-uc.a.run.app/anthropic/v1/messages -H 'Authorization: Bearer sk-ant-api03-y7XcGi4-O5TQQIxzDR9OEWSQaIf9Lx5NPlSBsTPEj4BdjSljxUJCfSsdHQi4UvYy7KOizFUKv3GLmkyZ9-wVhFj4LZOsfP4' -H 'x-api-key: sk-ant-api03-y7XcGi4-O5TQQIxzDR9OEWSQaIf9Lx5NPlSBsTPEj4BdjSljxUJCfSsdHQi4UvYy7KOizFUKv3GLmkyZ9-wVhFj4LZOsfP4' -H 'Content-Type: application/json' -H 'anthropic-version: 2023-01-01' -d '{\"model\":\"MiniMax-M2.7\",\"max_tokens\":5,\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}')"
+    ]
+  }
+}

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 stancsz
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 stancsz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,111 +1,161 @@
-# meow-swarm
-
-**The problem:** You want an AI coding agent that runs autonomously — not a chat window you babysit, but a background worker that accepts a task, runs to completion, and reports back. While you sleep. While you work on something else. In CI.
-
-**The solution:** `meow -p "task"` dispatches a self-healing, quality-gated coding agent into the background. It checkpoints every step to SQLite, retries on failure, stops when it's stuck, and surfaces everything in a TUI dashboard.
-
-```bash
-npm install -g meow-swarm
-meow -p "refactor auth into its own service"
-```
-
----
-
-## Install
-
-**Requires:** Node.js 18+ · `ANTHROPIC_API_KEY` env var set
-
-```bash
-npm install -g meow-swarm
-export ANTHROPIC_API_KEY=sk-ant-...   # or set in shell profile
-
-# Primary: headless (no TTY required) — designed for scripts, CI, or background dispatch
-meow -p "fix the race condition in src/queue.ts"
-
-# Interactive TUI dashboard
-meow --tui
-
-# Interactive REPL
-meow
-```
-
-Bun is not supported. `better-sqlite3` requires Node.js native addons.
-
----
-
-## What it actually does
-
-```
-you → meow -p "task" → background → checkpoint → quality gate → done
-                                    ↓ stuck?
-                              retry / adapt / stop + report
-```
-
-1. **Receives a task** via `meow -p` (headless, no TTY) or `meow` (interactive REPL)
-2. **Dispatches to L4 specialist** (Claude Code subprocess)
-3. **Mission reviewer scores output** across 7 criteria
-4. **Quality gate** — if output fails, it retries with reviewer notes
-5. **Convergence check** — stops if stagnating, budget exceeded, or diminishing returns
-6. **Checkpoints state** to SQLite after every iteration — crash-safe
-7. **TUI dashboard** shows live task progress, queue, and history
-
----
-
-## Self-healing: the MEOW-3-RULE
-
-When `meow -p` fails 3 times, it doesn't just give up. It surfaces a diagnostic:
-
-```
-Task arrives → meow -p "task"   (3 retry attempts)
-  ↓ fails × 3
-claude -p "fix meow-swarm"       (repairs meow-swarm's own code, NOT the task)
-  ↓
-you re-run → meow -p "task"     (now succeeds)
-```
-
-`claude -p` only fires when meow-swarm's own code/prompts are broken. It fixes meow-swarm, then you re-dispatch the original task. This is the operator loop — you never fix tasks manually.
-
----
-
-## Quality gates
-
-Every output is scored before it can be marked complete:
-
-| Gate | Checks | On fail |
-|------|--------|---------|
-| `NO_MOCKS` | No `TODO`, `FIXME`, placeholder code | Retry with note |
-| `TYPE_CHECK` | `tsc --noEmit` passes | Retry |
-| `LINT_CLEAN` | ESLint 0 errors | Retry |
-| `MISSION_COMPLETE` | Goal keywords present in output | Retry |
-| `SOP_COMPLIANCE` | Think-Plan-Verify pattern | Retry |
-
----
-
-## Configuration
-
-| Variable | Default | Notes |
-|----------|---------|-------|
-| `ANTHROPIC_API_KEY` | *(required)* | API key for LLM calls |
-| `ANTHROPIC_BASE_URL` | *(not set)* | Override for custom LLM endpoints |
-| `ANTHROPIC_MODEL` | `claude-sonnet-4` | Model name |
-| `MEOW_DB` | `~/.meow/meow.db` | SQLite checkpoint store |
-| `MEOW_MODE` | `SEQUENTIAL` | `SEQUENTIAL` · `PARALLEL` · `SHIP` · `AUDIT_ONLY` |
-
----
-
-## Architecture
-
-```
-L1 LIAISON      — Receives tasks, escalates ambiguity to human
-L2 ARCHITECT     — Breaks tasks, sequences dependencies
-L3 ORCHESTRATOR  — Task queue, convergence checks, dispatch
-L4 SPECIALISTS   — Claude Code subprocesses (can be swapped)
-```
-
-State is checkpointed to SQLite after every operation. If the process dies, the next invocation resumes from the last checkpoint.
-
----
-
-## License
-
-MIT
+# meow-swarm
+
+> One prompt. Meow plans it, builds it, verifies it, and repairs itself if anything breaks.
+
+```bash
+meow -p "add OAuth2 login to the API with tests"
+# → dispatched. check back with meow --tui
+```
+
+Most coding agents execute your prompt once and hand you back a diff. Meow-swarm is different: it runs a full plan → build → quality-verify → self-repair loop autonomously, and doesn't mark a task done until it can show evidence the work is correct.
+
+---
+
+## What makes meow-swarm different
+
+### 1. Definition of Done before the first line of code
+
+When a task arrives, meow derives explicit acceptance criteria from your request before touching anything. It knows what "done" looks like — specific, verifiable outcomes — before it starts. This is what separates a task that completes from one that finishes.
+
+### 2. Quality gates, not just a diff
+
+After every execution, meow runs a structured self-review loop against a set of quality gates:
+
+| Gate | What it checks |
+|------|---------------|
+| **Placeholder Detection** | No TODOs, FIXMEs, or stub bodies in produced code |
+| **Lint / Type Check** | Zero errors from the project's linter and type checker |
+| **Test Coverage** | Tests pass, coverage meets the project threshold |
+| **Coherence** | The diff actually addresses the stated goal (LLM review pass) |
+| **Human Sign-Off** | Production tasks require explicit approval before shipping |
+
+If gates fail, meow feeds the specific issues back into the agent loop and retries — up to a configurable iteration limit. A `QualityConvergenceChecker` tracks whether quality is genuinely improving each iteration and stops early if it detects diminishing returns, so it doesn't burn tokens grinding on something unfixable.
+
+### 3. Evidence-based completion
+
+Meow doesn't consider a task done because the code compiled. It runs the thing it built and captures the evidence:
+
+- **stdout / stderr** from running the produced code or tests
+- **Screenshots** for UI changes (visual diff against baseline)
+- **File read-back** for generated artifacts — confirms the file has real content, not a stub
+
+This evidence is fed to an LLM judge that scores the work against the original task description. Score below threshold → back into the loop with a specific critique. Score above threshold → task is marked complete with the evidence attached.
+
+### 4. MEOW-3-RULE: self-repair instead of giving up
+
+When meow fails three consecutive attempts on a task, it doesn't ask you for help. It runs a targeted `claude -p` call — not to finish the task, but to diagnose and patch meow's own code, prompts, or tool configuration. After the patch, the task is re-queued for a fresh attempt with the fixed machinery.
+
+```
+Task fails × 3
+  → claude -p "diagnose why meow failed, fix meow's code"
+  → meow is patched
+  → task re-queued → succeeds
+```
+
+The task and the mechanic are never conflated. Meow fixes itself; it doesn't sneak in a bad completion to avoid admitting failure.
+
+### 5. Skills-first execution
+
+Before writing any code for common task types — code review, frontend design, testing, documentation — meow searches the community skills ecosystem:
+
+- [`https://github.com/anthropics/skills`](https://github.com/anthropics/skills)
+- [`https://github.com/vercel-labs/skills`](https://github.com/vercel-labs/skills/blob/main/skills/find-skills/SKILL.md)
+
+A battle-tested code review skill has better prompts and output structure than anything meow would derive from scratch on every run. Skills are installed automatically if found (`npx skills add <skill> -g -y`) and invoked before falling back to raw LLM generation or a summon call.
+
+### 6. Background daemon — fire and forget
+
+Meow is not a chat partner. It runs in the background like a worker process:
+
+- Dispatch a task → returns immediately, work runs async
+- Checkpoints every state change to SQLite — crashes are recoverable
+- `meow --continue` resumes stranded tasks on reboot
+- `meow --tui` gives a live dashboard of agent status, task queue, and token costs
+
+You can dispatch a task, close your laptop, and come back to a completed result with a full audit trail of every decision and tool call.
+
+### 7. Multi-layer architecture with specialist routing
+
+```
+meow -p "task"
+       ↓
+  [L1 Liaison]          Intent extraction, MissionBrief with acceptance criteria
+       ↓
+  [L2 Architect]        Task decomposition, dependency resolution, specialist assignment
+       ↓
+  [L3 SwarmManager]     Parallel or sequential execution across specialist agents
+       ↓
+  [Self-Review Loop]    Quality gates, convergence check, evidence capture
+       ↓
+  [LLM Judge]           Scores output against original task — passes or feeds critique back
+       ↓
+  [L4 Auditor]          Final checkpoint to SQLite, cost tracking, audit ledger
+```
+
+Each layer uses the right model for its job. The Liaison uses a fast model for sub-500ms intent parsing. Deep execution uses your configured model (Claude Sonnet by default). The judge uses a separate call with the full context to avoid self-grading bias.
+
+---
+
+## Quick start
+
+```bash
+# Node.js 18+ required (Bun not supported — native SQLite addons require Node)
+npm install -g meow-swarm
+
+# Configure your API key
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# Dispatch a task
+meow -p "refactor the auth module to use JWT and add tests"
+
+# Watch it work
+meow --tui
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `meow -p "task"` | Dispatch task headlessly (primary interface) |
+| `meow` | Interactive REPL |
+| `meow --tui` | Live terminal dashboard |
+| `meow --continue` | Resume stranded tasks after a crash |
+| `meow --monitor` | Run the monitoring agent (cluster analysis, patch suggestions) |
+
+## Configuration
+
+Copy `.env.example` to `.env` and set:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ANTHROPIC_API_KEY` | required | API key |
+| `ANTHROPIC_MODEL` | `claude-sonnet-4` | Model for execution |
+| `MEOW_MODE` | `SHIP` | `SHIP`, `SEQUENTIAL`, `PARALLEL`, `ECOMODE`, `RALPH` |
+| `MEOW_BUDGET_CENTS` | unset | Hard spend cap per session |
+| `MEOW_DB` | `meow.db` | SQLite state database path |
+
+**Execution modes:**
+
+- `SHIP` — Full quality pipeline. Self-review loop, all gates, LLM judge. Use for production tasks.
+- `SEQUENTIAL` — Gates enabled, no judge pass. Good for development iteration.
+- `PARALLEL` — Maximum throughput, no quality gates. Use for bulk refactors you'll review yourself.
+- `ECOMODE` — Cheap model, 1 retry, 30s timeout. Fast exploration.
+- `RALPH` — Unlimited retries, relentless quality convergence. For hard problems where cost is secondary.
+
+---
+
+## MEOW-3-RULE (never violate this)
+
+```
+Task arrives → meow -p (3 retry attempts)
+  ↓ fails × 3
+claude -p (fixes meow's code/prompts — NOT the task)
+  ↓
+User re-runs same task → meow → succeeds
+```
+
+`claude -p` is a meow-swarm mechanic. It repairs broken machinery. It never completes the original task on meow's behalf.
+
+---
+
+See `docs/STATUS.md` for current known issues and `docs/TODO.md` for the prioritized improvement backlog.