Blackboard

Blackboard turns an engineering task into a reviewed candidate change using your local coding tools. Choose who plans, builds, and reviews; approve the plan; inspect the verification evidence; then decide what reaches your branch.

One task → an approved plan → a reviewed candidate → passing checks → your integration decision.

The primary experience is Delivery. Council proposals and debate remain available for comparison work, and @mentions send a direct task to one named agent. Execution stays on your controller machine; the web board holds the task history, immutable run settings, and evidence.

This is a private-alpha codebase, not a public multi-tenant service. See the product assessment and release gates for implemented changes, verified behavior, and remaining limits.

Why Blackboard

• Cross-vendor by design. Mix Codex, Claude, Antigravity (agy), Grok, DeepSeek, and Meta in the same task instead of locking a workflow to one provider.
• Choose models per agent. Model selection is stored with the task and passed to the corresponding CLI or API adapter.
• Shared, bounded context. Every agent receives the relevant task transcript plus a snapshot of the selected repository, with prompt and board payload limits.
• Isolated writer worktrees. Writing CLI jobs run in dedicated worktrees and candidate branches (blackboard/<run>/<agent>), keeping the primary checkout clean.
• Local execution. Subscription-backed CLIs run on the machine where you are already signed in, so their credentials remain in vendor-owned CLI sessions.
• Durable evidence & review. Runs, responses, failures, changed files, and candidate diffs are recorded on the board with review and controlled integration.
• Human-controlled. You choose the repository, participants, models, and when a run starts or stops, and you review and approve integration into your target branch.

How it works

The board and the agent controller are deliberately separate:

• The web app is the control plane. It stores tasks, shared messages, participants, model selections, runs, and queued jobs in D1.
• The local controller is the execution plane. It claims one job at a time and invokes the selected official CLI or API adapter in an isolated worktree.
• Subscription login tokens remain in each vendor's own CLI/keychain. Blackboard never reads or stores them.
• CLI agents inspect and edit files in dedicated worktrees. API-only agents receive repository context and return recommendations but cannot edit locally.

User task
   ↓
Web board: shared context, participants, models, run history
   ↓
Local controller: claims job → creates isolated worktree
   ↓
CLI agents edit candidate branch · API agents analyze snapshot
   ↓
Candidate diffs return to the board for inspection, review, and integration

Current scope & workflows

Blackboard supports two distinct workflow execution modes selectable from the composer or inspector:

1. Council mode (optional)

Council runs selected agents with worktree isolation in one of two modes: Proposals (default) builds independent proposals in parallel from the frozen run base, then a judge agent recommends exactly one; Debate runs agents sequentially, each building on the previous candidate branch.

• Audience selection: Choose Selected agents in the composer to run the selected participants under Proposals or Debate.
• Direct turns: Tagging an agent (e.g. @claude or @codex) or choosing a direct addressee sends a direct turn to that agent only, outside the council round loop.
• Round progression: After a completed council round, Start next round continues the discussion without requiring a new user message.

2. Delivery workflow (default: Plan → Build → Review → Verify → Integrate)

Delivery is a structured pipeline that coordinates specialized models across sequential phases:

• Planner (Scope & Plan): Analyzes task requirements with read-only repository access and produces a bounded plan artifact.
• Plan approval: The build waits for your approval. Edit the proposed plan or stop the run before work starts.
• Implementer (Workspace Build): Receives the approved plan and applies targeted edits inside a dedicated worktree on a candidate branch (blackboard/<run>/<agent>).
• Reviewer (Independent Review): Inspects the candidate diff with read-only context and renders a review verdict (approved or changes_requested).
• Fix cycles: A reviewer requesting changes triggers a bounded fix and re-review cycle (maximum two). The timeline follows the latest candidate and review.
• Stage timeline: Shows all five stages and distinguishes pending approval, execution, failed checks, and completed integration. The inspector and approval controls are accessible on mobile.
• Verification: Configure 1–6 single-line commands in the inspector (default npm test). They are snapshotted with the run and execute in order on the candidate after review, with a 60-second timeout per command. Include dependency setup when the worktree needs it. The report exposes the command, exit code, output, and exact candidate tree. Commands must finish with an explicit pass and exit code zero.
• Gated integration: Only the latest candidate with an approved review and passing checks can be integrated. Review the diff, then explicitly choose Integrate. Conflicts preserve the candidate for inspection.

Reusable skills

Blackboard supports reusable instruction bundles ("skills") that provide domain-specific guidance, conventions, or review criteria to participating agents.

• Create and manage skills: Open the inspector to create, edit, or delete custom skills. Each skill includes a name (up to 80 characters), an optional description (up to 280 characters), and instructions (up to 12,000 characters).
• Built-in Subagents skill: Blackboard includes a seeded "Subagents" system skill labeled Built in. Built-in skills cannot be edited or deleted.
• Subagents policy: When active, the Subagents skill enables provider-native subagent delegation under strict policy constraints:
  • Up to 2 subagents per job.
  • Single nesting level (subagents cannot spawn further subagents).
  • Research/test/review only (no file writing or implementation delegation).
  • Parent remains sole writer (the parent agent synthesizes subagent evidence and performs all file edits).
• Provider compatibility:
  • Supported: Codex, Claude, and Grok CLI adapters support provider-native subagent delegation.
  • Unavailable: Antigravity, DeepSeek, and Meta do not support native subagents in this harness.
  • Controller offline: Compatibility probes require an active local controller connection.
• Compatibility warnings: If selected participants include unsupported providers while Subagents is active, the UI displays a clear warning noting which agents will run directly without subagents, without silently removing the skill from the thread.
• Per-thread selection & limits: Attach up to 8 active skills to any thread. Selections are preserved when creating new tasks. Skill selections and edits are disabled while a run is in progress. When no skills are selected, no skills section is injected into agent prompts.
• Snapshot semantics: When a run starts (via direct message or council round), the active skill contents are snapshotted onto each queued job. Editing or deleting a skill later will not change in-progress or completed runs.
• Prompt precedence and limits: Selected skills are injected before the shared transcript and work log with explicit precedence below safety, repository, tool, and approval boundaries. The combined injected skills section is capped at 16,000 characters.
• Cross-vendor parity: Both CLI and API agents receive the same selected skill instructions in their prompt context.
• Composer & inspector access: Skills can be selected and inspected via the desktop inspector panel and the compact composer picker (available on viewports below 900px).

Start locally

Option 1: Run with npx (Recommended)

Requires Node.js 22.13 or newer. Run directly inside any git repository:

npx blackboard-web

Or install globally:

npm install -g blackboard-web
blackboard

Options:

• -p, --port <port>: Port to run the web board on (default: 3737, or auto-increments if busy)
• -C, --project <dir>: Path to git repository (default: current working directory)
• --password <pass>: Board UI password (auto-generated and saved to ~/.blackboard/board-password on first run)
• --check: Verify local CLI and API provider availability and exit
• --once: Process one queued job and exit
• --no-open: Do not automatically open the browser
• --concurrency <count>: Max concurrent agent jobs (default: 2)

Option 2: Run from source (Development)

Requires Node.js 22.13 or newer.

npm install
cp .env.local.example .env.local
cp .env.controller.example .env.controller
npm run dev

In a second terminal, from this repo or with BLACKBOARD_PROJECT_ROOT pointed at another git checkout:

npm run controller:check
npm run controller

Direct product access: users directly access the product via the CLI (npx blackboard-web) or local dev server (npm run dev). Authentication is kept hidden/inactive as of now, opening directly into the workspace with no login or landing page gate. Open http://localhost:3737, use the first-task checklist to choose a repository, agents, models, and verification commands. Choose a task template or describe your own task in the composer. The default Delivery workflow pauses for plan approval before building. The composer audience is authoritative: Selected agents starts the selected workflow; choosing or tagging named agents queues a direct turn for those agents only. After a completed council round, Start next round continues from the existing transcript without requiring another message. Each agent receives the bounded shared transcript plus git status, recent commits, and the tracked file list before working in the checkout.

Website & Landing Page

The Blackboard marketing and documentation website is completely decoupled from the local product harness and lives under the site/ directory (similar to Loreforge). It is built with clean static HTML5, CSS3, and progressive JavaScript enhancements with zero runtime framework dependencies, designed for direct deployment to Vercel.

To preview the website locally:

npm run site:dev
# or: python3 -m http.server 4173 --directory site

Open http://localhost:4173. To deploy to Vercel, point the Vercel project's Root Directory setting to site.

Project root

Pick the git checkout from the board. The repository control is a dropdown of recent paths; Browse asks the local controller to open Finder (or the system folder picker) so you can choose a folder. The controller picks up the new path on the next heartbeat and runs agents there.

Until you choose one, the harness uses the first of:

1. BLACKBOARD_PROJECT_ROOT
2. BLACKBOARD_AGENT_WORKSPACE — legacy alias, ignored if it still points at .blackboard/workspace
3. The controller's current working directory

