bitfolk 0.1.7 → 0.1.8

package/README.md

@@ -46,6 +46,8 @@ 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; `--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 |
@@ -212,6 +214,36 @@ 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: