@lesscap/baton-cli

The baton CLI: register/run a worker on a machine and manage workspaces/projects/requirements/tasks/sessions against a baton server.

A worker is the thing that actually runs agent sessions: it listens to the server's command stream and, per session, spawns claude in a git worktree.

Install

npm i -g @lesscap/baton-cli

Prerequisite: the machine needs the claude CLI on PATH, already logged in (the worker spawns it to run each turn). Override the path with BATON_CLAUDE_BIN=/path/to/claude if needed.

Run a worker

# 1. cd into the git repo the agent should work in
#    (each session gets its own worktree branched off it)
cd /path/to/your-repo

# 2. register this machine as a worker for a project
baton worker register \
  --url https://baton.fmap.dev/api \
  --project <projectId> \
  --name my-machine \
  --baseBranch main
#    → generates ./.baton.json with server, project, base branch, and worker token

# 3. run the worker daemon (foreground; Ctrl-C to stop)
baton worker run

The worker authenticates with its own bearer token — no login needed. Once running, it shows up (alive) under the project's workers in the web back-office; new sessions / inbound DingTalk messages are then executed by it.

.baton.json is per-directory local state (gitignored by convention) and is generated by baton worker register; baton init is optional. --baseBranch wins over BATON_BASE_BRANCH, then an existing saved value. If none is set, registration records the repo's current branch, falling back to main.

Before creating each new session worktree, the worker fetches that branch and forks from the updated origin/<branch> ref without moving the source checkout. Repositories without an origin use their local branch. Environments that keep Git credentials in a separate broker can set BATON_GIT_SYNC_BIN to a trusted executable; Baton invokes it as <executable> <repo> <branch>, then verifies the updated remote-tracking ref before creating the worktree. The helper must print the synced commit hash to stdout.

Other commands

baton init | workspace | project | requirement | task | session — run baton <command> --help for details. The back-office management commands hit gated routes; set BATON_USER / BATON_PASS to log in transparently (the worker commands above don't need this).