The path must be an absolute git checkout on the machine running the controller. Recent paths are remembered in the dropdown. Restart the controller after pulling these changes so Finder browse can open.

Subscription agents

Sign in with the official tools before starting the controller:

codex login
claude
agy
grok login

The exact interactive login flow, available models, usage limits, and subscription terms are owned by each vendor and can change. controller:check confirms that the commands are installed and prints the resolved project. The board labels these providers Detected or CLI found; this does not establish authentication, quota, or model availability. The first real run will surface an expired or missing login as a failed job.

Blackboard uses subscriptions only through official authenticated local CLIs. It does not extract OAuth tokens, automate vendor websites, or turn a personal subscription into a hosted API. Any provider without a suitable CLI must use its normal API adapter and separate API billing.

Adapters use these bounded, non-interactive modes:

| Agent | Transport | Harness mode | | --- | --- | --- | | Codex | codex exec | workspace-write sandbox in the project | | Claude | claude -p | acceptEdits, file + git-capable tools | | Antigravity | agy --print | accept-edits, skip permission prompts | | Grok | grok --prompt-file | always-approve, workspace sandbox, no force-push | | DeepSeek | OpenAI-compatible HTTPS API | snapshot only (cannot edit) | | Meta | OpenAI-compatible HTTPS API | snapshot only (cannot edit) |

API agents receive the same git snapshot (status, log, tracked files) and should propose concrete file-level changes. CLI agents may apply edits. The model dropdown controls the model argument sent to each adapter; availability still depends on the user's vendor account and installed CLI version.

API keys

Put API keys only in .env.controller; it is ignored by Git and is loaded only by the local controller. Keep .env.local limited to the board login (BLACKBOARD_LOGIN) and the shared runner token used by /api/controller. DeepSeek has working defaults. Meta requires META_MODEL because model access can vary by account. If your Meta endpoint is not the Llama API default, set META_BASE_URL to its OpenAI-compatible /v1 base.

Useful commands

npm run lint
npm test
npm run typecheck
npm run build
npm run controller:once
npm run db:generate

controller:once claims at most one queued job and exits. It is useful for debugging. The normal controller stays running with a worker pool (BLACKBOARD_CONCURRENCY, default 2, max 3) so independent jobs can overlap without flooding the machine.

Security boundary

This is a single-user local harness, not a public multi-tenant proxy for personal subscriptions. Agents can read and write files in the configured git checkout and can run git commands. They are instructed not to force-push, rewrite git config, or commit unless you ask. Grok is additionally blocked from rm -rf and git push --force.

Writing CLI jobs run in dedicated git worktrees on candidate branches (blackboard/<run>/<agent>), keeping your primary checkout and working tree clean. In Debate mode, agents build on previous candidates. Proposals use separate lineages. Changes remain in candidate branches until reviewed and integrated.

If the board is hosted, keep site access private. Blackboard supports user accounts with email/password sign-up and sign-in, optional external OAuth providers (GitHub, Google, GitLab), or a single BLACKBOARD_LOGIN password fallback. Set a separate BLACKBOARD_RUNNER_TOKEN for the controller, and run the controller only on the Mac that owns the CLI sessions. The board does not use the controller's local-dev token bypass. Never put CLI session files, OAuth tokens, or copied browser cookies in the database or deployment environment. Review diffs before you push anything an agent wrote.

Isolated product smoke test

Keep your normal board and controller stopped for this test URL. Start a separate preview using a disposable database:

BLACKBOARD_DEV_STATE_PATH=/tmp/blackboard-product-qa-state npm run dev -- --port 3017

Then run the protocol test against that preview:

BLACKBOARD_QA_URL=http://localhost:3017 node --env-file=.env.local scripts/product-smoke.mjs

The script refuses boards containing non-QA tasks or a connected real controller. It simulates plan, candidate, review, verification, and integration responses through the real API. It does not launch providers, execute verification commands, or apply Git changes. These checks complement the Git/process unit tests and real-provider testing; they do not replace them.

Idle boards refresh every five seconds; active work and integration refresh faster. A run cannot start until the controller confirms the repository and detects its selected providers. Existing queued jobs retain their recovery behavior.

Legacy databases

Databases predating jobs.run_id require a separate migration. Blackboard refuses that upgrade and preserves the existing tables; it no longer drops job and action history. Back up such a database before migrating it. Current databases continue through the existing additive setup path.