cruo-agent 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# cruo-agent
+
+Run a Cruo agent. It watches your board, picks up the cards you assign it, and
+works them — on your machine, under your own Claude account.
+
+```bash
+npx cruo-agent login cruo_pat_…    # the token Cruo showed you once
+npx cruo-agent --dry-run           # what would it pick up? starts no model
+npx cruo-agent                     # let it work
+```
+
+## What this actually is
+
+Three things people tend to run together, kept apart because they fail
+differently:
+
+- **The agent** is a member of your workspace — a row and a token. It signs in
+  to nothing, and nothing runs because it exists.
+- **The supervisor** is this program. It watches the board with a plain database
+  query, so sitting idle costs nothing, and starts a harness when there is work.
+- **The harness** is Claude Code, started fresh for one card and gone when that
+  card is done. Nothing carries over between cards but the board itself.
+
+Cruo runs no model of its own and never bills you for inference.
+
+## Getting a token
+
+Cruo → Settings → Members → **Add an agent**. The token is shown once; Cruo
+stores a hash. If you lose it, issue another from the key button on its row.
+
+Then assign the agent a card. That is the whole of the setup — an agent is a
+member, so it appears in the assignee list like anyone else.
+
+## Where the token comes from
+
+In order: `CRUO_TOKEN` in the environment, then `--token`, then whatever
+`cruo login` stored in `~/.cruo/config.json` (mode 0600).
+
+**There is no `cruo <token>` form on purpose.** A credential in a positional
+argument shows up in `ps` output, where every other user on the machine can read
+it, and in your shell history, where it stays. `--token` is there for a CI
+runner that injects secrets its own way, and it warns.
+
+## Letting it write code
+
+By default the harness gets the board and nothing else, which is right for an
+agent whose work is judgement over your issues. An agent that writes code needs
+a checkout and the tools to use it:
+
+```bash
+npx cruo-agent --worktree --allow 'mcp__cruo,Read,Glob,Grep,Edit,Write,Bash(git:*)'
+```
+
+`--worktree` gives every card its own checkout, cut fresh from `origin/main` —
+never the tree you are working in, and never whatever you have half-finished. It
+carries tracked files only, so an agent cannot read a `.env` you have not
+committed. When the run ends the checkout is deleted and the branch survives.
+
+Run it from the repository the agent should work on. If that repository needs
+installing before its tests will run, add `--prepare 'npm ci'` or whatever your
+equivalent is — a fresh checkout has your source and none of your dependencies.
+
+## Common options
+
+| flag | |
+|---|---|
+| `--once` | one pass, then exit |
+| `--dry-run` | show what it would pick up; starts no model |
+| `--limit <n>` | work at most n issues this pass |
+| `--interval <seconds>` | how often to poll (default 20) |
+| `--worktree` | a checkout per card |
+| `--allow <tools>` | what the harness may use |
+| `--push` | publish the branch after a run that commits |
+| `--harness-timeout <seconds>` | kill a run that wedges (default 600) |
+| `--max-attempts <n>` | give up on a card after n unproductive runs (default 3) |
+
+The full list, and what each is for: <https://cruo.space/agents>
+
+## Running it somewhere that is not your laptop
+
+The same command works on a server, and that machine needs no privileged access
+to Cruo: the supervisor trades its token for a short-lived session, so the only
+secret on the box is the agent's own token — scoped to one workspace, in one
+product, revocable from Settings.
+
+The harness still runs under your Claude account, on that box.
+
+## The name
+
+The package is `cruo-agent`; the command it installs is `cruo`. npm refuses the
+bare name as too close to `cron` and `crc`, and a bin's name is independent of
+its package's — so `npm i -g cruo-agent` gives you `cruo`, and `npx cruo-agent`
+works without one.

package/dist/VERSION

@@ -0,0 +1 @@
+0.1.0