### First-Time Project Setup with Bun

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/README.md

Guides through the initial setup of the Brenner Bot project. This includes cloning the repository, installing dependencies using Bun, verifying the toolchain, and running initial tests to confirm the environment is correctly configured.

```bash
# Clone the repository
git clone git@github.com:Dicklesworthstone/brenner_bot.git
cd brenner_bot

# Install dependencies
cd apps/web && bun install && cd ../..

# Verify toolchain
./brenner.ts doctor --skip-ntm --skip-cass --skip-cm

# Run tests to confirm everything works
cd apps/web && bun run test
```

--------------------------------

### Example: Quick Start with Preset Roster

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_start_command_v0.1.md

A basic example of starting a cockpit using a predefined roster preset.

```bash
brenner cockpit start \
  --thread-id RS-20251231-rrp-perf \
  --roster-preset default-3-agent \
  --excerpt-file excerpts/rrp-perf.md \
  --question "Does RRP improve decoder latency without quality loss?"
```

--------------------------------

### Install Dependencies and Run Dev Server

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/apps/web/README.md

Navigate to the web app directory, install dependencies using Bun, and start the development server. Open http://localhost:3000 in your browser.

```bash
cd apps/web
bun install --save-text-lockfile
bun run dev
```

--------------------------------

### Install and Run Web App Dependencies

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/AGENTS.md

Use these commands to install dependencies and start the development server for the web application. Ensure you are in the `apps/web` directory.

```bash
cd apps/web
bun install           # Install dependencies
bun run dev           # Dev server
bun run build         # Production build
bun run lint          # ESLint check
bun run lint:ox       # Oxlint check (faster)
```

--------------------------------

### Install and Run Web App Locally

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/README.md

Navigate to the web app directory, install dependencies, and start the development server. This is used for browsing primary docs and composing kickoff prompts.

```bash
cd apps/web
bun install
bun run dev
```

--------------------------------

### Brenner Bot Session Start Examples

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/README.md

Examples of starting a Brenner Bot session, including specifying project key, sender, recipients, and thread ID. The first example uses a specific format for research sessions, while the second uses a bead ID for engineering work.

```bash
./brenner.ts session start --project-key "$PWD" --sender GreenCastle --to BlueMountain,RedForest \
  --thread-id brenner_bot-5so.3.4.2 --excerpt-file excerpt.md --question "What is the core problem?"
```

```bash
./brenner.ts session start --project-key "$PWD" --sender GreenCastle --to BlueMountain,RedForest \
  --thread-id RS-20251230-cell-fate --excerpt-file excerpt.md --question "How do cells determine position?"
```

--------------------------------

### Example: Unified Mode with No Role Separation

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_start_command_v0.1.md

This example starts a cockpit in unified mode, where all agents receive the same prompt, without explicit role mapping.

```bash
brenner cockpit start \
  --thread-id RS-20251231-simple \
  --to BlueLake,RedForest \
  --unified \
  --excerpt-file excerpt.md
```

--------------------------------

### Full Orchestration Mode

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_start_command_v0.1.md

This example showcases the full orchestration capabilities of `brenner cockpit start`, including spawning an ntm session, sending kickoff messages, and broadcasting a notification to all agent panes.

```bash
brenner cockpit start \
  --thread-id RS-20251231-cell-fate \
  --roster-preset default-3-agent \
  --excerpt-file excerpt.md \
  --question "..." \
  --spawn \
  --broadcast
```

--------------------------------

### Cass Memory System Onboarding

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/AGENTS.md

Use the `cm onboard` command to guide the analysis of historical agent sessions and extract valuable rules for the playbook. Start by checking status and sampling sessions.

```bash
# 1. Check status and see recommendations
cm onboard status
```

```bash
# 2. Get sessions to analyze (filtered by gaps in your playbook)
cm onboard sample --fill-gaps
```

```bash
# 3. Read a session with rich context
cm onboard read /path/to/session.jsonl --template
```

```bash
# 4. Add extracted rules (one at a time or batch)
cm playbook add "Your rule content" --category "debugging"
# Or batch add:
cm playbook add --file rules.json
```

```bash
# 5. Mark session as processed
cm onboard mark-done /path/to/session.jsonl
```

--------------------------------

### Default Mode: Kickoff Only

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_start_command_v0.1.md

This example demonstrates the default behavior of `brenner cockpit start` which focuses solely on composing and sending role-specific kickoff messages without spawning an ntm session or broadcasting.

```bash
brenner cockpit start \
  --thread-id RS-20251231-cell-fate \
  --role-map "BlueLake=hypothesis_generator,PurpleMountain=test_designer,GreenValley=adversarial_critic" \
  --excerpt-file excerpt.md \
  --question "How does protein folding relate to cell fate decisions?"
```

