@celsoft/coordinator 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (2026-11-10)
+
+First public release.
+
+- One server runs a bus and a web page for Claude Code agents in Herdr: start agents on tracks in your repos, message them, answer their questions, and land their work, from your computer or your phone.
+- Every agent works in a worktree of its own and reaches GitHub only through the bus, which lands its work by a push or a PR as each repo says; Landing Scripts run before, during, and after each landing.
+- Agents plan before they build, publishing plans and other pages as their issue's documents, which the coordinator keeps for good and serves.
+- Profiles kept in your repos set what each repo's agents get: skills from each source (shipped, attached folders, npx skills, marketplace plugins), event handlers, and actions.
+- Runs on macOS and Linux; `npx @celsoft/coordinator init <folder>` makes a coordinator folder.

package/README.md

@@ -0,0 +1,107 @@
+<img src="https://cdn.jsdelivr.net/npm/@celsoft/coordinator/build/client/icon-192.png" alt="" width="96" height="96">
+
+# Coordinator
+
+A bus and a web page for Claude Code agents running in [Herdr](https://herdr.dev).
+You start agents on tracks in your repos, message them, answer their questions, and land their work, from one page on your computer or your phone.
+
+## What you need
+
+- **macOS or Linux** (WSL counts as Linux).
+- **Node 22** or newer.
+- **Claude Code** 2.1.316 or newer, signed in.
+- **Herdr**, running: every agent runs in a Herdr tab.
+- **git** 2.41 or newer.
+- **gh**, the GitHub CLI: it holds each GitHub login's token, and the page signs it in to each login your repos need.
+- **Tailscale** (optional): when it is installed and connected, the page is also served on your tailnet, so your phone reaches it.
+
+`npx coordinator check` in a coordinator folder says what is missing and how to get it.
+
+## Make a coordinator folder
+
+Every coordinator lives in a folder of its own: one pinned version, and its private `.coord` folder.
+
+```sh
+npx @celsoft/coordinator init ~/coordinator
+cd ~/coordinator
+npm start
+```
+
+- `init` installs the coordinator into the folder at exactly its own version, chooses free ports, and checks this machine (`--no-check` skips the check).
+- `--development DIR` names where your repos are (default `~/Development`): clones live in `DIR/repos/<org>/<repo>`, and agents work in `DIR/worktrees/<track>/<org>/<repo>`.
+- `npm start` runs the server in a Herdr tab of its own and prints the page's address.
+- `npm run pair` prints a one-time code; type it on the page to pair that browser.
+
+Several folders can run side by side, each on its own version, ports, and pairing.
+Give each its own development folder, or its own tracks, so their worktrees never meet.
+
+## Every day
+
+Run these inside the folder.
+
+| Command | What it does |
+| --- | --- |
+| `npm start` | Start the server in a Herdr tab of its own. |
+| `npm stop` | Stop it. Agents keep running in Herdr, and the next start picks them up. |
+| `npm restart` | Stop, then start: after an upgrade. |
+| `npm run status` | Whether it runs, its version, its address, and its agents. |
+| `npm run open` | Open the page, with a pairing code; over SSH it only prints the link, so no browser opens on the remote machine. |
+| `npm run pair` | A one-time code for pairing a browser. |
+| `npm run revoke` | Sign out every paired browser. |
+| `npm run logs` | The server's log; `npm run logs -- -f` follows it. |
+| `npm run agent -- <org/repo> <track>` | Start an agent on a track. |
+| `npm run check` | What this machine needs, and how to get it. |
+
+`npx coordinator <command>` does the same inside the folder.
+Outside a coordinator folder, `npx coordinator` would fetch another package of that name, so use the npm scripts, or `npx @celsoft/coordinator`.
+
+## GitHub logins
+
+Settings, GitHub lists the GitHub logins your repos use: each one's SSH key, the name and email its commits carry, and its orgs.
+Add one there, or set an org's login from its panel on the Repos page.
+The page signs gh in with a one-time code, makes a key or uses one in `~/.ssh`, and puts it on the account.
+The server checks each login at start and writes it into every repo of its orgs it keeps, so commits and pushes there, yours too, use the right account.
+For a clone it does not keep, `npx coordinator git apply` inside the clone does the same.
+
+## What is in .coord
+
+`.coord` is readable by you alone, and the server sets it back at every start if anything in it is not.
+
+- **`config.toml`:** what you choose: ports, development folder, your name, Agent plugins, the console, and the throttle. Edit it by hand or in the page's settings.
+- **`state/`:** what the bus records: its Sessions, Messages, issues, and repos, your pairing, and each agent's launch files. Written by the server only.
+- **`logs/`:** what happened, rotated. Safe to delete.
+- **`agents/`:** Agent Types of your own, added to the ones the coordinator ships, or replacing one by its name.
+
+## Your skills
+
+Agents load the coordinator's own skills and nothing of yours, unless you name your plugin folders in the **Agent plugins** setting, separated by commas (`~/my-skills`, for example).
+Agents call you by the **Your name** setting, your account's full name until you set it; your address on the bus is always `user`.
+
+## Upgrading
+
+```sh
+npm install @celsoft/coordinator@<version>
+npm restart
+```
+
+Only that folder changes.
+The first time a new version starts, it upgrades `.coord`'s files and keeps a copy of each as it was, named for its old format, such as `bus.json.format-7.bak`.
+An older version refuses files a newer one upgraded and names those copies; copy one back to go back.
+
+## Moving a folder
+
+Stop the server, move the folder anywhere, and start it again.
+Running agents are told the new place; their skills load from the old one until they are resumed.
+Carried to another machine, the bus keeps its history, issues, and settings, and tells you what stayed behind: running agents' conversations, repos to clone again, branches never pushed, and your pairing.
+
+## What agents can do
+
+Agents are Claude Code sessions with broad permissions in their worktrees: they read and write files and run commands there, in auto mode.
+They reach GitHub only through the bus: it pushes their work or opens its PR with your gh accounts, and they may only read with gh themselves.
+Each one asks you before it builds and before it lands, unless you free its leash.
+Drafting issue titles and track names asks Claude Haiku, on your own Claude account.
+
+## Uninstalling
+
+Stop the server and delete the folder.
+Its agents' worktrees stay in your development folder, its Herdr tabs stay open, and, if Tailscale served the page, `tailscale serve status` shows the port to turn off.