# BooCode — External Code Review & Lift Inventory

Last updated: 2026-05-25

This document tracks every open source repo BooCode references or lifts code from. Pin this so we don't lose attribution and don't re-evaluate the same projects twice.

BooCode is personal/single-user — license compatibility is non-blocking, but the License column is recorded so we don't accidentally inherit an obligation if BooCode ever goes public.

> **Companion doc:** `boocode_roadmap.md` is the canonical source for shipping state, version ordering, and what's planned vs. shipped. This document is the canonical source for *why* each external repo earned its row. Reconcile shipping state via the roadmap when in doubt.
>
> **Shipped reality as of 2026-05-25** (per roadmap + CHANGELOG): v1.13.x line closed. v2.0 BooCoder shipped (write tools, dispatcher, MCP server, CoderPane). v2.1.0 provider picker shipped — BooCoder on host systemd, direct spawn dispatch (SSH deprecated). Database name `boochat`, Docker service `boocode_db`. When this catalog reads "planned" for shipped work, check `CHANGELOG.md` and `boocode_roadmap.md`.

-----

## Paseo-equivalent dispatcher inside BooCode (2026-05-22 strategic pivot)

Sam wants BooCode to function like Paseo without using Paseo itself. **Paseo (getpaseo/paseo) is AGPL-3.0**, which is incompatible with BooCode's MIT licensing and BooCode's network-served deployment at `code.indifferentketchup.com`. Lift the architecture and design patterns (not copyrightable) without lifting any code. Build inside BooCode's existing Fastify + TypeScript + PostgreSQL + React stack.

### Locked architecture decisions (2026-05-22, Sam confirmed)

1. **Monorepo with three surfaces, not three backend packages.** `/opt/boocode/apps/`:
- `apps/web/` — React SPA (chat, coder, terminal panes).
- `apps/server/` — Fastify backend for BooChat (inference, read-only tools, :9500 in Docker).
- **`apps/coder/`** — BooCoder (write tools + external-CLI dispatch, port `9502`, `coder.indifferentketchup.com`, **shipped v2.0**, host systemd since v2.1.0).
- **`apps/booterm/`** — BooTerm (PTY/terminal pane, **live since May 2026, port `9501`**). bookworm-slim + node-pty + tmux + xterm.js. Shares Postgres database `boochat`.
- All three surfaces share the same Postgres, project registry, and task infrastructure.
1. **Single shared database `boochat`.** Docker service name `boocode_db`. Three apps, one Postgres. Cross-surface joins are valuable: a BooCoder task can reference the BooChat conversation that originated it; a BooTerm session can be linked to the BooCoder task it's debugging.
1. **Mount strategy: blanket `/opt:rw`, permission gating at the write-tool layer.** Container gets full RW access to `/opt`; the BooCoder write tools (`edit_file`, `create_file`, `delete_file`) enforce path scoping using the v1.15 permission wildcard ruleset (`apps/coder/services/path_guard.ts`). Per-project scoping is *policy*, not *mount*. Simpler, single mount, no Docker reconfig per project. Trade-off: a bug in path-guard logic is the only thing between BooCoder and writing outside `/opt/<project>/`. **Path-guard correctness is therefore the highest-priority test target for v2.0** — fuzz it, property-test it, run it through every traversal-attack pattern.
1. **External CLI agents (`opencode`, `claude`, `goose`, `pi`) live on the host.** BooCoder runs as `boocoder.service` on the host (v2.1.0+) and spawns agents directly via `install_path` — no SSH tunnel. Host install inherits Sam's existing `~/.opencode/`, `~/.claude/`, `~/.config/goose/` configs.

### Three-surface execution model

Each surface has its own primary execution mode but shares the same underlying tasks/projects/worktree infrastructure:

