@flumecode/runner 0.0.1

package/README.md

@@ -0,0 +1,98 @@
+# @flumecode/runner
+
+The FlumeCode **local runner**. It runs on your own machine, claims agent jobs
+from the FlumeCode web app, and drives your **local Claude Code** against a real
+checkout of the repo — editing files, running tests, and opening a pull request.
+
+Because the work runs on your machine and through your own Claude Code login, the
+FlumeCode service never stores an API key or runs your code itself.
+
+## Prerequisites
+
+- Node 20+
+- `git` on your PATH
+- [Claude Code](https://code.claude.com) installed and logged in (subscription),
+  or an `ANTHROPIC_API_KEY` exported in the shell you run the runner from
+- A runner token — create one in the web app on the **Runners** page
+
+## Install & run
+
+The runner ships as a global CLI on npm. The Runners page in the web app shows
+these exact commands with your token pre-filled:
+
+```bash
+npm install -g @flumecode/runner
+
+# Save the server URL + token (or run `flumecode login` for an interactive prompt)
+flumecode login --server https://<your-app> --token flrun_…
+
+# Start polling for jobs (keep it running)
+flumecode start
+```
+
+Config is written to `~/.flume/config.json` (mode 0600). The token lives only
+there and is sent only as the `Authorization` header to your server. The default
+server for a bare interactive `flumecode login` can be set via `FLUME_SERVER`.
+
+## Developing on the runner
+
+From the monorepo, run it straight from source with `tsx` (no build step):
+
+```bash
+pnpm install
+pnpm --filter @flumecode/runner dev login   # or: dev start
+```
+
+`pnpm --filter @flumecode/runner build` produces the published single-file bundle
+(`dist/cli.js`); it is published to npm by the `release-runner` GitHub workflow
+when a `runner-v*` tag is pushed.
+
+## What a job does
+
+1. Claim the next queued job for your account (`POST /api/runner/jobs/claim`).
+2. Clone the repo with a short-lived GitHub token and check out the frozen commit
+   on the request's `checkoutBranch`.
+3. Run Claude Code (`permissionMode: acceptEdits`) over the working directory with
+   the request + thread as the prompt.
+4. If it was an edit-mode job that changed files, run a second pass with the
+   `flumecode:document` skill to reconcile the repo wiki (`.flumecode/wiki/`) with
+   the change — bootstrapping it on the first run. The wiki edits are committed in
+   the same PR. A failure here is logged and skipped; it never fails the job.
+5. If files changed: commit, push `checkoutBranch`, open a PR into `mergeBranch`.
+6. Report the summary back (`POST /api/runner/jobs/:id/complete`), which fills in
+   the pending agent comment in the thread.
+
+Jobs come in two kinds. **chat** jobs answer a request thread (the flow above).
+**init** jobs bootstrap a repository: they clone the default branch onto a fresh
+`flumecode/init-*` branch, run the `flumecode:document` skill to create the
+`.flumecode/` wiki, and open a PR. A repo must be initialized (from its dashboard
+in the web app) before requests can be opened against it.
+
+> ⚠️ The runner executes model-generated commands on your machine via
+> `acceptEdits`. Run it only against repos and requests you trust.
+
+## Status reporting
+
+On startup (and every few minutes after) the runner probes your local Claude
+Code with one trivial turn and reports the result to the server
+(`POST /api/runner/heartbeat`). The web **Runners** page shows two states per
+machine: **Connected** (the runner is checking in) and **Claude Code ready**
+(its login works, so the server can dispatch tasks to it). A failed probe shows
+**Claude Code error** with the reason — usually "not logged in" or a missing
+binary.
+
+The runner also reports its own version (`x-flumecode-runner-version` header) on
+every call, so the Runners page can show an **Update available** hint when your
+machine is behind. To update: `npm install -g @flumecode/runner`, then restart
+the runner.
+
+## Troubleshooting
+
+- **"Runner token rejected (401)"** — the token is wrong or was removed. Create a
+  fresh one on the Runners page and re-run `flumecode login`.
+- **Claude Code error on the Runners page** — open a shell and confirm Claude Code
+  works there (`claude` is on your PATH and you're logged in), or that
+  `ANTHROPIC_API_KEY` is exported. The runner uses whatever that shell has.
+- **`flumecode: command not found`** — the global npm bin dir isn't on your PATH,
+  or use `npx @flumecode/runner …` instead of installing globally.
+- **Update available hint** — `npm install -g @flumecode/runner` then restart.