oakridge

Multi-agent workspace built on jig (separate repo, agent kit), kbbl (operator surface for CLI coding agents), and oakridge-core (workflow orchestration that can delegate agent execution to kbbl).

Layout

oakridge/
├── kbbl/                  # operator surface for CLI coding agents
├── lbc-dashboard/         # read-only dashboard for legit-biz-club study runs
├── oakridge-core/         # workflow substrate with kbbl delegated execution
├── legit-biz-club/        # workspace layer (v1, complete)
├── docs/                  # reference documentation
└── phase0/                # archived: legacy multi-agent proof-of-concept (not active)

Sub-packages

• kbbl — the operator surface. Drives one or more CLI coding agents (claude-code by default, codex opt-in) from a tablet- or phone-friendly PWA over Tailscale. Standalone; works without the workflow layer. See kbbl/README.md.
• lbc-dashboard — read-only dashboard for legit-biz-club study runs. Bun + Hono + React + Tailwind. Reads .run/ sidecars written by legit-biz-club. See lbc-dashboard/README.md.
• oakridge-core — the workflow substrate. Its bundled delegated_session stage starts and controls kbbl sessions for workflow runs while preserving direct kbbl session launching. See oakridge-core/README.md.
• legit-biz-club — the workspace layer (multi-agent collaboration over a shared artifact). v1 build complete — all five phases (foundation, incremental coordination, convergence, evals + memory commit, study harness) shipped on main. Python library; no CLI. See legit-biz-club/README.md.
• phase0 — archived legacy reference material. An early proof-of-concept multi-agent experiment; not an active write surface. Kept for historical reference only.

Quick start

For the operator surface (Claude Code sessions over Tailscale):

bun install
./kbbl/scripts/kbbl-start /path/to/your/repo

Defaults to 127.0.0.1:8788. See kbbl/README.md for tablet/phone exposure, dev mode, compaction config, and security posture.

For Oakridge v2 workflow-driven sessions, start the complete local stack from the repository root:

bun run oakridge

Open http://127.0.0.1:8788/#oakridge. The launcher builds the kbbl PWA, starts kbbl and oakridge-core with their integration configured, and stops both when you press Ctrl-C. The bundled multi-repository dev-flow definition is seeded automatically; choose New Run, select dev-flow v3, add the repositories the brief spans, enter the brief, and start the run.

To run the services separately for debugging:

# Terminal 1
OAKRIDGE_CORE_BASE_URL=http://127.0.0.1:8790 \
  ./kbbl/scripts/kbbl-start /path/to/your/repo

# Terminal 2
cd oakridge-core
KBBL_API_BASE_URL=http://127.0.0.1:8788 \
cargo run

When starting them separately, also set OAKRIDGE_CORE_BASE_URL=http://127.0.0.1:8790 on the kbbl process to enable the Oakridge PWA. oakridge-core reads the kbbl base URL from KBBL_API_BASE_URL.

The combined launcher requires Bash 4.3 or newer because it supervises both services with wait -n. Set OAKRIDGE_CORE_BIND and OAKRIDGE_CORE_PORT to change the local core listener; the launcher derives kbbl's core URL from those same values.

For the full Oakridge v2 runtime-delegation operator guide, including both interactive delegated_session and headless delegated_lbc_run examples, see docs/oakridge-v2-runbook.md.

Development

bun install                # installs deps across all sub-packages
bun run typecheck          # typecheck across the repo

Agent-context files

Per-package CLAUDE.md and AGENTS.md are generated by catagents from sources under .catagents/. Each source emits both basenames at the mirrored path (default --target=both), so Claude Code, Codex, and any other tool that reads either filename get the same conventions. Outputs may include tool-specific naming where a standard references concrete tool calls.

Setup once per machine: clone catagents as a sibling of this repo (so that ../catagents/ from this repo's root resolves to the catagents checkout). The .catagents/standards symlink in this repo is relative (../../catagents/standards); if your layout differs, re-point it.

catagents              # rebuild every <pkg>/{CLAUDE,AGENTS}.md
catagents --check      # diff against committed outputs (exit 2 on drift; intended for CI)

Both .catagents/ sources and the generated <pkg>/{CLAUDE,AGENTS}.md files are committed.

Trajectory

The architectural direction (multi-agent collaboration over a shared artifact, runtime-agnostic operator surface, jig as the agent substrate) lives in internal architecture memos that are not currently checked in. Stable operator guidance and follow-up notes live under docs/.