bitfolk 0.1.6 → 0.1.8

package/README.md

@@ -46,8 +46,10 @@ release rather than reuse one it cached. Installed, it also answers to the short
 | `bitfolk agents` | The workspace's agents: tool, builder or not, health, what each is doing |
 | `bitfolk approvals` | What agents wait on you for; `bitfolk approve <id>` and `bitfolk deny <id>` answer one |
 | `bitfolk tools` | The coding tools found here, on or off |
+| `bitfolk repos` | The git repos builders may work in; `repos add <path> [--name <n>]`, `repos rm <name>`, `repos default <name>` |
+| `bitfolk set --primary <tool>` | The tool sessions use while it has usage left (`none` clears it) |
 | `bitfolk add <tool>` / `rm <tool>` | Turn a tool on or off, or add your own with `--command` or `--acp` |
-| `bitfolk set --repo <path>` | Give sessions a git repo; `--max-usd`, `--max-runs`, `--timeout`, `--permission` change limits |
+| `bitfolk set --repo <path>` | Give sessions a git repo; `--pull-requests on` opens pull requests that merge once you approve; `--max-usd`, `--max-runs`, `--timeout`, `--permission` change limits |
 | `bitfolk share <port>` | Share an app running here at a link |
 | `bitfolk check` | Check sign-in, tools and repo (also `bitfolk doctor`) |
 | `bitfolk bug "<what>"` | Report a bug |
@@ -212,6 +214,57 @@ On a Mac, `bitfolk up` keeps the computer awake while it runs (`caffeinate -i`,
 the runner does). The screen can still sleep. Closing the lid on battery still sleeps the Mac and pauses sessions.
 `bitfolk up --let-sleep` turns this off.
 
+## Repos and the primary tool
+
+A computer can offer builders several git repos, each with a short name. Your workspace, its agents and the Run picker
+see the names and GitHub repos, never the paths:
+
+```
+bitfolk repos add ~/code/web           # named web; the first repo is the default
+bitfolk repos add ~/code/api
+bitfolk repos add ~/code/site --name marketing
+bitfolk repos default api
+bitfolk run --in web "fix the signup form"
+```
+
+A session works in the default repo unless it names another: `bitfolk run --in <name>`, the Run picker, an agent's
+`use_computer` request (`params.repo`), or a message asking for builders that names the repo. Only git repos: every
+session gets its own worktree and branch, so your checkouts stay as they are.
+
+Sessions go to the coding tool with usage left. `bitfolk set --primary codex` makes Codex the one to use while it has
+room; when it is out of usage or over 80% of its window, sessions go to the tool with the most left. The runner tells
+your workspace each tool's usage when `bitfolk up` starts, every 10 minutes and after each session:
+
+- Codex: the percent of each window used and when it resets, from its own session logs (`~/.codex/sessions`).
+- Claude Code: what its last run said: a warning near the limit, or "limit reached" with the reset time. It reports
+  nothing while it has room, so it counts as having room until then.
+
+A tool named on purpose always wins: `bitfolk run --runtime claude-code`, a tool picked on the Run picker, an agent's
+`params.tool`, or a message asking for builders that names the tool ("builders, use Codex on api"). Builders and agents
+see each tool's usage left and the repos (`GET /v1/computers`, and a "This computer" section in a builder's packet), so
+they can pass on what someone in the chat asked for.
+
+## Pull requests
+
+With a GitHub repo, builders' work can go up for review and merge into your main branch once you approve it:
+
+```
+bitfolk set --repo ~/code/app --pull-requests on
+```
+
+1. Connect GitHub in Bitfolk under Tools → Connected apps.
+2. When a session succeeds with commits, the runner pushes its `bitfolk/builder-<id>` branch to the repo's GitHub
+   `origin`, with your own git credentials (no prompts, no hooks). Only a GitHub origin is pushed to.
+3. Bitfolk opens a pull request into the branch from `--base` (or origin's default branch, else `main`) through your
+   GitHub connection, and asks you to approve "Merge pull request #N into main" on your phone, the web, Slack or with
+   `bitfolk approve <id>`.
+4. Once a person approves it, Bitfolk merges the pull request within a minute, at the exact commit you were shown. A
+   rule, an approval habit, the Coordinator or an agent's say-so never merges one. If a fix pushes new commits, the
+   earlier approval is retired and you're asked again.
+
+`bitfolk logs <id>` shows the pull request and whether it merged. `--pull-requests off` keeps branches on this
+computer again.
+
 ## Long-lived agents
 
 `bitfolk add bfa_...` still adds a permanent agent with a token copied from its page on your workspace, and `bitfolk up`