# So Many Crows

A flock of AI agents. Hand it a todo list; a Sentry crow triages each item, crows fly, and trust is earned over time.

Version one: command-line, text-only crows. No web, files, or APIs until each has guardrails.

## Run

```
go build -o crows .
./crows run todo.txt            # offline mock brain (no key needed)
ANTHROPIC_API_KEY=... ./crows run todo.txt   # real crows (Claude)
./crows trust                   # trust ledger
./crows log -n 20               # flight log
```

Optional: `CROWS_MODEL` overrides the model. Results land in `todo.crows.md`; state lives in `.crows/`.

## Web server

```
./crows serve                   # localhost:8080; API + Server-Sent Events (SSE); Ctrl-C to stop
```

The server runs the same pipeline as `crows run`, but items fly in parallel and approvals come over HTTP. `EVENTS.md` is the contract for events and the API:

```
curl -XPOST localhost:8080/api/lists -d '{"text":"- [ ] What is a crow","requester":"me"}'
curl -N "localhost:8080/api/events?list_id=<id>"        # replays the list's events so far, then streams
curl -XPOST localhost:8080/api/verdicts -d '{"item_id":"<id>-1","target":"triage","approve":true}'
curl localhost:8080/api/trust
```

- Item IDs are `<list_id>-<n>`, numbered from 1 in list order.
- Approvals left unanswered for 10 minutes count as rejected (`verdict: timeout`). `-approval-timeout` changes this for testing.
- A flooding requester gets 429 with `message` and `cooldown_s`; any list of theirs that is still flying also gets `requester.pranked`.
- POST bodies are capped at 64 KB. Static files are served from `./web` when that folder exists.

## How an item flies

1. **Sentry** classifies it: `solo` (one crow), `split` (2–4 subtasks in parallel), or `murder` (3 crows answer independently).
2. Split and murder results go to the **Elder**, who merges them and flags disagreement.
3. You approve or reject, depending on trust.

## Trust ladder

| Level    | Triage            | Output                         |
|----------|-------------------|--------------------------------|
| Stranger | you approve       | you approve                    |
| Regular  | you approve       | auto-accepted, marked unreviewed |
| Trusted  | runs on its own   | runs on its own                |

- Promotion: 10 clean approvals in a row (the flock as a whole needs 20).
- Demotion: one rejection drops a level.
- A crow's level blends its own record with the flock's record for that task type, so new crows start on the flock's reputation.
- The Sentry earns triage trust separately, per task type.
- The least-trusted crow on a job sets the approval bar.

## Guardrails (`guardrails.go`)

| Guardrail | Default |
|---|---|
| Crows in flight | 5 |
| Murder size | 3 |
| Items per list | 20 |
| Subtasks per split (depth 1, never re-split) | 4 |
| Tokens per item / per list | 20,000 / 100,000 |
| Crow timeout | 60s |
| Requests per minute per requester | 5 |
| Cooldown | 30s, doubling per strike, max 1h |

Fail-safe: any answer other than `y`, including no input, is a no.

## Abuse

Flooding the flock earns a mild prank message and a cooldown. Strikes fade one per clean day. Nothing destructive, nothing public.