--------------------------------

### View Latest Install Session Log

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/AGENTS.md

Tail the log of the latest installation session to check for issues.

```bash
ubs sessions --entries 1
```

--------------------------------

### Full Experiment Loop Example

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_runbook_v0.1.md

A comprehensive example demonstrating the complete experiment workflow from setting context to publishing the final artifact. Includes running, finding results, posting, compiling, and publishing.

```bash
# 0) Set workspace context
export PROJECT_KEY="$PWD"
export THREAD_ID="RS-20251230-cell-fate"

# 1) Run the experiment (capture)
./brenner.ts experiment run \
  --thread-id "$THREAD_ID" \
  --test-id T1 \
  --timeout 300 \
  -- python test_rrp.py --variant knockout

# 2) Find the result file
RESULT_FILE=$(ls -t artifacts/$THREAD_ID/experiments/T1/*.json | head -1)
echo "Result: $RESULT_FILE"

# 3) Post to thread (encode + send)
./brenner.ts experiment post \
  --result-file "$RESULT_FILE" \
  --project-key "$PROJECT_KEY" \
  --sender Operator \
  --to BlueLake,PurpleMountain,RedForest

# 4) Compile updated artifact
./brenner.ts session compile \
  --project-key "$PROJECT_KEY" \
  --thread-id "$THREAD_ID" \
  > artifact_v2.md

# 5) Publish to thread
./brenner.ts session publish \
  --project-key "$PROJECT_KEY" \
  --thread-id "$THREAD_ID" \
  --sender Operator \
  --to BlueLake,PurpleMountain,RedForest
```

--------------------------------

### Starting the Development Server with Bun

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/README.md

Launches the development server for the web application using Bun. After starting, the application can be accessed at `http://localhost:3000`. This command is used for local development and testing changes.

```bash
cd apps/web
bun run dev
# Open http://localhost:3000
```

--------------------------------

### Start Unified Session Kickoff (CLI)

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/README.md

Initiates a multi-agent session where all agents receive the same prompt using the CLI. Suitable for simpler scenarios.

```bash
brenner session start \
  --project-key "$PWD" \
  --thread-id RS20251230 \
  --sender GreenCastle \
  --to BlueLake,PurpleMountain,GreenValley \
  --unified \
  --excerpt-file excerpt.md \
  --question "How do cells determine their position in a developing embryo?"
```

--------------------------------

### Start Local Agent Mail Server

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_runbook_v0.1.md

If Agent Mail is not running, use this command to start a local instance. Ensure you adjust the path to your Agent Mail installation. This script requires bash.

```bash
cd /data/projects/mcp_agent_mail
bash scripts/run_server_with_token.sh
```

--------------------------------

### Brenner Bot Multi-Agent Session Setup

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/README.md

Commands to set up and start a multi-agent session using Brenner Bot and ntm. This includes setting environment variables, composing a kickoff prompt, and starting the session with role mapping.

```bash
export THREAD_ID="RS-20251230-cell-fate"
```

```bash
./brenner.ts mail agents --project-key "$PWD"
```

```bash
ntm new $THREAD_ID --layout=3-agent
```

```bash
./brenner.ts prompt compose \
  --template metaprompt_by_gpt_52.md \
  --excerpt-file excerpt.md \
  > kickoff.md
```

```bash
./brenner.ts session start \
  --project-key "$PWD" \
  --thread-id $THREAD_ID \
  --sender GreenCastle \
  --to BlueLake,PurpleMountain,GreenValley \
  --role-map "BlueLake=hypothesis_generator,PurpleMountain=test_designer,GreenValley=adversarial_critic" \
  --excerpt-file excerpt.md \
  --question "How do cells determine their position in a developing embryo?"
```

```bash
./brenner.ts session start \
  --project-key "$PWD" \
  --thread-id $THREAD_ID \
  --sender GreenCastle \
  --to BlueLake,PurpleMountain,GreenValley \
  --unified \
  --excerpt-file excerpt.md \
  --question "How do cells determine their position in a developing embryo?"
```

```bash
ntm broadcast $THREAD_ID "Please check your Agent Mail inbox"
```

--------------------------------

### CLI: Using a Preset

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/agent_roster_schema_v0.1.md

Start a session using a predefined agent preset via the CLI.

```bash
# Using a preset
brenner session start --preset default-3-agent \
  --to BlueLake --to PurpleMountain --to GreenValley
```

--------------------------------

### Example Evidence Pack File Paths

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/evidence_pack_v0.1.md

Illustrates concrete examples of evidence pack file paths based on the defined storage convention.

```bash
artifacts/RS-20251230-cell-fate/evidence.json
```

```bash
artifacts/brenner_bot-5so.10.2.2/evidence.json
```

