bitfolk 0.1.7 → 0.1.9

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 |
@@ -55,6 +57,12 @@ release rather than reuse one it cached. Installed, it also answers to the short
 `bitfolk help <command>` shows a command's options. Older forms keep working: `tool add`, `tool rm`, `ls`, `doctor`,
 `set machine`, and `run` with no words (or just an agent's name), which is `up`.
 
+While `bitfolk up` runs on a terminal, a prompt under its status panel takes commands: type `status`, `sessions`,
+`run "<what>"` (queued for this runner), `logs <id>`, `cancel <id>`, `approvals`, `approve <id>`, `chat`, `repos` and
+the like, without `bitfolk` in front. Each runs as `bitfolk <command>` and its output scrolls above the panel. `help`
+lists them, `quit` or Ctrl-C stops `up`. Commands that take over the terminal (`login`) or never end (`--follow`) stay
+for another tab.
+
 On a terminal, waits show a twinkling loader with the time so far, and `bitfolk up` keeps one live line under its log
 (listening, builders working, cost so far). In a pipe, a log file, CI, or with `NO_COLOR`, `--no-color`, `TERM=dumb` or
 `BITFOLK_NO_ANIMATION=1`, it prints plain lines only.
@@ -212,6 +220,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: