meow-swarm 0.2.0 → 0.4.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,86 @@
-# meow-swarm
+# 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.
+A background coding harness that runs autonomous coding tasks while you sleep. You dispatch a task, it runs in the background, and you check back later via TUI or state files.
 
-**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"
+```
+meow -p "fix the auth bug in src/auth.ts"
+# → background task dispatched, check back later with `meow --tui`
 ```
 
----
+## How it works
+
+Meow-Swarm is a **background daemon** for coding tasks — think `nohup ./worker.sh &` but for AI coding agents:
 
-## Install
+1. **Dispatch** — Run `meow -p "your task"` and it immediately returns
+2. **Work** — The swarm picks tasks from a queue, runs them, checkpoints progress to SQLite
+3. **Monitor** — Watch progress via `meow --tui` (real-time dashboard) or `meow` (REPL)
+4. **Recover** — Crashes and restarts don't lose work; interrupted tasks resume from the last checkpoint
 
-**Requires:** Node.js 18+ · `ANTHROPIC_API_KEY` env var set
+## Quick start
 
 ```bash
+# Install (Node.js 18+ required)
 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.
 
----
+# Configure API key (Anthropic)
+export ANTHROPIC_API_KEY="sk-ant-..."
 
-## What it actually does
+# Dispatch a task (runs in background)
+meow -p "add user registration to the API"
 
+# Monitor progress
+meow --tui
 ```
-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:
+## Architecture
 
 ```
-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)
+meow -p "task"          # CLI entry → task queued in SQLite
+       ↓
+[L1 Liaison]            # Validates and decomposes task
+       ↓
+[L2 Architect]          # Breaks into subtasks, resolves dependencies
+       ↓
+[L3 SwarmManager]       # Spawns specialist agents (Claude Code subprocesses)
+       ↓
+[Sandbox Gate]          # Blocks dangerous shell commands (rm -rf, etc.)
+       ↓
+[Mission Reviewer]      # Scores result against 7 quality criteria
+       ↓
+[L4 Auditor]            # Final verification, checkpoints to SQLite
 ```
 
-`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.
+- **Specialist agents** are Claude Code subprocesses that work on subtasks
+- **Checkpointing** means crashes are recoverable — tasks resume where they left off
+- **Safety sandbox** blocks destructive operations before they run
+- **Multi-agent coordination** via SQLite-backed task claims (no two agents work on the same task)
 
----
-
-## Quality gates
+## Key features
 
-Every output is scored before it can be marked complete:
+- **Crash-safe** — SQLite checkpointing survives power failures and restarts
+- **Process cleanup** — Stuck subprocesses are killed (Windows `taskkill /f /t`, POSIX `SIGKILL`)
+- **Safety gates** — Dangerous shell commands blocked before execution
+- **Recovery mode** — `meow --continue` replays stranded tasks on boot
+- **TUI dashboard** — Real-time monitoring of agent status, token costs, and task progress
 
-| 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 |
+## Commands
 
----
+| Command | Description |
+|---------|-------------|
+| `meow -p "task"` | Dispatch task (headless, returns immediately) |
+| `meow` | Interactive REPL |
+| `meow --tui` | Terminal dashboard |
+| `meow --continue` | Resume stranded tasks after a crash |
 
 ## 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.
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ANTHROPIC_API_KEY` | required | API key for the LLM |
+| `ANTHROPIC_MODEL` | `claude-sonnet-4` | Model to use |
+| `MEOW_DB` | `meow.db` | SQLite database path |
+| `MEOW_MODE` | `SEQUENTIAL` | `SEQUENTIAL`, `PARALLEL`, or `SHIP` |
 
 ---
 
-## License
-
-MIT
+See `.env.example` for configuration options.