blueclawDevelopment
Development means building and testing the Go daemon and the three TypeScript packages.
go build ./...
go vet ./...
go test ./...
bun install
bun run testprotocol, chatd and admin are one Bun workspace. bun run test at the root typechecks and runs each package in its own process; do not run bare bun test at the root. CI runs these commands with Postgres 16 as a service. After changing a contract in protocol/src, run bun run generate there; bun run generate:check rejects stale artifacts. Zod is the canonical contract, and Go types validate against the generated schemas. A breaking contract change bumps the protocol version. The package defines the shape of a capability descriptor and no tools; a product offers its own catalog to the scenarios through BLUECLAW_SCENARIO_CAPABILITY_CATALOG.
| Tier | Gate |
|---|---|
| Unit | none |
| Postgres-backed | BLUECLAW_TEST_POSTGRES_URL |
| Live model (costs money) | BLUECLAW_LIVE_LLM_TEST=1 |
| External agent | BLUECLAW_TEST_CLAUDE_CODE_PATH, BLUECLAW_TEST_CODEX_PATH, BLUECLAW_TEST_ANTIGRAVITY_PATH, BLUECLAW_TEST_ACP_AGENT_PATH |
| POSIX separation | BLUECLAW_TEST_POSIX_HELPER, BLUECLAW_TEST_POSIX_HELPER_PATH (root and an installed helper) |
| Virtual session | --live-llm or BLUECLAW_E2E_LIVE=1 |
A virtual session drives the agent loop with no VM and writes every request, response, tool call and artifact to a directory:
go run ./cmd/blueclaw-lab virtual-session --scenario presentation \
--artifact-dir .artifacts/blueclaw-e2e --live-llmScenarios are defined in internal/e2e/scenarios.go; --scenario-file loads one from JSON.
The lab
cmd/blueclaw-lab also drives a full rig: an Apple Silicon Mac as the person's computer, a Tart ARM Linux VM, and blueclaw inside a guest that VM boots under Cloud Hypervisor. config/lab.example.json configures it and lab/scripts/ holds provisioning and scenario scripts. The commands are image-build, vm-up, vm-down, vm-ssh, scenario-mattermost, scenario-slack and scenario-browser-handoff. Tart and a hardware-virtualized guest cannot start on a hosted CI runner, so the lab is not exercised by CI.
Screenshots
The terminal client images in the README are generated by ./tools/shoot-tui-screenshots, which builds the client, serves a seeded admin API and renders each screen with headless Chrome. Re-shoot them after changing internal/tui.
AGENTS.md holds the conventions the code follows.