Toolbox

A developer harness for coding agents: one git clone on the machine plus a small static Go binary (tb). Skills, persona, and verify recipes live here; each product repo keeps a short pointer, a generated AGENTS.md, and its own docs/ (including ADRs).

Toolbox is not an MCP server, not a daemon, not a marketplace, and not part of any product crate.

Source of truth for v1.7: docs/requirements.md. How it is built: docs/design.md. Recorded forks: docs/adr/. tb init writes toolbox_version = "1.7.0" (v1.6 added skills only, so the stamp skipped from 1.5.0 to 1.7.0).

What it does

• One clone ($TOOLBOX_HOME, default ~/toolbox) shared by every product repo.
• tb init -p <profile> wires a git repo to a named profile.
• tb install symlinks skills into Claude Code and Grok Build (v1's only install targets). Skills are not copied into product repos.
• Works on Arch Linux (x86_64) and macOS Apple Silicon (arm64).

Install

Clone this repo. If it is not at ~/toolbox, set TOOLBOX_HOME to the clone path (must exist and be a directory):

export TOOLBOX_HOME="$HOME/src/toolbox"   # example; skip if you cloned to ~/toolbox

Build the binary for this machine:

make linux    # dist/tb-linux-amd64
# make darwin # dist/tb-darwin-arm64  (cross-compile check, or native on M1)

Put tb on PATH. Example:

ln -sf "$TOOLBOX_HOME/dist/tb-linux-amd64" ~/.local/bin/tb
# on M1: ln -sf "$TOOLBOX_HOME/dist/tb-darwin-arm64" ~/.local/bin/tb

Link skills into the agents on this machine (run after clone and after git pull in $TOOLBOX_HOME):

tb install
tb doctor

tb install creates ~/.claude/skills and ~/.grok/skills if needed and symlinks each $TOOLBOX_HOME/skills/<name> into both. It is idempotent. A real file already at a target is skipped with a warning, not overwritten.

Agent detection (ADR 0004): binary on PATH, or a marker file (~/.claude/settings.json / ~/.grok/config.toml). One missing agent is a warning (exit 0). Neither present is an error (exit 1). Skills are still linked in the error case.

tb does not install or update Claude Code or Grok Build.

Wire a product repo

From inside a git repository:

tb init -p rust-systems   # or -p infra-go, -p back-go, -p game-bevy, -p cpp-systems, -p c-cli

This writes toolbox.toml (the profile pointer), renders AGENTS.md, and creates missing docs/ templates listed by the profile. Existing docs/adr/* files are never touched, including under --force. Skills stay in $TOOLBOX_HOME.

docs/session.md is the session handoff: local working state, not project knowledge. tb init appends it to the repo's .gitignore (creating the file if needed, never rewriting existing lines), so a public repo does not publish it. A .gitignore entry does not untrack a file that is already committed, so if it is, tb init prints a warning naming git rm --cached docs/session.md. tb never modifies the git index itself. Existing repos pick this up with tb init --force.

Re-running tb init on a repo that already has AGENTS.md / toolbox.toml:

	Interactive	Script / non-TTY	--force
Files would change	prompt: merge or refuse	refuse, exit 1, files untouched	refresh AGENTS.md (managed region only) and toolbox.toml
Bytes already match	no prompt; prints unchanged:	same	same

--force never rewrites ADR bodies or other docs/ files that already exist. It does refresh the managed region, including the binding rules and the Skills: line (review is a process skill in every profile).

Commands

Command	Role
tb install	Machine-level: symlink skills into Claude Code and Grok Build
tb init -p NAME [--force]	Wire the current git repo to a profile
tb doctor	Read-only health report (one screen). No --fix
tb skill new NAME	Scaffold $TOOLBOX_HOME/skills/<name>/SKILL.md. Does not attach it to a profile
tb persona show [-p NAME]	Print the persona file and its two section titles

Exit codes: 0 success (including “one agent missing”), 1 operational failure, 2 usage error.

tb doctor only hard-fails when zero agents are detected. Missing skill links and a missing cargo/go/cmake/gcc are warnings.

Profiles (v1.6)

Profile	Use	Extra skills
rust-systems	Systems / low-level Rust, greenfield and legacy	rust-verify, rust-systems
infra-go	Go CLIs, scripts, AWS/infra glue — not long-running HTTP backends	go-verify, infra-go, aws-guard
back-go	Go HTTP services and APIs, greenfield and legacy — not CLIs or one-shot jobs	go-verify, back-go, aws-guard
game-bevy	Bevy games in Rust, greenfield and legacy — not systems crates or non-Bevy engines	rust-verify, game-bevy
cpp-systems	C/C++ built with CMake — ggml-family repos (llama.cpp) and your own C++ projects	cpp-verify, cpp-ggml
c-cli	C programs you own and run — terminal tools, TUIs, exercise runners; not C++ and not upstream ggml	c-verify, c-cli

All six profiles include the process skills spec, adr, onboard, scout, handoff, review. review is the last gate after verify, before ticking a task.

Verify recipes live in rust-verify / go-verify / cpp-verify / c-verify. The agent runs those commands in its own shell. There is no tb verify.

rust-systems:

cargo fmt --check
cargo test
cargo clippy --all-targets -- -D warnings
# cargo miri test  — when the changed crate contains any unsafe

infra-go:

gofmt -l .          # must print nothing
go vet ./...
go test ./...
go test -race ./...

back-go:

gofmt -l .          # must print nothing
go vet ./...
go test ./...
go test -race ./...

game-bevy:

cargo fmt --check
cargo test
cargo clippy --all-targets -- -D warnings
# cargo miri test  — when the changed crate contains any unsafe

cpp-systems:

cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DLLAMA_FATAL_WARNINGS=ON
cmake --build build -j $(nproc)
ctest --test-dir build -L main --output-on-failure --timeout 900
# clang-format the added lines only
# ./build/bin/test-backend-ops  — when the diff touches ggml/

C++ has no universal recipe: cpp-verify says to confirm the flags against the target repo's CI workflows rather than recall them. In a repo you do not own (llama.cpp is the motivating case) do not run tb init — it would append a managed region to that project's tracked AGENTS.md and scaffold toolbox docs into its docs/. tb install has already linked the skills machine-wide; that is enough.

c-cli:

make
make test
# no Makefile yet: gcc -std=c11 -Wall -Wextra -Werror -g -o <bin> <sources>
# memory-touching diff: same line plus -fsanitize=address,undefined
git status --short     # must show no build output

The gcc line is the bootstrap for a repo that has no Makefile yet; adding the Makefile is that repo's first task. Unlike cpp-systems, c-cli is only for repos you own, so tb init -p c-cli is the expected first step.

Skills outside a profile's list (v1.6)

Not every skill belongs to exactly one profile's skills array. tb install symlinks every skill in skills/ into both agents regardless of profile membership, and a skill triggers off its own description independent of which profile a repo declares. Two skills use this directly:

Skill	Use	Pair with
trainer-maker	Building or reviewing a rustlings-style exercise trainer, in any language or subject domain	Your profile's own verify/house-style skill for the toolchain (cpp-cmake-verify, rust-verify, go-verify, ...)
cpp-cmake-verify	Verify recipe for a plain CMake C++ project with no ggml/backend matrix	Nothing extra needed; alternative to cpp-verify for a repo that is not ggml-family

cpp-cmake-verify exists because cpp-verify's worked commands are llama.cpp-shaped (-DLLAMA_FATAL_WARNINGS=ON, test-backend-ops, ci/run.sh) and do not fit a plain CMake C++ repo, even though cpp-systems's own description already claims that audience. Neither new skill is added to profiles/cpp-systems.toml's skills array — attach them to a repo's AGENTS.md Skills:/Verify: lines by hand if you want them documented there, keeping in mind that tb init --force regenerates that managed region from the profile file and will not know about a hand-edit.

Layout

$TOOLBOX_HOME/          # this repo (default ~/toolbox)
  profiles/             # rust-systems.toml, infra-go.toml, back-go.toml,
                        # game-bevy.toml, cpp-systems.toml, c-cli.toml
  personas/default.md
  skills/<name>/SKILL.md
  templates/            # files tb init copies if missing
  cmd/tb/               # Go module for the binary

After tb init, a product repo looks like:

<product>/
  toolbox.toml          # pointer: profile = "..."
  AGENTS.md             # generated managed region; user prose outside the markers is kept
  docs/                 # created if missing; docs/adr/* never overwritten

AGENTS.md is marker-delimited (<!-- toolbox:begin --> … <!-- toolbox:end -->). Hand-edits inside the markers are replaced on the next merge/--force. Content outside the markers is the repo's.

Adding a skill

tb skill new my-skill
# edit $TOOLBOX_HOME/skills/my-skill/SKILL.md
# add "my-skill" to the chosen profiles/<name>.toml skills array
tb install
git -C "$TOOLBOX_HOME" add skills/my-skill profiles && git -C "$TOOLBOX_HOME" commit

tb skill new does not edit any profile. There is no per-repo tb skill add / rm in v1.

Building and testing tb

From this repo:

make all                          # linux/amd64 and darwin/arm64 into dist/
cd cmd/tb && gofmt -l . && go vet ./... && go test ./... && go test -race ./...

CI on cmd/tb/** runs gofmt -l, go vet ./..., and go test ./.... The module is under cmd/tb/ so those tools never walk skills/ or profiles/. tb has no third-party Go dependencies (ADR 0001).

Not in v1.5

MCP, a local daemon, automatic agent memory, extra agents (Cursor, Codex, …), a persona-switch CLI, per-repo skill enable/disable, wrapping verify as tb verify, installing the coding agents themselves, a tb guard against initialising an upstream repo. Sync is git pull in $TOOLBOX_HOME plus tb install.