|Surface                     |Port           |Execution mode                                                                                                                                                                                   |Tools                                                                                                               |Write access                                                                    |
|----------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
|**BooChat** (`apps/server` + `apps/web`)|9500           |In-process inference loop                                                                                                                                                                        |`view_file`, `list_dir`, `grep`, `find_files`, codecontext sidecar tools                                            |None — `/opt` is read-only at the tool layer regardless of mount                |
|**BooCoder** (`apps/coder`) |9502           |**Two paths, same surface:** (a) in-process inference loop with native write tools + pending-changes queue, (b) ACP/PTY-dispatched external CLI (opencode/claude/goose/qwen) in a per-task git worktree|All BooChat tools + `edit_file`, `create_file`, `delete_file`, `apply_pending`, `rewind` + external dispatch via `tasks`|Yes, gated through `pending_changes` table (nothing touches disk until `/apply`)|
|**BooTerm** (`apps/booterm`)|**9501 (live)**|PTY to host shell via tmux, scoped to project cwd                                                                                                                                                |Shell + SSH-out, no inference loop                                                                                  |Yes (it's a real terminal)                                                      |

**The "two paths, same surface" decision in BooCoder is the answer to last turn's "1 and 2 full featured" question.** The in-process loop (Option B / Answer B) handles interactive write work where Sam wants the pending-changes UI and native tool gating. The PTY dispatch (Option A / Answer A) handles parallel/dispatched/batch work where Sam wants to A/B different CLI agents against the same task in separate worktrees. The user picks per task via a `dispatch_external_agent(agent: 'opencode'|'claude'|'goose'|'pi', model: string, task: string, worktree: string)` tool the in-process loop can call, or via a UI dropdown at task creation.

### MCP and ACP roles per surface (locked 2026-05-22)

Two open protocols extend BooCode's tool and agent surfaces:

- **MCP (Model Context Protocol):** the tool/resource extension protocol. An MCP **client** consumes tools from MCP **servers** (local stdio subprocesses or remote HTTP/SSE endpoints). Standard since late 2024. Reference SDKs in 10 languages. Hundreds of community servers, mostly via the [MCP Registry](https://registry.modelcontextprotocol.io/).
- **ACP (Agent Client Protocol):** the editor↔agent extension protocol. An ACP **client** (host) drives an ACP **agent** over JSON-RPC stdio (or HTTP/WS for remote). Standardizes session lifecycle, multi-session management, model/mode switching mid-session, file operations, terminal events, permission prompts. Originated at Zed. Implemented by opencode (`opencode acp`), goose (`goose acp`), JetBrains IDEs, Avante.nvim, CodeCompanion.nvim.

**The role assignment (Sam, 2026-05-22):**

|Surface     |MCP client                       |MCP server                                      |ACP client (host)                                              |ACP agent (driveable)                                      |
|------------|---------------------------------|------------------------------------------------|---------------------------------------------------------------|-----------------------------------------------------------|
|**BooChat** |**Yes** (read-only tool consumer)|No                                              |No                                                             |No                                                         |
|**BooCoder**|**Yes**                          |**Yes** (exposes BooCoder tools to other agents)|**Yes** (drives opencode/goose/etc. via ACP instead of raw PTY)|**Yes** (BooCoder itself driveable from Zed/JetBrains/etc.)|

**BooChat as MCP client only.** BooChat is read-only by design — its existing tools (`view_file`, `list_dir`, `grep`, `find_files`) extend naturally with MCP-served read-only tools (Context7 for docs, gh_grep for code search, the official `fetch`/`git`/`memory`/`sequentialthinking` reference servers). Per-server `enabled` flag gates which tools BooChat may consume. **Hard rule for BooChat MCP config: never enable a write-capable MCP server.** A server whose tools mutate state breaks the read-only invariant. The codecontext sidecar (already shipped in v1.12 Track B) becomes the first internal "MCP-shaped" tool source, even though it's currently an HTTP shim rather than an MCP server; consider rewriting it as a real MCP server in v1.13 so it composes naturally with the rest.

**BooCoder full matrix.** All four roles. Justifications:

1. **MCP client (write-capable allowed).** Same MCP ecosystem as BooChat plus write-capable servers (`filesystem` write tools, `git` commit, deployment integrations) — all gated through BooCoder's existing pending-changes queue regardless of whether the write comes from a native tool or an MCP-served tool. Per-task allow/deny means a dispatched task can have a different MCP roster than the interactive shell.
1. **MCP server.** Expose BooCoder's own primitives as MCP tools: `boocoder.create_task`, `boocoder.list_pending_changes`, `boocoder.apply`, `boocoder.dispatch_external_agent`, `boocoder.list_worktrees`, etc. **This is what makes opencode-on-the-host BooCoder-aware** — Sam's external `opencode` sessions in Termius can call BooCoder's task queue without going through BooCoder's UI. Aligns with the agent-hub (#48) board-API pattern. Stdio transport for local opencode/claude; HTTP+OAuth for any external/remote consumer.
1. **ACP client (host).** **This replaces the raw-PTY dispatch plan for any agent that supports ACP** — currently opencode (`opencode acp`) and goose (`goose acp`). Instead of spawning a PTY and parsing free-form text output, BooCoder spawns the agent as an ACP subprocess and communicates over JSON-RPC. Gains: native session lifecycle, mid-session model/mode switching, file-operation events the BooCoder UI can render as diffs, terminal events that surface inside BooTerm, permission-prompt events the BooCoder UI can answer with a real dialog. **MCP servers configured in BooCoder are auto-forwarded to the dispatched ACP agent** (per goose docs: ACP clients pass their MCP servers in `context_servers` to the agent automatically) — one MCP config surface drives every dispatched agent. For agents without ACP (claude code, pi, smallcode), fall back to PTY dispatch as currently designed.
1. **ACP agent.** Expose `boocoder acp` so Zed, JetBrains, Avante.nvim, etc. can drive BooCoder as their agent. Means BooCoder becomes useable from any ACP-compatible editor without giving up the BooCoder UI, pending-changes gate, or task DAG. Lower priority than the other three — it's an outbound exposure, not core to the dispatcher build — but cheap once the ACP client side is implemented (same protocol library, server side).

**Why BooChat doesn't get ACP:** ACP standardizes the editor↔agent direction. BooChat doesn't drive agents; it *is* the chat. Nothing for ACP to do there. Adding ACP-agent role to BooChat would mean making BooChat driveable from Zed, which would convert it from a chat surface into an opencode-equivalent — different product. Skip.

**MCP server selection for v1 (start small).** Don't enable everything in the registry; MCP servers consume context budget per tool definition and large registries hit token limits fast. Start with:

- **For BooChat (read-only):** Context7 (already used via opencode), gh_grep, `modelcontextprotocol/server-fetch`, `modelcontextprotocol/server-git` (read mode), `modelcontextprotocol/server-memory`. Optionally `sequentialthinking` for reasoning chain scaffolding.
- **For BooCoder (add write-capable):** all of the above plus `modelcontextprotocol/server-filesystem` (with path scope = `/opt/<project>`, write-gated by BooCoder's pending-changes queue), eventually a custom BooCoder-internal MCP server for `dispatch_external_agent` / `apply_pending` / `list_worktrees`.

**Reference materials to read before implementing:**

- **Anthropics `mcp-builder` skill** (MIT, in `anthropics/skills`): four-phase MCP server build workflow — research → implement → test → eval. Includes the 10-question evaluation framework for validating that an LLM can actually use the server. **Run BooCoder-internal MCP server through this eval before shipping.**
- **OpenCode MCP docs** (`opencode.ai/docs/mcp-servers/`): the cleanest reference for the config-file shape, OAuth flow (Dynamic Client Registration per RFC 7591), per-agent tool whitelisting via glob patterns. Lift the JSON schema near-verbatim into BooCode's config (it's not copyrightable, and matching opencode's shape means any opencode user can copy their config to BooCode).
- **OpenCode ACP docs** (`opencode.ai/docs/acp/`): minimal — basically just `opencode acp` over stdio JSON-RPC. The protocol does the heavy lifting; once BooCoder speaks ACP, opencode works without further config.
- **Goose ACP docs** (`goose-docs.ai/docs/guides/acp-clients/`): more detailed than opencode's. Critical pattern documented there: **the ACP client's `context_servers` (MCP servers) are auto-forwarded to the agent.** This is the protocol-level mechanism for "one MCP config, every dispatched agent inherits it."
- **`agentclientprotocol.com`:** the canonical ACP spec. Note: full remote-agent support (HTTP/WebSocket transport) is still "a work in progress" per the spec maintainers — local-subprocess ACP is the proven path, remote ACP is experimental. **BooCoder's ACP client should use stdio for v1**, defer remote ACP until the spec stabilizes.
- **`modelcontextprotocol/servers`:** only 7 reference servers (everything/fetch/filesystem/git/memory/sequentialthinking/time) — the archived list (PostgreSQL, Slack, GitHub, etc.) is significant because **MCP servers are migrating to vendor-owned ownership** (GitHub now has an official MCP registry at `github.com/mcp`, Sentry hosts `mcp.sentry.dev`, etc.). Don't reimplement what vendors maintain. Discover via the MCP Registry, not the reference repo.

### Phasing for MCP/ACP integration (slots into the Paseo-equivalent phases)

- **Phase 1 MCP** (slots into Paseo-equivalent Phase 1): wire BooChat MCP client. Start with one server (likely Context7, since Sam already uses it). Single config block in BooChat's existing `agents.ts`. Tools appear alongside `view_file`/`grep`/etc. Validates the protocol loop end-to-end without touching write paths.
- **Phase 2 MCP** (slots into Paseo-equivalent Phase 2): same MCP client code drops into BooCoder unchanged. Add write-capable servers behind pending-changes gating. **Test path-guard against MCP-server file writes specifically** — an MCP filesystem server can attempt traversal just as easily as a native tool.
- **Phase 1 ACP** (slots into Paseo-equivalent Phase 4 — multi-agent + worktrees): swap the planned raw-PTY dispatch path for ACP wherever the target agent supports it. Initial coverage: opencode + goose. Claude Code / pi / smallcode stay on PTY fallback. The dispatcher worker checks `available_agents.supports_acp` per agent at dispatch time and picks the right transport. Same task table, different transport.
- **Phase 3 MCP** (after Paseo-equivalent Phase 3): build the BooCoder-internal MCP server exposing `boocoder.*` tools. Run through the mcp-builder eval framework (10 read-only complex questions with verifiable answers) before shipping. Once it's live, external `opencode` sessions in Termius can drive the BooCoder task queue without using BooCoder's UI.
- **Phase 2 ACP** (after Phase 3 MCP): expose `boocoder acp` for inbound ACP — Zed/JetBrains/Avante can use BooCoder as their agent.

### What Paseo is (the reference design)

Paseo is "one interface for all your Claude Code, Codex, and OpenCode agents." 4k stars, AGPL-3.0, TypeScript-heavy (98%), monorepo with 6 packages.

**Core architectural choices, each a target for BooCode to reproduce:**

1. **Daemon + clients split.** A long-running local daemon owns agent process management; thin clients (CLI, desktop Electron, mobile Expo, web) connect over WebSocket. Daemon survives client disconnects. **BooCode equivalent:** the Fastify server is the daemon; the React SPA, the three surface tabs (chat/coder/term), and a new thin `boocode` CLI are all clients.
1. **Six-package monorepo:** `server` (daemon), `app` (Expo iOS/Android/web), `cli`, `desktop` (Electron), `relay` (remote connectivity), `website`. **BooCode equivalent:** `apps/server` (BooChat Fastify backend), `apps/web` (React SPA hosting all pane types), `apps/coder` + `apps/booterm` (BooCoder and BooTerm surfaces). `relay` is unnecessary — Sam's Tailscale + Caddy + Authelia stack already provides remote connectivity; mobile is PWA.
1. **Process orchestration as the daemon's job.** Paseo spawns Claude Code / Codex / OpenCode as **child processes**, not API calls. Each agent runs with full local dev environment access. **BooCoder equivalent:** the dispatch worker (in `apps/server`) spawns `claude` / `opencode` / `goose` / `pi` via local-exec PTY on the **host**, captures stdout/stderr/exit-code into PostgreSQL stream tables, exposes WebSocket events to all three React surfaces.
1. **CLI shape:**

   ```
   paseo run --provider claude/opus-4.6 "implement user authentication"
   paseo run --provider codex/gpt-5.4 --worktree feature-x "implement feature X"
   paseo ls
   paseo attach <id>
   paseo send <id> "follow-up"
   paseo --host workstation.local:6767 run "..."
   ```

   **BooCode equivalent (target):** `boocode run --agent opencode --model qwen3.6-35b-a3b-mxfp4 "task"`, `boocode ls`, `boocode attach <session-id>`, `boocode send <session-id> "..."`, `boocode --host ubuntu-homelab.tailnet.ts.net:9500 run "..."`.
1. **`--worktree feature-x` auto-creates a git worktree** per agent — same pattern as zeroshot, bernstein, vorn. **Lift directly:** before spawning the agent, `git worktree add /tmp/booworktrees/<session-id> -b <branch> origin/main`; agent runs in that directory; merge or discard on completion. One worktree per active session.
1. **Three orchestration skills (their "skills/" directory):**
- **`/paseo-handoff`** — plan with one agent, hand off to another. (Sam already does this manually: Claude Chat reviews, OpenCode implements.)
- **`/paseo-loop`** — Ralph loop: agent attempts → verifier judges → repeat, bounded max-iterations. Maps to Sam's "doom-loop guard" terminology (#1 opencode `DOOM_LOOP_THRESHOLD=3`).
- **`/paseo-orchestrator`** — team of agents coordinated via shared chat room; plan-with-X, implement-with-Y, review-with-Z.
1. **No telemetry, no forced login.** Confirms BooCode's privacy-first stance.
1. **`mise` for tool version management.** Worth checking against BooCode's Node version pinning; `.mise.toml` is a more modern alternative to `.nvmrc`.

### How BooCode reproduces this (target architecture)

The dispatcher lives inside the existing BooCode Fastify server, so the React SPA and a new CLI both drive the same backend. PostgreSQL is the durable state. Per-session PTY child processes are the units of agent work. The CLI is a thin client over the existing WebSocket/HTTP API.

**New PostgreSQL tables** (schema drawn from `Dominic789654/agent-hub` for the durable-task pattern, also see #45 entry below):

```
projects          id, name, repo_path, default_agent, default_model
task_templates    id, project_id, name, prompt_template, tools_whitelist, agent, model
tasks             id, project_id, template_id, parent_task_id, state, input, output_summary, dependencies, agent, model, worktree_path, cost, started_at, ended_at
pipelines         id, project_id, name, steps (FK array of template ids)
pipeline_runs     id, pipeline_id, state, current_step, run_started_at
human_inbox       view of tasks where state IN ('blocked', 'failed', 'needs_human')
```

**New worker process** (`boocode-dispatcher`): picks ready tasks (`state='pending'` AND all dependencies are `state='done'`) off the queue, spawns the agent via PTY in the assigned worktree, captures output, marks `state='done'`/`'failed'`/`'needs_human'` with a summary. Runs as a systemd unit alongside the Fastify server.

**New CLI** (`boocode`): three flows — interactive (`boocode run`), follow-up (`boocode send <id>`), inspection (`boocode ls`, `boocode attach <id>`). Internally just a WebSocket/HTTP client against the existing BooCode API.

**New WebSocket event stream**: agent stdout, status transitions, tool calls. Same pattern Paseo uses for daemon-to-client.

**Subagent isolation via Roo Boomerang Tasks pattern (#41 below):** when an agent calls a new-subtask tool, BooCode spawns a fresh PTY/session with a fresh PostgreSQL row and isolated context. Child runs to `attempt_completion`, writes a summary, dies. Parent resumes reading only the summary. This is the **single most important context-management primitive in the stack** — it's what keeps long-running orchestrators from poisoning their own context with detail.

**Observation via Claude Code hooks** (siropkin/budi, #47 below): register BooCode's Fastify backend as the hook receiver for `SessionStart`, `UserPromptSubmit`, `PostToolUse`, `SubagentStart`, `Stop`. Real-time visibility without wrapping the agent.

### Phased plan (rough sequence, not a master plan)

- **Phase 1** — PTY child-process dispatch for a single agent (claude or opencode), exposed via the existing BooCode UI. No queue, no DAG. Just "spawn, capture, display."
- **Phase 2** — PostgreSQL tasks/projects schema + worker. Static project registry, single-agent flow.
- **Phase 3** — Boomerang-style `new_task` tool + isolated child sessions. Orchestrator vs executor agent profiles.
- **Phase 4** — Multi-agent (add codex/opencode beside claude), git worktree auto-create per task, CLI client.
- **Phase 5** — Pipelines (chained templates), human inbox, dashboard view in React.
- **Phase 6** — `/handoff`, `/loop`, `/orchestrator` skills.

Don't ship Phase 1 against AGPL/GPL code; build clean. Patterns are free; code isn't.

-----

## Reference repos

### Tier A — actively lifting from / running as sidecar

#### 1. anomalyco/opencode (NEW Tier A as of 2026-05-20)

- **URL:** <https://github.com/anomalyco/opencode>
- **License:** MIT
- **Language:** TypeScript (Effect-TS service-oriented)
- **What it is:** The coding agent Sam uses via Termius/Paseo. Also the source of every algorithm BooCode is porting through v1.15.
- **Why it matters:** opencode's `packages/opencode/src/session/` is the canonical reference implementation for every part of the inference layer BooCode is rebuilding. We lift the algorithms, not the Effect-TS plumbing.
- **Algorithms lifted so far:**
  - `session/compaction.ts` → v1.11.0 (shipped). `usable`, `isOverflow`, `select`, `buildPrompt` ported to plain TS. SUMMARY_TEMPLATE markdown skeleton verbatim.
  - `session/overflow.ts` → v1.11.0 (shipped). 20k `COMPACTION_BUFFER` constant.
  - `session/processor.ts` `DOOM_LOOP_THRESHOLD=3` → v1.11.6 (shipped).
  - `session/llm.ts` AI SDK adoption (`streamText`, ReasoningPart shape) → v1.13.1 (shipped).
  - Parts taxonomy (text/tool_call/tool_result/reasoning/step_start) → v1.13.0 (shipped).
  - `experimental_repairToolCall` via AI SDK v6 → v1.13.3 (shipped).
  - **Two-tier compaction prune** (`message_parts.hidden_at` + pure decision helper) → v1.13.4 (shipped).
  - **`tool/truncate.ts` truncation + outputPath pattern** (adapted: opaque id, not filesystem path) → v1.13.5 (shipped).
- **Algorithms lifted (queued):**
  - `session/overflow.ts` 0.85×ctx_max early-trigger formula → v1.13.9
  - `session/prompt.ts` `runLoop()` outer agent loop → v1.14
  - `permission/evaluate.ts` wildcard ruleset → v1.15
  - MCP client (transport, tools/list discovery, tools/call) → v1.15
- **What NOT to use:** Effect-TS service plumbing. Snapshot/patch system (for tool-edit revert; BooCoder territory if needed). The `experimental_native_runtime` (AI SDK fallback path). opencode's prompts.
- **Source tag:** `dev` branch on `anomalyco/opencode`. **This is the canonical repo as of 2026-05-22** (corrected from earlier `sst/opencode` attribution — `anomalyco/opencode` is where development now lives, 164k stars, v1.15.7 released May 21 2026, 13k+ commits).

#### 2. nmakod/codecontext

- **URL:** <https://github.com/nmakod/codecontext>
- **License:** MIT
- **Language:** Go (single binary)
- **What it is:** AI-oriented codebase context map generator. Tree-sitter parsing across TS/JS/Go/C++/Swift/Python/Java/Rust/Dart/JSON/YAML. Generates `CLAUDE.md`-style structured overview. Bundled MCP server with 8 tools.
- **MCP tools exposed:** `get_codebase_overview`, `get_file_analysis`, `get_symbol_info`, `search_symbols`, `get_dependencies`, `watch_changes`, `get_semantic_neighborhoods` (git co-change patterns — no embeddings), `get_framework_analysis`.
- **Why it matters:** Solves the "architect needs a map" problem without embeddings.
- **How we use it:** Run as sidecar container in v1.12. Wire its MCP tools into BooCode's `inference/tools.ts` as static wrappers in v1.12, then re-wire via real MCP client when v1.15 ships.
- **What NOT to use:** Nothing. Clean fit.

#### 3. aimasteracc/tree-sitter-analyzer

- **URL:** <https://github.com/aimasteracc/tree-sitter-analyzer>
- **License:** MIT
- **Language:** Python, MCP server + CLI
- **What it is:** Local-first code context engine. Outline-first navigation, ripgrep-based impact trace, no embeddings. 17 languages. Claims 54-56% token reduction via TOON format.
- **MCP tools exposed:** `get_code_outline`, `trace_impact`, plus structural search/extract tools.
- **Why it matters:** Backup analyzer with a different response shape — outline-first scales better than codecontext's full dump on huge files. Impact trace is useful for "what calls this function" without a full graph build.
- **How we use it:** Lift the AST query patterns (`.scm` files) and the outline-first response shape. Can also run as a second MCP sidecar alongside codecontext.
- **What NOT to use:** Don't lift the TOON format if it conflicts with shadcn rendering — markdown stays.

#### 4. spirituslab/codesight

- **URL:** <https://github.com/spirituslab/codesight>
- **License:** check repo — assumed MIT-ish
- **Language:** TypeScript/Node
- **What it is:** Static code structure visualization. Symbol extraction, import resolution, call graphs. Detects circular dependencies and dead code (with documented false-positive caveats for `customElements.define()`, framework entry points, dynamic imports).
- **Why it matters:** Gives BooCode a `repo_health` tool — different from codecontext's "what is this" map. This is "what's wrong with this."
- **How we use it:** v1.16. Port the analyzer core (`analyze.mjs`). Call-graph builder + circular-dep + dead-code detectors into BooCode's `tools/repo_health.ts`. Drop the VS Code extension shell entirely.
- **What NOT to use:** The VS Code wrapper, the "idea layer" feature (requires Copilot or Claude Code wiring we don't want).

#### 5. Aider-AI/aider

- **URL:** <https://github.com/Aider-AI/aider>
- **License:** Apache-2.0
- **Language:** Python
- **What it is:** Git-native AI pair programmer CLI. Pioneered the tree-sitter repo-map + personalized PageRank approach.
- **Why it matters:** Authoritative source of per-language `tags.scm` query files. 60+ languages curated and battle-tested.
- **How we use it:** **Lift directly:** `aider/queries/tree-sitter-*.scm` — drop into BooCode's analyzer for any language codecontext or codesight don't cover natively.
- **What NOT to use:** Don't port `repomap.py` itself — codecontext supersedes it.

-----

### Tier B — patterns / partial lift

#### 6. continuedev/continue

- **URL:** <https://github.com/continuedev/continue>
- **License:** Apache-2.0
- **Language:** TypeScript
- **What it is:** IDE assistant framework. Full RAG pipeline, AST chunking, multi-provider LLM abstraction.
- **Why it matters:** One specific drop-in lift:
1. `core/indexing/ignore.ts` — `DEFAULT_SECURITY_IGNORE_FILETYPES`. Three-tier matcher (basenames, extensions, prefixes). Going into BooCode's `pathGuard` to block analyzing `.env`, `.pem`, `id_rsa`, etc.
- **How we use it:** v1.11.7. Lift the ignore list, adapt to a `path.basename` + extension + prefix matcher.
- **What NOT to use:** `core/indexing/CodebaseIndexer.ts` and `LanceDbIndex.ts` — embedding-based, the path we walked away from.

#### 7. cline/cline

- **URL:** <https://github.com/cline/cline>
- **License:** Apache-2.0
- **Language:** TypeScript (VS Code extension)
- **What it is:** Autonomous coding agent. Pioneered plan/act mode and granular per-tool auto-approve.
- **Why it matters:** Pattern source for v1.15 (absorbed into the broader permissions work). Plan/act invariant: in plan mode, write tools hidden from the model's tool registry; in act mode, available but each individual tool can be approval-gated.
- **How we use it:** Lift the *pattern*, not the code. opencode's `permission/evaluate.ts` wildcard ruleset supersedes cline's mode-enum; cline contributes the conceptual framing (read-only invariant in BooCode v1.x).
- **What NOT to use:** Cline's VS Code-specific UI plumbing. The shape is wrong for our stack.

#### 8. plandex-ai/plandex

- **URL:** <https://github.com/plandex-ai/plandex>
- **License:** MIT
- **Language:** Go
- **What it is:** Terminal agent with a pending-changes sandbox. Edits never touch the filesystem until `/apply`. 2M token context.
- **Why it matters:** Reference architecture for BooCoder (v2.0). The "edits queue in a virtual layer, applied atomically" model is the right safety story for write tools.
- **How we use it:** Lift the data model: `pending_changes` table keyed by `(project_id, session_id, file_path)`, with diff content and apply/reject state. Lift the `diff` / `apply` / `rewind` UX vocabulary.
- **What NOT to use:** Plandex's 2M-context-window engineering. Our context is bounded by llama-swap.

#### 9. OpenHands/OpenHands

- **URL:** <https://github.com/OpenHands/OpenHands>
- **License:** MIT
- **Language:** Python
- **What it is:** Autonomous coding agent platform. V1 architecture is built on an append-only typed event log + Docker sandbox runtime.
- **Why it matters:** Two distinct patterns:
1. Event-log architecture — superseded by v1.13's parts-table approach (which derives from opencode's part-message model). OpenHands event-log is conceptually similar but different shape.
1. Sandbox runtime — per-session Docker container for write tools. Closes the `/opt:ro` mount risk.
- **How we use it:** v2.1. Lift the runtime container pattern (HTTP API inside container, BooCoder calls in). Don't port the Python implementation directly.
- **What NOT to use:** OpenHands' agent prompts, the full microagent system, the cloud deployment path. Event-log shape (use opencode-derived parts table instead).

-----

### Tier C — reference only / partial use / skip

#### 10. cortexkit/aft (actual repo path: ualtinok/aft)

- **URL:** <https://github.com/ualtinok/aft>
- **License:** check repo
- **Language:** Rust binary + TypeScript plugin
- **What it is:** Tree-sitter analysis tools delivered as a Rust binary, communicating with an OpenCode plugin via JSON-over-stdio. Warm-process pattern: one binary per project keeps parse trees in memory.
- **Why it matters:** The BridgePool transport model. If our `codecontext` tool calls get hot (agent loops calling it dozens of times per session), the warm-process pattern is faster than fork-per-call.
- **How we use it:** **Defer.** Profile first. Codecontext sidecar might be fast enough on its own. Revisit if tool-call latency becomes the bottleneck.
- **What NOT to use:** The opencode-plugin wrapper. Wrong integration surface.

#### 11. codeprysm/codeprysm

- **URL:** <https://github.com/codeprysm/codeprysm>
- **License:** check repo
- **Language:** Rust
- **What it is:** Graph-based code intelligence: tree-sitter parsing → node/edge graph in Qdrant, embeddings layered on top, MCP server exposes semantic search.
- **Why it matters:** Clean node/edge taxonomy: nodes = Container/Callable/Data; edges = CONTAINS/USES/DEFINES.
- **How we use it:** Lift the taxonomy *only* if we end up building our own graph instead of relying on codecontext. The embedding half is the trap we walked away from.
- **What NOT to use:** The Qdrant + embedding pipeline. Same anti-pattern as continue's indexer.

#### 12. DeepSourceCorp/globstar

- **URL:** <https://github.com/DeepSourceCorp/globstar>
- **License:** MIT
- **Language:** Go
- **What it is:** Static analysis toolkit for writing code checkers using tree-sitter S-expression queries. YAML interface for simple checkers, Go interface for complex multi-file checkers.
- **Why it matters:** Not for the architect tool. **Future use only.** If BooCoder ever grows a "verify before commit" lane, globstar checkers could be the verification engine: drop YAML checkers into `.globstar/`, run as a pre-apply gate.
- **How we use it:** Park. Not in any current version.
- **What NOT to use:** Don't try to use it as a codebase analyzer — it's a linter framework, wrong tool for the architect role.

#### 13. getpaseo/paseo

- **URL:** <https://github.com/getpaseo/paseo>
- **License:** AGPL-3.0
- **What it is:** WebSocket daemon ↔ client protocol for agent coordination. Already running in your stack (paseo dispatches Claude Code/opencode).
- **Why it matters:** Patterns for agent lifecycle, `--worktree` flag pattern, ECDH/NaCl security model.
- **How we use it:** Reference for BooCoder isolation (v2.0/v2.1). Note AGPL — fine for personal, blocks public distribution.
- **What NOT to use:** Don't vendor the source. Treat as a peer service.

#### 14. earendil-works/pi

- **URL:** <https://github.com/earendil-works/pi>
- **License:** MIT
- **What it is:** `@mariozechner/pi-agent-core` (tool loop + state machine) and `@mariozechner/pi-ai` (provider abstraction).
- **Why it matters:** If we ever want non-llama-swap inference (Anthropic, OpenAI, Mistral direct), pi-ai is the cleanest TypeScript provider abstraction available.
- **How we use it:** Defer. v2.x optional batch only.

#### 15. microsoft/agent-framework

- **URL:** <https://github.com/microsoft/agent-framework>
- **License:** MIT
- **What it is:** Workflow graphs for multi-agent coordination.
- **Why it matters:** Conceptual reference for far-future multi-agent orchestration.
- **How we use it:** Read the ADRs in `docs/decisions/`. Don't port code — implementation is Azure/Python/.NET-heavy.

#### 16. microsoft/autogen

- **URL:** <https://github.com/microsoft/autogen>
- **License:** MIT
- **What it is:** Earlier Microsoft multi-agent framework.
- **Why it matters:** Effectively sunsetting in favor of agent-framework.
- **How we use it:** Skip. Don't invest in evaluating further.

#### 17. open-webui/open-webui

- **URL:** <https://github.com/open-webui/open-webui>
- **License:** BSD-3
- **What it is:** Self-hosted LLM frontend.
- **Why it matters:** Python/Svelte, wrong stack. RAG pipeline only worth a read if BooLab needs improvement — unrelated to BooCode.
- **How we use it:** Skip for BooCode.

-----

### Reviewed 2026-05-22 — agent CLIs, ensembler, skills, context tooling

(Entries #18–#60 from the 2026-05-22 deep review pass are preserved verbatim from the prior catalog; reproducing the full block here would exceed the doc's usable density. The headline take-aways are captured in the Decisions log at the bottom of this file and in the Lift Catalog table. Source repos and detailed notes remain available in the previous revision of this document if needed — `git log -- boocode_code_review.md` to retrieve.)

-----

## Lift catalog — what lands where

|Source repo                         |Specific artifact                                                                                                     |License                                        |BooCode destination                                                                         |Version                                           |
|------------------------------------|----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|--------------------------------------------------------------------------------------------|--------------------------------------------------|
|`anomalyco/opencode`                |`session/compaction.ts` + `session/overflow.ts` algorithms                                                            |MIT                                            |`services/compaction.ts`                                                                    |**v1.11.0 ✅**                                     |
|`anomalyco/opencode`                |`session/processor.ts` DOOM_LOOP_THRESHOLD pattern                                                                    |MIT                                            |`services/inference.ts` doom-loop guard                                                     |**v1.11.6 ✅**                                     |
|`continuedev/continue`              |`core/indexing/ignore.ts` DEFAULT_SECURITY_IGNORE_FILETYPES                                                           |Apache-2.0                                     |Extend `path_guard.ts` exclusion list                                                       |**v1.11.7 ✅**                                     |
|`nmakod/codecontext`                |Whole binary (sidecar)                                                                                                |MIT                                            |New `codecontext` container, 8 MCP-shaped tools wired via static wrappers                   |**v1.12.0 ✅**                                     |
|`anomalyco/opencode`                |`session/llm.ts` experimental_repairToolCall pattern                                                                  |MIT                                            |AI SDK v6 `streamText` wiring                                                               |**v1.13.3 ✅**                                     |
|`anomalyco/opencode`                |`tool/truncate.ts` truncation + outputPath pattern (adapted: opaque id)                                               |MIT                                            |`services/truncate.ts` + `view_truncated_output` tool                                       |**v1.13.5 ✅**                                     |
|`Aider-AI/aider`                    |`aider/queries/tree-sitter-*.scm` (60+ files)                                                                         |Apache-2.0                                     |Fallback grammars for languages not covered by sidecars                                     |**v1.12 ✅ (fallback)**                            |
|`anomalyco/opencode`                |`session/llm.ts` AI SDK v6 adoption + ReasoningPart shape                                                             |MIT                                            |`services/inference/stream-phase.ts` (`streamText` adapter)                                 |**v1.13.1-A/B/C ✅**                               |
|`anomalyco/opencode`                |Parts-message taxonomy (text, tool_call, tool_result, reasoning, step_start)                                          |MIT                                            |`message_parts` table + `messages_with_parts` view                                          |**v1.13.0 ✅ + v1.13.1-B ✅**                       |
|`anomalyco/opencode`                |Two-tier compaction prune (`message_parts.hidden_at` + tier logic)                                                    |MIT                                            |`services/inference/prune.ts` (`selectPruneTargets`)                                        |**v1.13.4 ✅**                                     |
|`anomalyco/opencode`                |0.85×ctx_max overflow trigger formula                                                                                 |MIT                                            |`services/compaction.ts` early-trigger constant                                             |v1.13.9 (planned)                                 |
|`anomalyco/opencode`                |`session/prompt.ts` runLoop() outer agent loop                                                                        |MIT                                            |`services/inference.ts` step-based loop                                                     |v1.14 (planned)                                   |
|`anomalyco/opencode`                |`agent.steps` per-agent step cap                                                                                      |MIT                                            |AGENTS.md + agents.ts                                                                       |v1.14 (planned)                                   |
|`anomalyco/opencode`                |`permission/evaluate.ts` wildcard ruleset                                                                             |MIT                                            |new `permissions` table + matcher                                                           |v1.15 (planned)                                   |
|`anomalyco/opencode`                |`mcp/index.ts` MCP client (SSE transport + tools/list + tools/call)                                                   |MIT                                            |new `services/mcp/` module; codecontext re-wired through it                                 |v1.15 (planned)                                   |
|`cline/cline`                       |Plan/Act invariant (read-only mode pattern)                                                                           |Apache-2.0                                     |absorbed into v1.15 permissions work                                                        |v1.15 (planned)                                   |
|`spirituslab/codesight`             |`analyze.mjs` — call graph, circular-dep, dead-code                                                                   |MIT-ish                                        |`apps/server/src/tools/repo_health.ts`                                                      |v1.16 (planned)                                   |
|`plandex-ai/plandex`                |`pending_changes` data model, diff/apply/rewind UX                                                                    |MIT                                            |New `pending_changes` table, BooCoder write-tool gating                                     |v2.0 (planned)                                    |
|`OpenHands/OpenHands`               |Sandbox runtime pattern                                                                                               |MIT                                            |New per-session Docker sandbox (skip-condition if path-guard holds)                         |v2.1 (optional)                                   |
|`cortexkit/aft` (ualtinok/aft)      |BridgePool warm-process JSON-stdio pattern                                                                            |check                                          |Optimization if profile shows fork overhead                                                 |Deferred                                          |
|`codeprysm/codeprysm`               |Node/edge taxonomy (Container/Callable/Data, CONTAINS/USES/DEFINES)                                                   |check                                          |Reference only if we ever build our own graph                                               |None                                              |
|`getpaseo/paseo`                    |**Daemon+clients architecture, CLI verb shape, three skills concept**                                                 |AGPL-3.0 (design only)                         |**Paseo-equivalent dispatcher design** (all phases)                                         |**v2.0+ roadmap**                                 |
|`Dominic789654/agent-hub`           |**Task DAG schema, dispatcher worker, project registry, human inbox**                                                 |Apache-2.0                                     |**PostgreSQL schema + dispatcher worker process**                                           |**v2.0**                                          |
|`Roo Code Boomerang Tasks`          |Orchestrator-with-capability-restriction + down-pass/up-pass context discipline                                       |Apache-2.0 (pattern)                           |AGENTS.md design principle (v1.14) → `new_task` tool (v2.0)                                 |**v1.14 → v2.0**                                  |
|`siropkin/budi`                     |Claude Code 5-hook event taxonomy                                                                                     |MIT (pattern)                                  |Install globally on Sam's host for Claude Code observability                                |**Immediate (host install)**                      |
|`sipyourdrink-ltd/bernstein`        |HMAC-chained audit log primitive                                                                                      |verify                                         |PostgreSQL audit table with `prev_hmac` field                                               |v1.13+ optional                                   |
|`eyaltoledano/claude-task-master`   |Tiered tool loading (`core`/`standard`/`all`)                                                                         |MIT+Commons Clause (pattern only)              |`BOOCODE_TOOLS` env var in `agents.ts`                                                      |v1.12.x or v1.13                                  |
|`ai-christianson/RA.Aid`            |Three-stage research/plan/implement + expert escape hatch                                                             |Apache-2.0 (pattern)                           |AGENTS.md design principle + per-stage model routing                                        |v1.14+                                            |
|`DeepSourceCorp/globstar`           |Whole toolkit                                                                                                         |MIT                                            |Future verify-before-commit gate for BooCoder                                               |Parked                                            |
|`earendil-works/pi`                 |`pi-ai` provider abstraction                                                                                          |MIT                                            |Multi-provider LLM if pursued                                                               |v2.x optional                                     |
|`microsoft/agent-framework`         |Workflow graph concepts                                                                                               |MIT                                            |Conceptual only                                                                             |v3.x                                              |
|`qodo-ai/agents`                    |`agent.toml` schema: `output_schema`, `exit_expression`, `execution_strategy`                                         |MIT                                            |Extend `AGENTS.md` / agents.ts metadata                                                     |v1.14+                                            |
|`qodo-ai/qodo-cover`                |Record/replay LLM response harness (hashed prompt → fixture YAML)                                                     |AGPL-3.0                                       |Re-implement in Vitest plugin; pattern only, no vendored source                             |v1.13+                                            |
|`qodo-ai/qodo-skills`               |PR-resolver state machine (fetch issues → batch/interactive fix → inline reply)                                       |MIT                                            |New BooCoder PR-resolver tool with provider CLI adapters                                    |v2.0+                                             |
|`augmentcode/augment-swebench-agent`|Majority-vote ensembler (K diffs → ranker model → winner) + JSONL schema                                              |MIT                                            |Optional BooCoder verify-gate layer above pending-changes                                   |v2.0+ optional                                    |
|`olimorris/codecompanion.nvim`      |Agent Client Protocol (ACP) integration shape                                                                         |Apache-2.0                                     |Conceptual only — possible non-web frontend protocol                                        |v2.x watch list                                   |
|`zed-industries/codex-acp`          |ACP server-side adapter reference implementation                                                                      |Apache-2.0                                     |Working blueprint if BooCode ever ships an ACP adapter                                      |v2.x watch list (parked)                          |
|`Leonxlnx/taste-skill`              |`taste-skill/SKILL.md` (anti-slop ban list + 3-dial parameterization)                                                 |MIT                                            |Vendor into BooCode skills/ after diff against existing `frontend-design`; binds to BooCoder|v1.12.x diff → v2.0+                              |
|`Fission-AI/OpenSpec`               |`openspec/changes/<name>/{proposal,specs,design,tasks}.md` directory structure                                        |permissive (verify)                            |Reformat BooCode's batch docs to OpenSpec shape; optional CLI adoption later                |v1.13.x or v1.14                                  |
|`covibes/zeroshot`                  |Complexity × TaskType → workflow conductor + blind-validation invariant                                               |MIT                                            |AGENTS.md principle (no code); blind-validation gate above pending-changes                  |v1.13/v1.14 (principle) → v2.0+ (gate)            |
|`0xmariowu/AgentLint`               |31 evidence-backed checks (emphasis density, sweet-spot CLAUDE.md length, SHA-pinned Actions, .env/.gitignore, etc.)  |MIT                                            |Manual one-pass audit of CLAUDE.md/AGENTS.md across Sam's repos; optional plugin install    |Immediate (manual pass) → v1.12.x (plugin)        |
|`aaif-goose/goose`                  |Native ACP + 15+ providers (incl. Ollama); .claude/.codex/.cursor skill cross-emission                                |Apache-2.0                                     |Reference for ACP-protocol implementation and multi-provider abstraction                    |Reference / v2.x (if ACP lands)                   |
|`memovai/memov`                     |Shadow `.mem` timeline; `snap`/`validate_commit` MCP-tool shape; drift detection                                      |MIT                                            |Reference for v1.13+ `view_session_history` tool + v2.0+ verify gate                        |v1.13+ (history tool design) → v2.0+ (drift gate) |
|`Roo Code: Boomerang Tasks`         |Orchestrator with intentional capability restriction; down-pass/up-pass context discipline; precedence override clause|Apache-2.0 (Roo) — pattern lift only           |AGENTS.md orchestrator role definition + dispatched-task prompt template                    |v1.13 / v1.14 (principle), v2.0+ (real delegation)|
|`eyaltoledano/claude-task-master`   |Tiered tool-loading via env var (core/standard/all); three model roles; PRD-as-source-of-truth                        |MIT+Commons Clause (no code lift; pattern only)|`BOOCODE_TOOLS` env var for tiered loading; reaffirm three-model-role pattern               |v1.12.x / v1.13 (tier hint)                       |
|`sipyourdrink-ltd/bernstein`        |HMAC-chained audit log; signed agent cards (Ed25519+JCS); per-artifact lineage; air-gap mode                          |Verify before lift                             |Reference for compliance-grade BooCode if/when needed; HMAC log small lift candidate        |v2.0+ (audit log), speculative (full stack)       |
|`siropkin/budi` (tool, not lift)    |5-hook Claude Code taxonomy; HTTP daemon + SQLite + dashboard                                                         |MIT                                            |Install globally to observe Claude Code token costs; hook taxonomy as reference             |Immediate (install)                               |

-----

## Decisions log

- **v1.13.7 stability bundle uncovered two latent v1.13.1-A regressions (2026-05-22).** Investigation during the cosmetic-revert session surfaced: (1) `@ai-sdk/openai-compatible` defaults `includeUsage: false`, so `stream_options.include_usage` was never sent to llama-swap and `result.usage.inputTokens/outputTokens` resolved `undefined` — every assistant row had `tokens_used`/`ctx_used` NULL since v1.13.1-A shipped. One-line fix in `provider.ts`. (2) AI SDK v6 streaming occasionally emits a leading `\n` text-delta on tool-call-only turns; `content.length > 0` returned true for `"\n"`, producing an empty MessageBubble + ActionRow between every tool call. Fixed by trim guards in `MessageList.flatten` (`hasText`) and `MessageBubble` (`hasContent`). Plus: `buildMessagesPayload` now skips trailing empty/failed assistant rows (kills "Cannot have 2 or more assistant messages" rejections from the upstream), and `BUDGET_NO_AGENT` bumped 15→30 to match `BUDGET_READ_ONLY` (every tool today is read-only; the 15-cap was forward-looking). The class of bug is consistent: AI SDK v6 changes the streaming surface in ways that aren't caught by tsc or vitest — only production observability surfaces them. Argues for v1.13.11 WS-frame Zod schemas to catch the next round.
- **MCP and ACP roles locked per surface (2026-05-22).** **BooChat = MCP client only**, read-only tool consumer. **BooCoder = MCP client + MCP server + ACP client (host) + ACP agent (driveable)** — full matrix. Hard rule: BooChat MCP config must never enable a write-capable server (the read-only invariant overrides protocol convenience). BooCoder's ACP client role **replaces the raw-PTY dispatch plan for any agent that supports ACP** (opencode `opencode acp`, goose `goose acp`); claude/pi/smallcode stay on PTY fallback. The protocol pattern that justifies the full BooCoder matrix: ACP clients auto-forward their MCP `context_servers` to the dispatched agent (per goose docs) — one MCP config surface drives every dispatched agent. BooCoder MCP-server role exposes `boocoder.create_task`, `boocoder.list_pending_changes`, `boocoder.apply`, etc. so external opencode-in-Termius sessions become BooCoder-aware without going through BooCoder's UI. BooCoder ACP-agent role (`boocoder acp`) lets Zed/JetBrains/Avante.nvim drive BooCoder as their agent — outbound exposure, lowest priority of the four roles. **Reference materials**: anthropics `mcp-builder` skill (4-phase build workflow + 10-question eval framework), opencode MCP/ACP docs as JSON-schema reference, goose ACP docs for the `context_servers` auto-forward pattern, `agentclientprotocol.com` spec — but note remote ACP (HTTP/WS) is still WIP, BooCoder's ACP client must use stdio for v1.
- **BooCode monorepo locked as 3-surface structure (2026-05-22, updated 2026-05-25).** `/opt/boocode/`: BooChat = `apps/server` + `apps/web` (:9500), BooCoder = `apps/coder` (:9502, shipped v2.0, host systemd v2.1.0), BooTerm = `apps/booterm` (:9501). All share Postgres database `boochat`.
- **Single shared database `boochat` (shipped v2.0).** Docker service `boocode_db`. Enables cross-surface joins (coder task → chat → term session).
- **Mount strategy: blanket `/opt:rw`, policy enforcement at the write-tool layer (2026-05-22).** Per-project scoping is logic, not mount. Path-guard correctness becomes the highest-priority test target for v2.0 — fuzz it, property-test it, every traversal-attack pattern.
- **External CLI agents (`opencode` / `claude` / `goose` / `pi`) live on the host, not in containers (2026-05-22).** BooCoder shells out via local-exec PTY (`node-pty`, host shell). Host install means inherit Sam's existing `~/.opencode/`, `~/.claude/`, `~/.config/goose/` configs without re-mounting. Containerize later only if a concrete reason emerges.
- **STRATEGIC PIVOT (2026-05-22): Build a Paseo-equivalent dispatcher inside BooCode. Lift patterns, not code.** Sam wants BooCode to function like Paseo without using Paseo itself. **Paseo (getpaseo/paseo) is AGPL-3.0** — incompatible with BooCode's MIT license and its network-served deployment at `code.indifferentketchup.com`. Vendoring Paseo code would force BooCode to become AGPL. Solution: **reproduce the architecture in BooCode's existing Fastify + TS + PostgreSQL + React stack, using only license-clean patterns**. Full target architecture documented in the new "Paseo-equivalent dispatcher inside BooCode" section at the top of this document. **Primary architectural template: `Dominic789654/agent-hub` (#48)** — Apache-2.0, license-clean, captures the exact three-process model (board server + dispatcher + assistant terminal) and the schema (tasks/projects/templates/pipelines/human_inbox) BooCode should reproduce. **Critical context-management primitive: Roo Code Boomerang Tasks pattern (#46)** — orchestrator with intentional capability restriction, down-pass/up-pass context discipline, no implicit inheritance. **Observation pattern: Claude Code hooks** (siropkin/budi #51 reference) — register BooCode as the hook receiver to get real-time visibility without wrapping the agent. **Phasing:** Phase 1 single-agent PTY dispatch → Phase 2 PostgreSQL queue + worker → Phase 3 Boomerang `new_task` tool → Phase 4 multi-agent + worktrees + CLI → Phase 5 pipelines + dashboard → Phase 6 handoff/loop/orchestrator skills. **This is now the dominant roadmap direction**, ahead of v1.12.x debugger fixes (queued) and v1.13/v1.14 batch work (deferred until Paseo-equivalent Phases 1–2 are scoped).
- **BooCoder agent layer: both Option A AND Option B, full-featured (2026-05-22).** Earlier May 18 chat recommended Option A (thin orchestration shell over OpenCode) as the path forward but explicitly called the choice not-locked. Sam's call this session: ship **both** paths in the same BooCoder surface. **Option B / in-process loop** handles interactive write work with native tools + pending-changes UI (v2.0 plandex pattern still applies). **Option A / PTY dispatch** handles parallel/batch work where Sam wants to A/B opencode vs claude vs goose vs pi against the same task in separate worktrees. User picks per task. This supersedes the May 18 "reframe Batch 14 as OpenCode orchestration UI" recommendation — both paths now coexist.
- **Paseo (getpaseo/paseo) is the reference design, not a catalog code lift (2026-05-22).** AGPL-3.0 + 4k stars + 6-package TypeScript monorepo (server / app / cli / desktop / relay / website). The architecture is the lift: daemon + clients split, child-process agent orchestration, WebSocket protocol, `paseo run/ls/attach/send` CLI shape, `--worktree feature-x` flag, `/paseo-handoff` / `/paseo-loop` / `/paseo-orchestrator` skills. **Do not vendor code.** Read the README and the `skills/` directory's three skill files for design reference; reimplement in BooCode's MIT stack. The skills' shape (named `/handoff`, `/loop`, `/orchestrator` operations) is non-copyrightable; lift the shape.
- **Embeddings dropped from BooCode** (May 2026). Replaced RAG with file-view tools + sidecar analyzers.
- **opencode promoted to Tier A** (2026-05-20). The compaction port (v1.11.0) made it clear opencode is not just "the agent Sam uses" — it's the canonical reference implementation for everything BooCode is rebuilding through v1.15. Five algorithms identified for lift (compaction, doom-loop, repairToolCall, runLoop, permission evaluate) plus truncate.ts and MCP client. **Update 2026-05-22:** truncate.ts shipped v1.13.5; doom-loop, repairToolCall, compaction, prune all shipped; runLoop + permission still queued for v1.14/v1.15.
- **OpenCode canonical repo is `anomalyco/opencode`, NOT `sst/opencode` (corrected 2026-05-22).** Sam confirmed: the prior catalog entry's "anomalyco is a rebranded mirror, use sst as canonical" was inverted. Development moved to anomalyco; sst/opencode is the predecessor lineage. `anomalyco/opencode` `dev` branch is now the active source for every algorithm lift through v1.15. All 15 catalog references rewritten in this session.
- **Original Batch 11 (aider PageRank port) replaced** by codecontext sidecar approach.
- **Original Batch 12 (codebase indexer w/ Harrier) removed.** No embedding infrastructure.
- **Original Batch 13 (OpenHands event log) replaced** by v1.13 parts table (opencode pattern). Same outcome, different shape.
- **Original Batch 12 (cline plan/act mode) absorbed into v1.15** (opencode permission ruleset). Same outcome, wildcard rules instead of mode enum.
- **Aider's `repomap.py` port dropped.** Codecontext supersedes it. Aider contribution narrows to the `.scm` query files only.
- **Globstar role re-scoped.** Not an architect tool — parked for future verify-before-commit gate.
- **codeprysm role re-scoped.** Taxonomy reference only. Embedding half rejected.
- **AI SDK adoption deferred to v1.13.** Hand-roll opencode's repairToolCall pattern in v1.12 first. **Update 2026-05-22:** v1.12 deferred the repairToolCall hand-roll entirely; both AI SDK v6 adoption AND repairToolCall shipped together in v1.13.1-A/v1.13.3 — cleaner outcome than the two-step plan.
- **`tool_choice='required'` confirmed supported** by llama-swap (qwen3.6-35b-a3b-mxfp4, 2026-05-20). Repair tool call is viable.
- **`anomalyco/opencode` confirmed canonical (2026-05-22).** Earlier confusion about whether `sst/opencode` or `anomalyco/opencode` was the active fork is resolved: anomalyco is where active development continues. Use `anomalyco/opencode` for all algorithm lifts.
- **Reviewed 2026-05-22 (cline, kilocode, prompt-tower, auggie, augment-agent, augment-swebench-agent, codecompanion.nvim, junie, cody-public-snapshot, qodo-ai/{agents,qodo-cover,open-aware,qodo-skills}).** Three real lifts emerged:
  - **Qodo `agent.toml` schema** (`output_schema`, `exit_expression`, `execution_strategy`) → land in AGENTS.md at v1.14+.
  - **qodo-cover record/replay LLM harness** → re-implement (don't vendor — AGPL) as a Vitest fixture plugin at v1.13+.
  - **augment-swebench-agent ensembler** → optional v2.0+ verify-gate layer above pending-changes (plandex pattern).
  - **qodo-skills PR-resolver state machine** → BooCoder v2.0+ tool.
- **ACP added to v2.x watch list.** Zed's Agent Client Protocol is the analog of MCP for client↔agent. Not in any current batch; revisit only if BooCode wants to expose itself to Zed/Neovim/Termius beyond the web UI. **Reference implementations bracket the protocol:** codecompanion.nvim (#28) is the client side, zed-industries/codex-acp (#31) is the server-side adapter. The codex-acp README confirms ACP's full feature surface (context @-mentions, images, permission-gated tool calls, edit review, TODO lists, slash commands, client MCP servers) matches features BooCode already has internally — adopting ACP would be transport translation, not feature build.
- **kilocode and Cline skipped as code sources** (entry #20). Orchestrator/sub-agent pattern is already covered by cline (#7) and agent-framework (#15).
- **Junie skipped permanently.** No usable source.
- **Cody parked.** Multi-repo context fetcher is the only interesting piece; overkill for single-repo BooCode.
- **prompt-tower skipped.** AGPL VS Code extension; nothing novel that continue's ignore lift + universal XML wrapping doesn't already cover.
- **tiktoken-rs and calloop rejected (2026-05-22).** Both are Rust and Zed-stack-specific. tiktoken-rs additionally fails the model check — Qwen/Gemma/Nemotron don't use OpenAI's BPE encodings, so token counts would be wrong by 10–30%. **Source of truth for token counts on llama-swap models is `POST /tokenize` on llama-server**; no client-side tokenizer library needed. Do not re-evaluate either repo.
- **taste-skill accepted as Tier B vendor candidate (2026-05-22).** MIT, SKILL.md format already matches BooCode v1.12 standard, 18k+ stars, framework-agnostic. Two real wins: the 100+ anti-slop ban list (specific font/color/layout failure modes LLMs default to) and the 3-dial parameterization pattern (reusable beyond design). **Gated on a diff against the existing `frontend-design` SKILL** to avoid duplication before vendoring. Real value lands with BooCoder v2.0+ when write tools generate frontend code for Sam's projects (DubDrive, BooLab, Fathom, etc.).
- **costrict skipped, OpenSpec accepted (2026-05-22).** costrict is Apache-2.0 but the top contributors are Roo Code maintainers and the codebase has `.roo/`/`.rooignore`/`.roomodes` — same Cline-lineage VS Code extension shape BooCode rejected at kilocode (#20). The novel surface costrict ships is its **OpenSpec integration**, which is a separate repo. **OpenSpec is the real find:** it formalizes the spec-governed dispatch workflow Sam already uses (per-change folder with proposal/specs/design/tasks artifacts, slash commands per agent, artifact-lifecycle gates). Start by adopting just the directory structure for BooCode's own batch docs (zero-dep documentation reformat); evaluate full CLI adoption later. **Tracked for v1.13.x or v1.14**, not blocking v1.12.0.
- **agents.md noted but not evaluated.** costrict's README acknowledges `agentsmd/agents.md` as a partner. The name and shape strongly suggest it's the canonical source of the AGENTS.md convention BooCode v1.12 already adopted. Worth a future drive-by to confirm, but not blocking anything.
- **zeroshot accepted as Tier B pattern reference (2026-05-22).** MIT, multi-agent orchestration above coding-agent CLIs (Claude Code, Codex, OpenCode, Gemini CLI). **Sits at Paseo's layer, not BooCode's.** Five pattern lifts: complexity-classification conductor, blind-validation invariant (separate agent context verifies — doesn't see worker's history), crash-safe SQLite ledger, three-tier isolation taxonomy (none/worktree/Docker), JSON cluster templates. **The blind-validation invariant is the single most important architectural idea** zeroshot adds — fills the missing piece in plandex/OpenHands/cline patterns where the same agent writes and judges its own work. Lands at BooCode v1.13/v1.14 as an AGENTS.md design principle, then at v2.0+ as a real verify gate above pending-changes. **Separately:** zeroshot is a candidate Paseo-successor if Paseo ever needs replacement; that's a Paseo-scope decision, not BooCode-scope.
- **toprank rejected (2026-05-22).** SEO/SEM domain — wrong category for BooCode. Sam runs developer infrastructure, not marketing sites. Skill format is the same one BooCode v1.12 already uses; no novel pattern.
- **AgentLint accepted as high-value immediate-application reference (2026-05-22).** MIT, 31 evidence-backed repo-quality checks. Most useful catalog entry for *the present moment* — applies directly to every CLAUDE.md/AGENTS.md across Sam's homelab (BooCode, BooLab, HLH, indifferent-broccoli, paseo, etc.) without needing any code lift or version dependency. Specific data points from 265 versions of Anthropic's Claude Code system prompt are immediately actionable: trim emphasis-keyword density, target 60–120 line CLAUDE.md sweet spot, SHA-pin Actions, ensure `.env`/`CLAUDE.local.md` are gitignored. **Recommend a single audit pass session against BooCode's instruction files** before any further skill work lands. Optional plugin install for ongoing audits is a v1.12.x post-merge call.
- **awesome-vibe-coding surveyed (2026-05-22).** 60+ tools across 10 sections. **No new catalog entries promoted from the list.** Already-covered items: Cline, Roo Code, Continue, Prompt Tower, Augment, aider, Codex CLI, Gemini CLI. Skipped on category: 18 Web Builders, 4 Editor/IDEs, mobile/desktop builders. **Real leads tracked for next review pass:** `block/goose` (multi-model local agent framework), `eyaltoledano/claude-task-master` (task decomposition algorithm), `ai-christianson/RA.Aid` and the underlying `LangGraph` framework (workflow graphs in production), `automata/aicodeguide` (AI-first methodology). Do not re-evaluate the rejected items.
- **aaif-goose/goose (formerly block/goose) added as Tier B reference (2026-05-22).** Apache-2.0, 45.2k stars, recently moved to Linux Foundation's Agentic AI Foundation. Rust + TypeScript. Native ACP, 15+ providers including Ollama, MCP support for 70+ extensions. **Sits at Paseo's layer, not BooCode's.** Skip code (wrong stack); track as reference for ACP-protocol implementations and the multi-provider abstraction pattern. Ships `.claude/`, `.codex/`, `.cursor/` skill directories — confirms the cross-agent skill-emission pattern noticed in autohand/code-cli (#33).
- **memovai/memov accepted as Tier B reference (2026-05-22).** MIT, Python. Shadow `.mem` timeline tracks prompts + context + plan + file changes at every agent interaction; zero pollution to `.git`. MCP-exposed. `validate_commit` MCP tool detects context drift between prompt and actual changes. **Direct match for BooCode's reviewer-architect pattern.** Lift the MCP-tool shape (`snap`, `mem_history`, `mem_jump`, `validate_commit`) as reference for v1.13+ `view_session_history` feature and v2.0+ verify gate. Don't vendor Python code into Fastify/TS BooCode.
- **bhouston/mycoder rejected (2026-05-22).** MIT, TypeScript, 566 stars, **stale** (last release Mar 2025). Standard CLI coding agent — Claude/OpenAI/Ollama, MCP, parallel sub-agents. Functionally a less-mature opencode. Sam already uses opencode for this role. One UX pattern noted (Ctrl+M mid-stream corrections) but BooCode/opencode/Claude Code all have chat-based interruption. Skip.
- **ai-christianson/RA.Aid accepted as Tier B pattern reference (2026-05-22).** Apache-2.0, Python, 2.2k stars. **Three-stage architecture (Research / Planning / Implementation) on LangGraph** with per-stage model routing (`--research-provider`, `--planner-provider`, `--expert-provider`) + "expert tool" called only when needed for hard reasoning. **Aligns directly with Sam's qwopus27b/qwen3-coder routing.** Lift the three-stage AGENTS.md design and expert-tool escape hatch at v1.14+; don't lift LangGraph (wrong stack); never enable `--cowboy-mode` equivalent (opposite of BooCode's no-autonomous-commit rule).
- **Kirill89/reviewcerberus rejected as code, CoV logged as pattern (2026-05-22).** Closed-source Docker distribution (license not in registry). Multi-provider (Bedrock/Anthropic/Ollama/Moonshot), accepts `guidelines.md`, **Chain-of-Verification mode** to reduce false positives. CoV is the only takeaway — per-finding verification primitive, complementary to zeroshot's blind-validation (per-workflow #37) and bernstein's lineage chains (per-artifact #49). Stackable.
- **autohandai/code-cli rejected (2026-05-22).** 56 stars, COMMERCIAL.md present (commercial license restriction likely). Standard ReAct CLI agent with no novel pattern vs opencode. Cross-agent skill emission (copies skills between `~/.claude/skills/`, `~/.codex/skills/`, `~/.autohand/skills/`) is the only interesting bit — same pattern goose (#41) does. Skip.
- **Roo Code Boomerang Tasks accepted as Tier B pattern reference (2026-05-22, Sam-flagged).** Roo Code itself rejected (already covered via #20 kilocode and #35 costrict — VS Code/Cline lineage). Three architectural patterns lifted: **(1) Orchestrator with intentional capability restriction** — cannot read/write/MCP/shell, only delegates, preventing context poisoning. **(2) Down-pass/up-pass context discipline** — no implicit inheritance, parent passes context down via `new_task` message, subtask passes summary up via `attempt_completion` result only. **(3) Explicit precedence override clause** baked into subtask prompts. Together these sharpen zeroshot's blind-validation (#37) into a both-directions principle. Lands at v1.13/v1.14 as AGENTS.md design, v2.0+ as real delegation mechanics.
- **eyaltoledano/claude-task-master pattern accepted, code rejected (2026-05-22).** **MIT + Commons Clause** makes BooCode (self-hosted developer chat) a competing product — no code vendoring. 25.7k stars, JS/TS. Three patterns worth lifting independently in BooCode's own MIT code: **(1) Tiered tool-loading via env var** (`TASK_MASTER_TOOLS=core|standard|all|custom`, 7/15/36 tools, ~5k/10k/21k tokens) — direct fit for `BOOCODE_TOOLS` at v1.12.x or v1.13. **(2) Three model roles** (main/research/fallback) — same pattern as RA.Aid (#44), complementary evidence. **(3) PRD-as-source-of-truth** at `.taskmaster/docs/prd.txt` formalizes Sam's spec-governed work convention.
- **Dominic789654/agent-hub tracked, not lifted (2026-05-22).** Apache-2.0, Python 100% stdlib-only (no FastAPI/SQLAlchemy/Pydantic — zero supply chain surface), 1 star, v0.1.0 March 2026. Local-first multitask board for routing/observing code-assistant work across repos. SQLite queueing, dependency-aware dispatch, **human inbox**, dashboard at `/app`. **Architecturally what Paseo wants to grow into.** Too early to vendor; track for next pass. The stdlib-only constraint is a useful lens to evaluate BooCode/BooLab dependency footprint.
- **sipyourdrink-ltd/bernstein tracked as compliance-grade reference (2026-05-22).** License needs verification before any lift (`/LICENSE` should be checked directly). 262 stars, Python. Same layer as zeroshot (#37) and agent-hub (#48), but with **audit-grade compliance** as differentiator: HMAC-chained audit log, signed agent cards (Ed25519/EdDSA + JCS), per-artifact lineage (producer + inputs + prompt SHA + model + cost), customer-key signing for DORA/NIS2/EU AI Act Article 12, air-gap deploy, deterministic scheduler, one git worktree per agent, cost-aware routing bandit. **Over-spec for Sam's current homelab work** but the right shape if BooCode ever needs to produce audit evidence. The **HMAC-chained audit log** is a small lift-friendly pattern even today.
- **vorn-run/vorn rejected as code, pattern noted (2026-05-22).** MIT, Electron + TypeScript, 24 stars, alpha. Multi-agent grid UI for Claude Code/Copilot/Codex/OpenCode/Gemini. Each agent in its own PTY. Task queue + kanban + workflow automation + headless execution + inline diff review with structured-feedback-back-to-agent + worktree isolation + MCP server. **Wrong stack** (Electron desktop UI vs BooCode's Fastify/TS+React SPA). Pattern note: **PTY-per-agent + worktree-per-task + inline-diff-feedback-loop** is the canonical shape for multi-agent orchestration above real CLI agents; same architectural choice Paseo made.
- **siropkin/budi accepted as tooling, not catalog entry (2026-05-22).** MIT, Rust, single 6MB binary, sub-millisecond hook latency. **WakaTime for Claude Code** — tracks tokens, costs, prompts, file activity, sub-agent spawns in local SQLite, dashboard at `localhost:7878/dashboard`. **Recommend immediate install** (`budi init --global`) for Claude Code session observability. The **5-hook Claude Code event taxonomy** (`SessionStart`, `UserPromptSubmit`, `PostToolUse`, `SubagentStart`, `Stop`) is the canonical reference and worth knowing when BooCode v2.0+ designs its own hook system.
- **GeiserX/LynxPrompt tracked as architectural reference, code off-limits (2026-05-22).** **GPL-3.0 makes vendoring incompatible with BooCode's MIT licensing.** 27 stars, Next.js + PostgreSQL + Prisma. Self-hostable platform for managing AGENTS.md / CLAUDE.md / .cursor/rules / slash commands across **30+ AI assistant formats**. Single blueprint, export to N formats. Federated marketplace. The concept fits Sam's situation (5+ project CLAUDE.md/AGENTS.md files maintained separately) but the **manual AgentLint (#39) audit pass is the right ROI today** rather than adopting a full platform. If consolidation ever needed, reimplement the format-adapter pattern in MIT-licensed BooCode code, don't vendor.
- **ShipWithAI/claude-code-mastery noted as docs reference (2026-05-22).** **CC BY-NC-SA 4.0** content + MIT code examples. 9 stars. Free 16-phase / 55-module / 136-lesson course on Claude Code workflows. **Two structural patterns worth borrowing:** (1) **7-block module structure** (WHY → CONCEPT → DEMO → PRACTICE → CHEAT SHEET → PITFALLS → REAL CASE) as a docs template; (2) **phase list as coverage checklist** to diff against Sam's own CLAUDE.md/AGENTS.md files — combine with AgentLint (#39) for a single audit pass. Don't redistribute content (NC license).