--------------------------------

### Dry-Run Output Simulation

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_start_command_v0.1.md

This is an example of the output you would see when running the brenner cockpit start command with the --dry-run flag.

```text
DRY RUN: cockpit start

Would execute:
  1. ntm spawn RS-20251231-cell-fate --cc=1 --cod=1 --gmi=1
  2. Send kickoff to BlueLake (hypothesis_generator)
  3. Send kickoff to PurpleMountain (test_designer)
  4. Send kickoff to GreenValley (adversarial_critic)
  5. ntm send RS-20251231-cell-fate --all "Please check your Agent Mail inbox..."

Roster:
  BlueLake        → hypothesis_generator (codex-cli)
  PurpleMountain  → test_designer (claude-code)
  GreenValley     → adversarial_critic (gemini-cli)
```

--------------------------------

### Example: Dry Run to Preview Orchestration

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_start_command_v0.1.md

Use this command to preview the orchestration plan using a roster file, without executing any commands.

```bash
brenner cockpit start \
  --thread-id RS-20251231-rrp-perf \
  --roster-file roster.json \
  --excerpt-file excerpt.md \
  --spawn --broadcast \
  --dry-run
```

--------------------------------

### Config File: Default 3-Agent Setup

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/agent_roster_schema_v0.1.md

Example configuration file (`brenner.config.ts`) defining a preset named 'default-3-agent' with specific roles, programs, and models.

```typescript
// brenner.config.ts
export default {
  roster: {
    presets: [
      {
        id: "default-3-agent",
        name: "Default 3-Agent Setup",
        description: "Standard Brenner Protocol with Codex/Opus/Gemini",
        entries: [
          { role: "hypothesis_generator", program: "codex-cli", model: "GPT-5.2" },
          { role: "test_designer", program: "claude-code", model: "Opus 4.5" },
          { role: "adversarial_critic", program: "gemini-cli", model: "Gemini 3" },
        ],
      },
    ],
    defaultPreset: "default-3-agent",
  },
};
```

--------------------------------

### Pinned Upgrade Example (macOS/Linux)

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/bootstrap_troubleshooting_v0.1.md

This script downloads and executes the installer for a specific version of Brenner Bot on macOS and Linux. Ensure you set the desired VERSION before running.

```bash
export VERSION="0.1.0" # example
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/brenner_bot/v${VERSION}/install.sh" \
  | bash -s -- --version "${VERSION}" --easy-mode --verify
```

--------------------------------

### Start Role-Separated Session Kickoff (CLI)

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/README.md

Initiates a multi-agent session with role-specific prompts using the CLI. Recommended for complex interactions.

```bash
brenner session start \
  --project-key "$PWD" \
  --thread-id RS20251230 \
  --sender GreenCastle \
  --to BlueLake,PurpleMountain,GreenValley \
  --role-map "BlueLake=hypothesis_generator,PurpleMountain=test_designer,GreenValley=adversarial_critic" \
  --excerpt-file excerpt.md \
  --question "How do cells determine their position in a developing embryo?"
```

--------------------------------

### Macro Start Session

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/agent_mail_contracts_v0.1.md

Initiates a project session, including ensuring the project exists, registering an agent, and optionally reserving file paths.

```APIDOC
## POST tools/call macro_start_session

### Description
Boot a project session (ensure_project + register_agent + optional reservations).

### Method
POST

### Endpoint
tools/call

### Parameters
#### Request Body
- **method** (string) - Required - The method to call, should be "tools/call".
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - The name of the tool, should be "macro_start_session".
  - **arguments** (object) - Required - Arguments for the macro_start_session tool.
    - **project_key** (string) - Yes - Absolute path to the project.
    - **agent_name** (string) - Yes - The name of the agent to register.
    - **program** (string) - Yes - The program or context for the session (e.g., "claude-code").
    - **model** (string) - Yes - The model to use for the session (e.g., "opus-4.5").
    - **task_description** (string) - Yes - A description of the task for the session.
    - **reserve_paths** (string[]) - No - An array of glob patterns for file paths to reserve.

### Request Example
```json
{
  "method": "tools/call",
  "params": {
    "name": "macro_start_session",
    "arguments": {
      "project_key": "/data/projects/brenner_bot",
      "agent_name": "GreenDog",
      "program": "claude-code",
      "model": "opus-4.5",
      "task_description": "Protocol development",
      "reserve_paths": ["apps/web/src/**"]
    }
  }
}
```
```

--------------------------------

### Check ntm Dependencies

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_runbook_v0.1.md

Run this command to check if all necessary dependencies for ntm, including agent CLIs, are installed. This helps identify missing components before starting agent sessions.

```bash
ntm deps
```

--------------------------------

