meow-swarm 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +58 -121
  2. package/dist/index.js +597 -348
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,174 +1,111 @@
1
1
  # meow-swarm
2
2
 
3
- ![](https://img.shields.io/badge/npm-meow--swarm-blue?style=flat-square) ![](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square) ![](https://img.shields.io/badge/License-MIT-green?style=flat-square) ![](https://img.shields.io/badge/TypeScript-5.0-blue?style=flat-square)
3
+ **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.
4
4
 
5
- **`meow -p`** — the primary interface. Run autonomous coding agents in the background.
5
+ **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.
6
6
 
7
- ```
7
+ ```bash
8
8
  npm install -g meow-swarm
9
- meow -p "fix the auth bug in src/auth.ts"
9
+ meow -p "refactor auth into its own service"
10
10
  ```
11
11
 
12
- meow-swarm is a sovereign, stateful, multi-agent coding harness that runs locally in your terminal. It coordinates L1→L4 specialist agents, checkpoints every task state to SQLite, gates output quality before commit, and exposes a TUI dashboard. You fire it and come back later — it is not a synchronous chat partner.
13
-
14
12
  ---
15
13
 
16
- ## Get Started
14
+ ## Install
15
+
16
+ **Requires:** Node.js 18+ · `ANTHROPIC_API_KEY` env var set
17
17
 
18
18
  ```bash
19
- # Primary: headless mode (no TTY required) — this is meow -p
20
- meow -p "fix the stalled REPL in src/cli/repl.ts"
19
+ npm install -g meow-swarm
20
+ export ANTHROPIC_API_KEY=sk-ant-... # or set in shell profile
21
21
 
22
- # Interactive REPL
23
- meow
22
+ # Primary: headless (no TTY required) — designed for scripts, CI, or background dispatch
23
+ meow -p "fix the race condition in src/queue.ts"
24
24
 
25
- # Interactive TUI
25
+ # Interactive TUI dashboard
26
26
  meow --tui
27
- ```
28
-
29
- **Requirements:** Node.js 18+, `ANTHROPIC_API_KEY` env var. Bun is not supported (better-sqlite3 requires Node.js native addons).
30
-
31
- ---
32
-
33
- ## What is meow-swarm?
34
27
 
35
- A background daemon harness for autonomous coding agents. Think `nohup ./worker.sh &` — you dispatch a task, it runs in the background, you check the TUI or state files later.
36
-
37
- ```
38
- Task arrives
39
- │
40
- ▼
41
- L4 SPECIALIST (Claude Code) — implements
42
- │
43
- ▼
44
- MISSION REVIEWER — scores output across 7 criteria
45
- │
46
- ├── score >= threshold ──► COMMIT
47
- │
48
- └── score < threshold ──► RETRY (with review notes)
49
- │
50
- ┌──────────────┴──────────────┐
51
- ▼ ▼
52
- CONVERGENCE CHECK STAGNATION CHECK
53
- ─ token budget? ─ 2 iters no improvement?
54
- ─ max iters hit? ─ diminishing returns?
55
- │ │
56
- ▼ ▼
57
- STOP / REPORT ADAPT / DECOMPOSE
28
+ # Interactive REPL
29
+ meow
58
30
  ```
59
31
 
60
- meow-swarm does NOT grind until the user kills it. It evaluates whether continued iteration is productive and stops when it is not.
61
-
62
- ---
63
-
64
- ## Quality Gates
65
-
66
- Every output passes through structural gates before it can be committed:
67
-
68
- | Gate | Checks | Fail action |
69
- |------|--------|-------------|
70
- | `NO_MOCKS` | No `TODO`, `FIXME`, placeholder code | Retry with note |
71
- | `TYPE_CHECK` | `tsc --noEmit` passes | Retry |
72
- | `LINT_CLEAN` | ESLint reports 0 errors | Retry |
73
- | `REAL_TESTS` | Test files exist and non-empty | Warn (non-fatal) |
74
- | `MISSION_COMPLETE` | Goal keywords in output | Retry if missing |
75
- | `SOP_COMPLIANCE` | Think-Plan-Verify in output | Retry if missing |
76
-
77
- ---
78
-
79
- ## Convergence Logic
80
-
81
- meow-swarm stops iterating when:
82
-
83
- - **Stagnation** — No score improvement for 2 consecutive iterations
84
- - **Token budget exceeded** — Cumulative spend crosses threshold
85
- - **Diminishing returns** — Score improvement falls below minimum delta
86
-
87
- ---
88
-
89
- ## Execution Modes
90
-
91
- | Mode | Behavior |
92
- |------|----------|
93
- | `SEQUENTIAL` | One task at a time. Full review between each step. |
94
- | `SHIP` | Pass through all specialists with final review only. |
95
- | `PARALLEL` | Run independent tasks concurrently. |
96
- | `AUDIT_ONLY` | Score existing output without executing. |
32
+ Bun is not supported. `better-sqlite3` requires Node.js native addons.
97
33
 
98
34
  ---
99
35
 
100
- ## Architecture
36
+ ## What it actually does
101
37
 
102
38
  ```
103
- L1 LIAISON — Human-facing. Receives tasks, escalates ambiguity.
104
- L2 ARCHITECT — Mid-layer planner. Breaks tasks, sequences dependencies.
105
- L3 ORCHESTRATOR — Execution coordinator. TaskQueue, convergence checks.
106
- L4 SPECIALISTS — Claude Code / Aider subprocesses.
39
+ you → meow -p "task" → background → checkpoint → quality gate → done
40
+ ↓ stuck?
41
+ retry / adapt / stop + report
107
42
  ```
108
43
 
109
- **Key files:**
110
-
111
- | File | Purpose |
112
- |------|---------|
113
- | `src/index.ts` | CLI entry: `meow -p` for headless, `meow` for REPL, `meow --tui` for TUI |
114
- | `src/agent/agent.ts` | MEOW-3-RULE: 3-retry loop + fixMeow() + suggestUpstreamContribution() |
115
- | `src/agent/summoner.ts` | Spawns specialist agents as subprocesses |
116
- | `src/agent/mission_reviewer.ts` | 7-criterion scoring, quality gates |
117
- | `src/orchestrator/Orchestrator.ts` | Convergence checks, task dispatch |
118
- | `src/kernel/kernel.ts` | Heartbeat loop, watchdog, respawn |
119
- | `src/db/database.ts` | SQLite + sqlite-vec for persistence + checkpointing |
44
+ 1. **Receives a task** via `meow -p` (headless, no TTY) or `meow` (interactive REPL)
45
+ 2. **Dispatches to L4 specialist** (Claude Code subprocess)
46
+ 3. **Mission reviewer scores output** across 7 criteria
47
+ 4. **Quality gate** — if output fails, it retries with reviewer notes
48
+ 5. **Convergence check** — stops if stagnating, budget exceeded, or diminishing returns
49
+ 6. **Checkpoints state** to SQLite after every iteration — crash-safe
50
+ 7. **TUI dashboard** shows live task progress, queue, and history
120
51
 
121
52
  ---
122
53
 
123
- ## meow -p (the primary interface)
54
+ ## Self-healing: the MEOW-3-RULE
124
55
 
125
- `meow -p` is the primary headless interface — no TTY required, designed for calling from scripts, CI, or other AI agents:
56
+ When `meow -p` fails 3 times, it doesn't just give up. It surfaces a diagnostic:
126
57
 
127
58
  ```
128
- meow -p "your task description"
59
+ Task arrives → meow -p "task" (3 retry attempts)
60
+ ↓ fails × 3
61
+ claude -p "fix meow-swarm" (repairs meow-swarm's own code, NOT the task)
62
+ ↓
63
+ you re-run → meow -p "task" (now succeeds)
129
64
  ```
130
65
 
131
- The `-p` / `--plan` flag activates non-interactive mode. Task output goes to stdout. Progress goes to the TTY if available, otherwise to `~/.meow/` state files.
66
+ `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.
132
67
 
133
68
  ---
134
69
 
135
- ## MEOW-3-RULE
136
-
137
- meow-swarm's self-repair loop:
70
+ ## Quality gates
138
71
 
139
- ```
140
- Task arrives → meow -p "task" (meow-swarm gets 3 retry attempts)
141
- ↓ fails × 3
142
- claude -p "fix meow-swarm" (fixes meow-swarm's own code, NOT the task)
143
- ↓
144
- User re-invokes same task → meow -p → succeeds
145
- ```
72
+ Every output is scored before it can be marked complete:
146
73
 
147
- `claude -p` only runs when meow-swarm's own code/prompts/tools are broken. It patches meow-swarm, then meow-swarm retries and completes the task.
74
+ | Gate | Checks | On fail |
75
+ |------|--------|---------|
76
+ | `NO_MOCKS` | No `TODO`, `FIXME`, placeholder code | Retry with note |
77
+ | `TYPE_CHECK` | `tsc --noEmit` passes | Retry |
78
+ | `LINT_CLEAN` | ESLint 0 errors | Retry |
79
+ | `MISSION_COMPLETE` | Goal keywords present in output | Retry |
80
+ | `SOP_COMPLIANCE` | Think-Plan-Verify pattern | Retry |
148
81
 
149
82
  ---
150
83
 
151
84
  ## Configuration
152
85
 
153
- | Variable | Description | Default |
154
- |----------|-------------|---------|
155
- | `ANTHROPIC_API_KEY` | API key for LLM calls | (required) |
156
- | `ANTHROPIC_BASE_URL` | LLM endpoint | MiniMax gateway |
157
- | `ANTHROPIC_MODEL` | Model name | `claude-sonnet-4` |
158
- | `MEOW_DB` | SQLite database path | `~/.meow/meow.db` |
159
- | `MEOW_MODE` | Execution mode | `SEQUENTIAL` |
86
+ | Variable | Default | Notes |
87
+ |----------|---------|-------|
88
+ | `ANTHROPIC_API_KEY` | *(required)* | API key for LLM calls |
89
+ | `ANTHROPIC_BASE_URL` | *(not set)* | Override for custom LLM endpoints |
90
+ | `ANTHROPIC_MODEL` | `claude-sonnet-4` | Model name |
91
+ | `MEOW_DB` | `~/.meow/meow.db` | SQLite checkpoint store |
92
+ | `MEOW_MODE` | `SEQUENTIAL` | `SEQUENTIAL` · `PARALLEL` · `SHIP` · `AUDIT_ONLY` |
160
93
 
161
94
  ---
162
95
 
163
- ## npm
96
+ ## Architecture
164
97
 
165
98
  ```
166
- npm install -g meow-swarm
167
- https://www.npmjs.com/package/meow-swarm
99
+ L1 LIAISON — Receives tasks, escalates ambiguity to human
100
+ L2 ARCHITECT — Breaks tasks, sequences dependencies
101
+ L3 ORCHESTRATOR — Task queue, convergence checks, dispatch
102
+ L4 SPECIALISTS — Claude Code subprocesses (can be swapped)
168
103
  ```
169
104
 
105
+ State is checkpointed to SQLite after every operation. If the process dies, the next invocation resumes from the last checkpoint.
106
+
170
107
  ---
171
108
 
172
109
  ## License
173
110
 
174
- MIT — see [LICENSE](LICENSE)
111
+ MIT