brindle 0.0.2__tar.gz → 0.0.4__tar.gz

{brindle-0.0.2 → brindle-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brindle
-Version: 0.0.2
+Version: 0.0.4
 Summary: Run coding agents in parallel, each on its own git branch, with a supervisor that delegates, reviews, and merges
 Project-URL: Homepage, https://pawdelta.com/brindle/
 Project-URL: Documentation, https://pawdelta.com/brindle/docs/recommended-use
@@ -45,9 +45,9 @@ curl -fsSL pawdelta.com/brindle/install | sh
 brindle demo        # watch it finish a practice repo in a few minutes
 ```
 
-![brindle demo: a supervisor splits a goal between two workers, each branch is reviewed and merged, and both milestones turn green once their checks pass](https://pawdelta.com/brindle/brindle-demo.gif)
+![brindle demo: a supervisor splits a goal between two workers, each branch is reviewed and merged, and both milestones turn green once their checks pass](https://pawdelta.com/brindle/brindle-demo.gif?v=0.0.2)
 
-*`brindle demo`, recorded on brindle 0.14.6 (sped up 4×): two workers in parallel, each branch reviewed and merged, both milestones verified by their check commands.*
+*`brindle demo`, recorded on brindle 0.0.2 (sped up 4×): two workers in parallel, each branch reviewed and merged, both milestones verified by their check commands.*
 
 - **Done means a command passed.** A goal is split into milestones, each with a
   check command that brindle runs itself. A milestone is verified when its check exits
@@ -89,13 +89,9 @@ uv tool install --editable ~/Projects/brindle   # or from a local checkout
 brindle drives Claude Code, so you need that too (`npm install -g @anthropic-ai/claude-code`).
 
 `brindle --version` prints the installed version; the tmux status bar of every brindle
-session shows it too (`brindle 0.11.5`). A session started before an upgrade keeps
+session shows it too (`brindle 0.0.4`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
-### Upgrading from copse
-
-brindle was called copse until 0.0.1, and it doesn't read anything copse saved. Install `brindle`, then move `~/.copse` to `~/.brindle` and each repo's `.copse/` to `.brindle/`. Until you do, saved permission rules, policy and config there don't apply. `brindle doctor` lists every leftover it finds, including old `copse` entries in `.agents/hooks.json` and `mcp_config.json` to remove.
-
 ## Quick start
 
 ```sh
@@ -345,6 +341,7 @@ your own status line prints, so what you see doesn't change.
 | `brindle delegation [conservative\|balanced\|fast]` | how readily the supervisor delegates: fewest tokens, the default, or quickest |
 | `brindle transfer [REPO] [--from SESSION] [-b BRANCH]` | move a scratch session's work into a real repo |
 | `brindle ls [--all]` | workspaces and agents |
+| `brindle repo add PATH [--name ALIAS] / rm ALIAS / ls` | attach other local repos to the current session so workers can go there (brindle Pro; see "Several repos in one session") |
 | `brindle history [--limit N] [--kind K] [--all]` | durable log of worker results, reviews, merges and milestone checks |
 | `brindle history --share [--session ID]` | a few lines about this session to paste into Slack or a post: goal, milestones verified, workers, merges, reviews (and how many by a different model), parallel speedup, tokens |
 | `brindle permissions list / check / suggestions / accept / allow / deny / forget / reset` | the rules brindle answers workers' permission requests with, and what it suggests from your approvals (see "Permission policy") |
@@ -380,6 +377,7 @@ knowing them helps when you tell the supervisor how to work.
 | `send_message` | any agent | message another agent; delivered when it's idle |
 | `read_messages` | supervisor | read the messages agents and brindle sent you and mark them read; with `message_delivery` `"pull"` (the default) you get a one-line "N new messages" notice instead of each message |
 | `list_agents` / `list_tasks` / `list_agent_profiles` | supervisor | who's running, what's queued, which profiles exist |
+| `list_repos` | supervisor | the repos attached to the session (brindle Pro); `repo=<alias>` on `assign`/`handoff` puts a worker there |
 | `cancel_task` | supervisor | cancel a queued task (and its dependents) to re-plan |
 | `workspace_diff` | supervisor | a worker branch's changes against its base |
 | `request_review` / `submit_review` | supervisor / reviewer | start a reviewer on a branch / record its verdict |
@@ -484,7 +482,7 @@ Autopilot, merge gates and cleanup:
 | `sidebar` | `"left"` | where the dashboard sits in each window: `"left"` of the chat, or `"bottom"` (full-width rows under it) |
 | `delegation` | `"balanced"` | how readily the supervisor hands work to workers. `"conservative"` does most work in its own chat (fewest tokens), `"fast"` splits any multi-part request across parallel workers straight away (quickest, most tokens). `brindle delegation fast` saves it for every repo and session (in `~/.brindle/config.json`; `--repo` for this repo only) and tells a running supervisor |
 | `delete_merged_branches` | `true` | removing a worktree (after a merge, `brindle rm`, `brindle prune`, session cleanup) also deletes its branch once every commit is in its base, so finished branches don't pile up. An unmerged branch is always kept; `false` keeps them all. If GitHub keeps merged PR branches, the first `brindle pr` in a repo offers to turn on its automatic deletion with your `gh` login (repo admins only) |
-| `pr_footer` | `true` | `brindle pr` and `brindle ci` end the PR description with one line: "🌲 Built in parallel and verified with brindle" (a link). `false` leaves it out. Never added to commit messages |
+| `pr_footer` | `true` | `brindle pr` ends the PR description with one line: "🌲 Built in parallel and verified with brindle" (a link). `false` leaves it out. Never added to commit messages |
 | `message_delivery` | `"pull"` | how agent and brindle messages reach an interactive supervisor: `"pull"` keeps them unread and delivers one notice ("brindle (16:25:03): 2 new messages (from 9f742c5c, pipeline). Call read_messages."; the time keeps Claude Code from dropping a repeat; the sidebar shows an unread count), `"push"` delivers each message's text. Messages you send (`brindle send`, typing) and messages to workers are always pushed |
 | `learning` | `"auto"` | hosted learning (brindle Pro, via the API; see below): `"auto"` uses it when your plan includes it and nothing otherwise; `"cloud"`; `"off"`. Any other value means off |
 | `learning_candidates` | `[]` | the profile names the hosted learner may pick from |
@@ -672,6 +670,7 @@ how to use them, and the next step to get the rest:
 |---|---|---|
 | hosted learning | Pro | on by itself; `brindle learning` |
 | per-worktree services | Pro | `"services"` in `.brindle/config.json` |
+| several repos in one session | Pro | `brindle repo add <path>` |
 | org policies + audit feed | Team | `brindle account org policy` |
 | Brindle-CI | Team | `brindle ci init` |
 | audit log, air-gap | Enterprise | `brindle audit verify`, `"airgap": true` |
@@ -689,6 +688,21 @@ brindle account org member policy-role <member> <role|none>   # give a member a
 brindle account org company [link <org_id> | unlink]          # link orgs you own into one company; learning is pooled only within it
 ```
 
+### Several repos in one session (brindle Pro)
+
+A session can work across several repos. Attach another local repo you own
+to the running session and the supervisor can put workers there: each gets a
+worktree in that repo, that repo's own checks and review, and merges into that
+repo's branch. A task may depend on one in another repo, a milestone check can
+run in another repo (`check@<alias>: <command>` in `goals.md`, or `repo` in
+`set_goal`), and the sidebar and `brindle ls` group workers by repo.
+
+```sh
+brindle repo add ../pawdelta-web --name web   # attach a repo to the current session (alias: web)
+brindle repo ls                               # the repos attached to this session
+brindle repo rm web                           # detach it (its worktrees and branches stay)
+```
+
 Setting up a team takes no sign-up form:
 
 ```sh
@@ -792,129 +806,61 @@ brindle audit pubkey                               # this install's public key (
 one altered in place (hash or signature), one removed, inserted or reordered
 (seq and prev_hash), or a truncated tail. Verifying and exporting never need
 the entitlement, so a log keeps its value after a plan lapses.
-### Brindle-CI: issues into pull requests
-
-brindle Team can run brindle with nobody at a terminal. `brindle ci run` cuts a
-`brindle/ci-<issue or slug>` branch, starts a supervisor with autopilot on in a
-detached tmux session, gives it the goal, and waits until every milestone's
-check passes. Then it pushes the branch and opens the pull request with `gh`
-(the body lists the goal, the milestones and their checks, and `Closes #N`
-for an issue), prints the PR URL and exits 0; with `--bundle` it writes the
-branch to a file instead, for `brindle ci publish` (see below). It exits 1, with what happened,
-when the supervisor asks for a decision (`need_user`: the question is the
-reason), stalls, or runs out of time. The session and its workers are always
-stopped at the end, and a JSON summary goes to `$GITHUB_STEP_SUMMARY` when
-that is set.
-
-```sh
-brindle ci run --issue 42                      # the goal is the issue's title and body
-brindle ci run --goal "Add a /health endpoint" # or typed; a goals.md-shaped text brings its milestones
-brindle ci run --goal-file .brindle/goals.md --timeout 90 --max-workers 2 --base develop --no-pr
-brindle ci init --label brindle                  # the GitHub Actions workflow (see below)
-
-# The same run in three steps, so no secret worth stealing is near the agents:
-brindle ci entitle --out ent.jwt                                      # uses BRINDLE_PRO_TOKEN, then exits
-brindle ci run --issue 42 --entitlement ent.jwt --bundle out/brindle.bundle   # no CI token, no push token
-brindle ci publish out/brindle.bundle --repo acme/api                   # elsewhere: pushes and opens the PR
-```
 
-With `--issue` and `--goal`, the supervisor derives the milestones and their
-checks itself; a goals.md-shaped goal (`# Goal`, `## Milestone`, `check:`) is
-recorded as written. `--max-workers` sets `max_agents` in the repo's
-`.brindle/config.local.json`.
-
-**Who is trusted with what.** Agents run your repo's code: its tests, its
-scripts, and whatever an issue talks them into. They run as the same user as
-brindle, so treat everything on that machine as theirs to read: environment
-variables, files, git and `gh` settings. brindle does take its tokens out of the
-environment before agents start and pushes from a clean copy of the commits,
-but that only makes theft harder. What actually protects a secret is that it
-isn't on the machine while agents run. So the work can be split:
-
-1. `brindle ci entitle --out FILE` exchanges `BRINDLE_PRO_TOKEN` for the signed,
-   short-lived entitlement and writes it to a file (mode 0600). Run it on a
-   different machine from the agents (the workflow gives it its own job):
-   on hosted runners agents have sudo, and the runner holds every secret of
-   the job they run in. `brindle ci run` reads the file and deletes it before
-   any agent starts.
-2. `brindle ci run --entitlement FILE --bundle PATH` does the work with no CI
-   token and no token that can write to GitHub (`--issue` needs one that can
-   read). When the goal is verified it writes the new commits to PATH as a git
-   bundle, and `PATH.json` with the branch, base, title and body of the pull
-   request. `--bundle` implies `--no-pr`: nothing is pushed.
-3. `brindle ci publish PATH [--repo owner/name]` runs where no agent ever ran,
-   with the token that can push. It verifies the bundle, fetches its one
-   `brindle/ci-…` branch into a fresh bare repo, pushes that branch to
-   `https://github.com/<repo>` (default: `$GITHUB_REPOSITORY`) and opens the
-   pull request with `gh`. It never checks out or runs repo code, hooks or
-   agents, and it refuses a bundle whose branch isn't a `brindle/ci-` branch, so
-   a run can't publish over `main`. The pull request targets `--base`, else
-   the repository's default branch; the bundle doesn't get to choose. A
-   hostile run can still add commits to an existing `brindle/ci-` branch.
-
-The workflow `brindle ci init` writes pins brindle to the version that wrote it,
-since the publishing job holds a write token. The short-lived entitlement
-passes between jobs as an artifact kept one day. A CI entitlement expires
-three hours after it's issued, so anyone who can download the repo's
-artifacts could use it for that long at most.
-
-`brindle ci run` without `--bundle` still pushes and opens the pull request
-itself. Use that only where you trust the repo's code and everyone who can
-steer the agents.
-
-`brindle ci init` writes `.github/workflows/brindle.yml`, which runs on
-`workflow_dispatch` and whenever an issue gets the label (`brindle` by
-default). It has three jobs:
-
-- `entitle` (no permissions) runs `brindle ci entitle` with `BRINDLE_PRO_TOKEN`
-  on a machine that checks out and runs nothing from the repo. It hands the
-  short-lived entitlement (three hours) to the next job as an artifact kept
-  one day, so the CI token is never on the agents' machine.
-- `run` (permissions: `contents: read`, `issues: read`) checks the repo out
-  without keeping credentials, installs tmux, brindle (pinned to the version
-  that wrote the workflow) and Claude Code, then runs `brindle ci run --issue
-  <number> --entitlement … --bundle …` with only `ANTHROPIC_API_KEY` and a
-  read-only `GH_TOKEN`. brindle deletes the entitlement file before any agent
-  starts. The job uploads the bundle as an artifact.
-- `publish` (permissions:
-  `contents: write`, `pull-requests: write`) starts on a fresh machine, checks
-  nothing out, downloads the artifact and runs `brindle ci publish`, targeting
-  the repository's default branch.
-
-`brindle ci init` won't
-overwrite an existing file without `--force`. The workflow needs two secrets,
-`BRINDLE_PRO_TOKEN` (an org CI token, below) and `ANTHROPIC_API_KEY`, and the
-repo's Actions settings must allow GitHub Actions to create pull requests.
-The model API key is the one secret agents must have; give it a spending
-limit.
-
-An org admin creates the CI token; it is shown once, so store it straight away:
-
-```sh
-brindle account org ci-token create "acme/api actions" --org org_...   # prints cpc_... once
-gh secret set BRINDLE_PRO_TOKEN                                         # paste it
-brindle account org ci-token list --org org_...                         # names, status, last used; never the secret
-brindle account org ci-token revoke ct_... --org org_...                # CI stops at its next run
+### Brindle-CI
+
+Brindle-CI (brindle Team) brings brindle into your CI: it fixes broken builds,
+turns issues into pull requests whose checks it has verified, and reviews pull
+requests with evidence. It runs on your own CI with your own model keys; the
+hosted control plane decides what each run does and what it reports. The
+workflows call these commands:
+
+- `brindle ci init`: set a repository up in one go (the GitHub App, the secrets,
+  the workflows as a pull request, then a doctor check). Run it inside a
+  checkout of the repository. For Claude it asks whether to use an API key
+  (the `ANTHROPIC_API_KEY` secret) or Anthropic
+  [workload identity federation](https://platform.claude.com/docs/en/manage-claude/wif-reference)
+  (`--credential key|federation` answers without asking).
+- `brindle ci doctor`: which provider CLIs and credential names a runner has, and
+  which providers CI may use on this repository.
+- `brindle ci start`: start a run for an issue, a goal text or a dispatched run,
+  or a validation of a pull request.
+- `brindle ci run`: run what was started: the supervisor and the result upload,
+  or the pull request's checks and reviews and the evidence upload.
+- `brindle ci report`: tell the service how the workflow's jobs ended.
+
+Credential names are reported, never values. On a repository owned by a GitHub
+organization, a provider signed in only with a personal subscription is not used.
+
+An Anthropic API key is either a workspace key (scoped to one workspace) or an
+organization-level key (not scoped to a workspace). An organization-level key
+needs the workspace in every request, so after the key `brindle ci init` asks for
+its workspace ID (`wrkspc_...`; leave it blank for a workspace key, or pass
+`--workspace-id`, default `$ANTHROPIC_WORKSPACE_ID`) and stores it as the Actions
+variable `ANTHROPIC_WORKSPACE_ID`. The workflow then sets
+`ANTHROPIC_CUSTOM_HEADERS="anthropic-workspace-id: <id>"`, which reaches every
+Claude Code process the run starts.
+
+With identity federation the repository stores no Anthropic key: the workflow
+exchanges GitHub's OIDC token once for a short-lived Anthropic token, as a
+Claude Console service account (billed as API, so it is allowed on
+organization repositories), and gives the job `ANTHROPIC_AUTH_TOKEN`. `brindle
+ci init` stores the rule, organization, service account and optional workspace
+IDs as the Actions variables `ANTHROPIC_FEDERATION_RULE_ID`,
+`ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` and
+`ANTHROPIC_WORKSPACE_ID`. Create the federation rule in the Claude Console with
+subject prefix `repo:<owner>/<name>:*`, the condition
+
+```text
+claims.repository == "<owner>/<name>" && claims.workflow_ref.startsWith("<owner>/<name>/.github/workflows/brindle-ci-")
 ```
 
-On every run the token is presented to the backend, which checks it and the
-org's live plan and returns a signed entitlement. `brindle ci run` verifies it in
-memory and writes nothing to disk; `brindle ci entitle` writes only the signed
-entitlement, which expires soon, never the token. The token doesn't rotate, so one secret
-keeps working until it is revoked or the org's plan no longer includes CI. A
-refresh token from `brindle account login` won't do: it rotates on use.
-
-Two things to know before you add the label to your repo:
-
-- **Who can apply the label.** The issue body steers an unattended agent
-  whose work becomes a pull request on a `brindle/ci-` branch. Only people you
-  trust with write access should be able to apply the trigger label; on a
-  public repo, anyone who can write the issue text is choosing what the agent
-  is told to do. Review the pull request like any other before merging it.
-- **CI on the pull request.** A PR opened with the workflow's own
-  `GITHUB_TOKEN` doesn't trigger the repo's other workflows. If you want your
-  checks to run on brindle's PRs, set `GH_TOKEN` in the `publish` job to a
-  GitHub App installation token or a personal access token instead.
+audience `https://api.anthropic.com`, and a token lifetime of at least 7200
+seconds. The condition lets only brindle's workflows mint tokens. On pull
+requests the pull request's own copy of the validate workflow runs, so give
+write access only to people you trust (forks never get a token). Leave the `ANTHROPIC_API_KEY` secret
+unset: a key takes precedence (brindle drops an empty one before Claude Code
+starts).
 
 **Closing and cleaning up.** Press `x` on an agent in the sidebar (twice for one
 that's still running) or run `brindle close <id>` to stop it and hide it. Stopping means
@@ -1056,14 +1002,34 @@ change files under a directory without prompts.
 brindle only offers a profile whose CLI is installed and signed in. A profile on a
 CLI that isn't signed in is left out of the supervisor's profile list and of
 routing by weight, and naming it directly stops with how to sign in
-(`claude auth login`, `codex login`) instead of opening the CLI's login screen.
-`brindle doctor` shows each CLI's sign-in. Keys set in the environment
-(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY` and the like) count as signed in.
-`agy` has no sign-in status command, so brindle can't tell when it's signed out:
-sign in once by running `agy` yourself. A worker that no hook reports on (Codex)
+(`claude auth login`, `codex login`, running `agy`) instead of opening the CLI's
+login screen. `brindle doctor` shows, for each installed CLI, how it's signed in
+and whether a quota limit is in effect. Sign-in is its own login, an environment
+key (by name, never its value) set in your shell or in a profile's
+`env.NAME: value` lines, signed out, or unknown when the status check gives no
+answer. Keys set in the environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+`GEMINI_API_KEY` and the like) count as signed in; see the table below for what
+each CLI takes. A worker that no hook reports on (Codex)
 and that shows nothing new for 10 minutes without reporting, for example because
 it's signed in without a plan that includes it, is reported to its supervisor.
 
+#### Key login
+
+| Provider | Key login (environment variables) |
+|---|---|
+| `claude` | yes: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, or Bedrock/Vertex/Foundry (`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`) |
+| `codex` | yes: `OPENAI_API_KEY`, `CODEX_API_KEY` |
+| `antigravity` | `GEMINI_API_KEY`, only with `"modelProvider": "gemini"` in `agy`'s `settings.json` (see [Google Antigravity](#google-antigravity)); otherwise `agy`'s own browser sign-in |
+
+Workers that run unattended should use key login where the CLI supports it.
+A personal login is one interactive session with one quota shared by every
+worker: when it expires or its quota runs out, every worker on it stalls until
+someone signs in again in a browser. A key gives workers their own limits and
+needs no browser step. Put the key in your environment, or in a profile's
+`env.NAME: value` lines in `~/.brindle/agents` (never in the repo), and
+`brindle doctor` names the variable each CLI gets, from your shell or from
+which profiles.
+
 ### Cheap workers
 
 By default a Claude Code worker loads everything your own `claude` does: your
@@ -1298,6 +1264,15 @@ curl -fsSL https://antigravity.google/cli/install.sh | bash
 agy        # sign in with your Google account, then quit
 ```
 
+To run unattended workers without a browser login, `agy` (1.1.13 or newer) can use
+a Gemini API key instead: put `"modelProvider": "gemini"` in
+`~/.gemini/antigravity-cli/settings.json` and set `GEMINI_API_KEY`, in your
+environment or in a profile's `env.GEMINI_API_KEY: ...` line (keep the key out of
+the repo). The key alone does nothing: without `modelProvider`, `agy` still asks
+you to sign in. `agy` takes no other key or token from the environment; its
+Google Cloud, Workforce Identity and Application Default Credentials sign-ins are
+chosen on its sign-in screen.
+
 Then run the whole session on it with `brindle --provider antigravity`, or mix models:
 give a profile `provider: antigravity` (for example a `gemini-reviewer` for a second
 model's review) and the supervisor can hand it tasks.