### Check brenner CLI Upgrade Guidance

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/docs/cli-binary-build.md

Use the `brenner upgrade` command to get information on how to upgrade the installed CLI. This command provides instructions but does not perform the upgrade automatically.

```bash
brenner upgrade
```

```bash
brenner upgrade --version 0.2.0
```

--------------------------------

### Get UBS Help

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/AGENTS.md

Display the full command reference for UBS.

```bash
ubs --help
```

--------------------------------

### Configure Local Development Environment Variables

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/deployment_runbook_v0.1.md

Copy the example environment file and set local development variables for Agent Mail, lab mode, and project defaults.

```bash
# Local Agent Mail
AGENT_MAIL_BASE_URL=http://127.0.0.1:8765
AGENT_MAIL_PATH=/mcp/

# Lab mode with shared secret (no Cloudflare Access locally)
BRENNER_LAB_MODE=1
BRENNER_LAB_SECRET=your-local-dev-secret
BRENNER_TRUST_CF_ACCESS_HEADERS=0

# Defaults
BRENNER_PROJECT_KEY=/data/projects/brenner_bot
AGENT_NAME=GreenCastle
```

--------------------------------

### Example: Full Orchestration with Explicit Roster

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_start_command_v0.1.md

This command initiates full orchestration with a custom roster map, enabling spawn and broadcast features.

```bash
brenner cockpit start \
  --thread-id RS-20251231-rrp-perf \
  --role-map "BlueLake=hypothesis_generator,RedForest=test_designer,GreenValley=adversarial_critic" \
  --excerpt-file excerpts/rrp-perf.md \
  --question "Does RRP improve decoder latency without quality loss?" \
  --spawn --broadcast \
  --ack-required
```

--------------------------------

### Agent Mail Test Server Setup and Usage

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/README.md

Sets up an in-memory Agent Mail server for integration testing. It starts the server, configures the base URL, and provides methods to seed threads and assert message counts. Ensure to reset the server state between tests.

```typescript
import { AgentMailTestServer } from "@/test-utils";

let server: AgentMailTestServer;

beforeAll(async () => {
  server = new AgentMailTestServer();
  await server.start(18765);
  process.env.AGENT_MAIL_BASE_URL = `http://localhost:18765`;
});

afterAll(async () => {
  await server.stop();
});

beforeEach(() => {
  server.reset(); // Clear state between tests
});

it("seeds a thread for testing", () => {
  // seedThread creates projects and agents as needed
  server.seedThread({
    projectKey: "/test/project",
    threadId: "TEST-001",
    messages: [
      { from: "TestAgent", to: ["Recipient"], subject: "Test", body_md: "Hello" },
    ],
  });

  // Inspection methods for assertions
  const messages = server.getMessagesTo("Recipient");
  expect(messages).toHaveLength(1);
  expect(server.getMessagesInThread("TEST-001")).toHaveLength(1);
});
```

--------------------------------

### Quick Install Brenner CLI

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/README.md

Installs the Brenner CLI using a curl script. The `--easy-mode` flag simplifies the installation process, and `--verify` ensures the integrity of the installation.

```bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/brenner_bot/main/install.sh?$(date +%s)" \
  | bash -s -- --easy-mode --verify
```

--------------------------------

### Send Kickoff - Roster Mode (Recommended)

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/cockpit_runbook_v0.1.md

Starts an agent session with explicit role assignments for each recipient using roster mode. This is the recommended approach for production sessions.

```bash
./brenner.ts session start \
  --project-key "$PWD" \
  --thread-id "$THREAD_ID" \
  --sender FuchsiaDog \
  --to BlueLake,PurpleMountain,RedForest \
  --role-map "BlueLake=hypothesis_generator,PurpleMountain=test_designer,RedForest=adversarial_critic" \
  --excerpt-file excerpt.md \
  --ack-required
```

--------------------------------

### URL Encode Project Path Example

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/specs/agent_mail_contracts_v0.1.md

Example demonstrating the required URL encoding for the 'project' query parameter in resource URIs.

```string
/data/projects/brenner_bot → %2Fdata%2Fprojects%2Fbrenner_bot
```

--------------------------------

### Install Bun

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/docs/cli-binary-build.md

Install Bun version 1.1.0 or later using the official installation script. This is a prerequisite for building the brenner CLI.

```bash
curl -fsSL https://bun.sh/install | bash
```

```bash
bun --version
```

--------------------------------

### Install Playwright Browsers and Dependencies

Source: https://github.com/dicklesworthstone/brenner_bot/blob/main/docs/testing-best-practices.md

Install Playwright browsers and their dependencies for E2E testing. This command is useful for troubleshooting Playwright installation issues.

```bash
cd apps/web
bunx playwright install --with-deps chromium
```