meow-swarm 0.1.0 → 0.1.2

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 (4) hide show
  1. package/README.md +63 -116
  2. package/dist/index.js +208 -254
  3. package/package.json +16 -12
  4. package/src/index.ts +0 -92
package/README.md CHANGED
@@ -1,164 +1,111 @@
1
- # MEOW — Autonomous Multi-Agent Coding Harness
1
+ # meow-swarm
2
2
 
3
- ![](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square) [![npm]](https://www.npmjs.com/package/meow-agent)
4
- ![](https://img.shields.io/badge/License-MIT-green?style=flat-square)
5
- ![](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.
6
4
 
7
- **MEOW** (Meta-Orchestrator Operating on World) is a sovereign coding harness that runs locally in your terminal, coordinates specialist agents, and structural quality gates prevent hallucination from reaching output. Built on TypeScript and SQLite-vec.
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.
8
6
 
9
- **Learn more at [github.com/stancsz/meow](https://github.com/stancsz/meow)**
7
+ ```bash
8
+ npm install -g meow-swarm
9
+ meow -p "refactor auth into its own service"
10
+ ```
10
11
 
11
12
  ---
12
13
 
13
- ## Get Started
14
+ ## Install
15
+
16
+ **Requires:** Node.js 18+ · `ANTHROPIC_API_KEY` env var set
14
17
 
15
18
  ```bash
16
- # Install
17
- npm install -g meow-agent
19
+ npm install -g meow-swarm
20
+ export ANTHROPIC_API_KEY=sk-ant-... # or set in shell profile
18
21
 
19
- # Run a task (headless — no TTY required)
20
- meow -p "fix the stalled REPL in src/cli/repl.ts"
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
+
25
+ # Interactive TUI dashboard
26
+ meow --tui
21
27
 
22
28
  # Interactive REPL
23
29
  meow
24
-
25
- # Interactive TUI
26
- meow --tui
27
30
  ```
28
31
 
29
- Or clone and run:
30
-
31
- ```bash
32
- git clone https://github.com/stancsz/meow.git
33
- cd meow
34
- npm install
35
- npx tsx src/index.ts "your task here"
36
- ```
32
+ Bun is not supported. `better-sqlite3` requires Node.js native addons.
37
33
 
38
34
  ---
39
35
 
40
- ## What MEOW Does
36
+ ## What it actually does
41
37
 
42
38
  ```
43
- Task arrives
44
- │
45
- ▼
46
- L4 SPECIALIST (Claude Code / Aider) — implements
47
- │
48
- ▼
49
- MISSION REVIEWER — scores output across 7 criteria
50
- │
51
- ├── score >= threshold ──► COMMIT
52
- │
53
- └── score < threshold ──► RETRY (with review notes)
54
- │
55
- ┌──────────────┴──────────────┐
56
- ▼ ▼
57
- CONVERGENCE CHECK STAGNATION CHECK
58
- ─ token budget? ─ 2 iters no improvement?
59
- ─ max iters hit? ─ diminishing returns?
60
- │ │
61
- ▼ ▼
62
- STOP / REPORT ADAPT / DECOMPOSE
39
+ you → meow -p "task" → background → checkpoint → quality gate → done
40
+ ↓ stuck?
41
+ retry / adapt / stop + report
63
42
  ```
64
43
 
65
- MEOW does NOT grind until the user kills it. It evaluates whether continued iteration is productive and stops when it is not.
66
-
67
- ---
68
-
69
- ## Quality Gates
70
-
71
- Every output passes through structural gates before it can be committed:
72
-
73
- | Gate | Checks | Fail action |
74
- |------|--------|-------------|
75
- | `NO_MOCKS` | No `TODO`, `FIXME`, placeholder code | Retry with note |
76
- | `TYPE_CHECK` | `tsc --noEmit` passes | Retry |
77
- | `LINT_CLEAN` | ESLint reports 0 errors | Retry |
78
- | `REAL_TESTS` | Test files exist and non-empty | Warn (non-fatal) |
79
- | `MISSION_COMPLETE` | Goal keywords in output | Retry if missing |
80
- | `SOP_COMPLIANCE` | Think-Plan-Verify in output | Retry if missing |
81
-
82
- ---
83
-
84
- ## Convergence Logic
85
-
86
- MEOW stops iterating when:
87
-
88
- - **Stagnation** — No score improvement for 2 consecutive iterations
89
- - **Token budget exceeded** — Cumulative spend crosses threshold
90
- - **Diminishing returns** — Score improvement falls below minimum delta
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
91
51
 
92
52
  ---
93
53
 
94
- ## Execution Modes
95
-
96
- | Mode | Behavior |
97
- |------|----------|
98
- | `SEQUENTIAL` | One task at a time. Full review between each step. |
99
- | `SHIP` | Pass through all specialists with final review only. |
100
- | `PARALLEL` | Run independent tasks concurrently. |
101
- | `AUDIT_ONLY` | Score existing output without executing. |
102
-
103
- ---
54
+ ## Self-healing: the MEOW-3-RULE
104
55
 
105
- ## Architecture
56
+ When `meow -p` fails 3 times, it doesn't just give up. It surfaces a diagnostic:
106
57
 
107
58
  ```
108
- L1 LIAISON — Human-facing. Receives tasks, escalates ambiguity.
109
- L2 ARCHITECT — Mid-layer planner. Breaks tasks, sequences dependencies.
110
- L3 ORCHESTRATOR — Execution coordinator. TaskQueue, convergence checks.
111
- L4 SPECIALISTS — Claude Code / Aider subprocesses.
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)
112
64
  ```
113
65
 
114
- **Key files:**
115
-
116
- | File | Purpose |
117
- |------|---------|
118
- | `src/agent/agent.ts` | MEOW-3-RULE: 3-retry loop + fixMeow() |
119
- | `src/agent/summoner.ts` | Spawns specialist agents as subprocesses |
120
- | `src/agent/mission_reviewer.ts` | 7-criterion scoring, quality gates |
121
- | `src/orchestrator/Orchestrator.ts` | Convergence checks, task dispatch |
122
- | `src/kernel/kernel.ts` | Heartbeat loop, watchdog, respawn |
123
- | `src/db/database.ts` | SQLite + sqlite-vec for persistence |
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.
124
67
 
125
68
  ---
126
69
 
127
- ## MEOW-3-RULE
128
-
129
- MEOW uses `meow -p` as the primary interface (not `claude -p`):
70
+ ## Quality gates
130
71
 
131
- ```
132
- Task arrives → meow -p "task" (MEOW gets 3 retry attempts)
133
- ↓ fails × 3
134
- claude -p "fix MEOW" (fixes MEOW's own code, NOT the task)
135
- ↓
136
- User re-invokes same task → meow -p → succeeds
137
- ```
72
+ Every output is scored before it can be marked complete:
138
73
 
139
- `claude -p` only runs when MEOW's own code/prompts/tools are broken. It patches MEOW, then MEOW 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 |
140
81
 
141
82
  ---
142
83
 
143
84
  ## Configuration
144
85
 
145
- | Variable | Description | Default |
146
- |----------|-------------|---------|
147
- | `ANTHROPIC_API_KEY` | API key for LLM calls | (required) |
148
- | `ANTHROPIC_BASE_URL` | LLM endpoint | MiniMax gateway |
149
- | `ANTHROPIC_MODEL` | Model name | `claude-sonnet-4` |
150
- | `MEOW_DB` | SQLite database path | `~/.meow/meow.db` |
151
- | `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` |
152
93
 
153
94
  ---
154
95
 
155
- ## Requirements
96
+ ## Architecture
97
+
98
+ ```
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)
103
+ ```
156
104
 
157
- - Node.js 18+ (Bun is **NOT** supported — `better-sqlite3` native addons require Node)
158
- - TypeScript 5.0+
105
+ State is checkpointed to SQLite after every operation. If the process dies, the next invocation resumes from the last checkpoint.
159
106
 
160
107
  ---
161
108
 
162
109
  ## License
163
110
 
164
- MIT — see [LICENSE](LICENSE)
111
+ MIT