boocode/boocode_roadmap.md

BooCode v1.x — Roadmap

Last updated: 2026-05-16

Overview

BooCode is a standalone code-chat tool at /opt/boocode/. Read-only by design — pick a project, chat with a local LLM that has file-inspection tools, get streaming responses over WebSocket.

Live at https://code.indifferentketchup.com (Caddy → Authelia → Tailscale → 100.114.205.53:9500).

Architectural commitments:

• No embeddings. The model uses file-view tools (view_file, list_dir, grep, find_files) + sidecar analyzers (codecontext, codesight). Walked away from the RAG pipeline May 2026.
• Read-only in v1.x. Write tools land in BooCoder (separate container, post-v1.x).
• One Postgres (boocode_db), one frontend SPA, container-per-service for new capabilities.

External code lifted from / referenced in: see boocode_code_review.md for full inventory.

---

Batch summary

Batch	Theme	Status	Branch / Notes
1	Markdown, Copy + Regen, tok/s + ctx, AI naming	✅ Done	v1.1-batch1 merged
2	Sidebar restructure	✅ Done	v1.1-batch2 merged
3	Pane system, FileBrowserPane + Shiki, cross-tab	✅ Done	v1.1-batch3 merged
3.5	Chip infrastructure, @file, line-select	✅ Done	merged
4 (v1.2)	Chats inside sessions, right-rail, /compact, archive, force-send	✅ Done	merged
4.1–4.4	Project archive, sidebar context, Gitea API, bootstrap	✅ Done	merged
v1.5 cleanup	resolveProjectPath, BOOTSTRAP_ROOT, vitest pin	✅ Done	merged
v1.6 mobile	Drawer, single-pane, long-press, IME-safe, pull-to-refresh, swipe-close	✅ Done	merged
v1.6.1	RightRail mobile wrapper fix	✅ Done	merged
Tool-loop bump	MAX_TOOL_LOOP_DEPTH 5→15	✅ Done	merged
v1.6.2	Workspace + Session+Project headers + ChatTabBar new-chat + RightRail mobile drawer	🔄 In flight	v1.6.2-mobile-ui-fixes
v1.8 mobile tabs	Bottom-sheet pane switcher + cross-tab pane_status WS sync + StatusDot on tabs	Next up	v1.8-mobile-tabs; hand-rolled sheet
9 (REORDERED, DECOUPLED)	Agents (Tier 2): AGENTS.md, per-agent temp/tools, picker in ChatInput toolbar	✅ Implemented, uncommitted	six builtins; on main awaiting commit
5	Fork message, delete message, header polish	Planned
6	Drag-drop file + paste-as-attachment	Planned	thin extension of 3.5 chips
7	Settings drawer: system prompt, web search toggle, agent entry	Planned	adds SettingsDrawer agent entry (Batch 9 deferred half)
8	Web search backend: SearXNG web_search + web_fetch	Planned
10	BooTerm: separate container, xterm.js + node-pty + tmux	Planned
11 — Architect: codebase map	codecontext sidecar + MCP tool wiring	Planned	from nmakod/codecontext
11b — Architect: repo health	call graph, circular deps, dead code	Planned	from spirituslab/codesight
12 — Tool approval + plan/act mode	Read-only invariant, per-tool gating	Planned	from cline
13 — Append-only event log	Replace messages-table semantics	Planned	from OpenHands V1
14 — BooCoder: pending changes	Sandboxed edit queue, atomic apply	Post-v1.x	from plandex
15 — BooCoder runtime isolation	Per-session Docker sandbox	Post-v1.x	from OpenHands
16 — Multi-provider LLM	Optional litellm-style abstraction	Optional	from pi-ai
17 — Workflow graphs	Multi-agent coordination	Far future	from microsoft/agent-framework concepts

Old Batch 12 (codebase indexer w/ Harrier embeddings) — REMOVED. Replaced by Batch 11/11b sidecar approach. See boocode_code_review.md decisions log.

Batch 9 reordered ahead of 5–8, 10. Picker mounts in ChatInput.tsx toolbar only. SettingsDrawer agent entry rolled into Batch 7 when it lands. No UI dependency on Batches 5/6/7, so it can ship anytime after v1.6.2.

---

Batch details (planned / new)

Batch 9 — Agents (Tier 2, DECOUPLED)

Spec: boocode_batch9.md with the deltas below.

Status: Next up after v1.6.2 merges. Decoupled from Batch 7.

Deltas from boocode_batch9.md:

1. Builtin defaults in agents.ts OMIT the model field. Resolution order makes session.model win when agent.model is null. Spec line 30 example is misleading — do not hardcode any model in builtins.
2. Builtin defaults are the six agents shipped in /opt/boocode/AGENTS.md: Code Reviewer, Debugger, Refactorer, Architect, Security Auditor, Prompt Builder. If project root AGENTS.md exists, only its agents show. If absent, show the six builtins.
3. AgentPicker mounts in ChatInput.tsx toolbar between ModelPicker and the + button. No SettingsDrawer.tsx or Header.tsx changes in this batch.
4. SettingsDrawer agent entry + Header active-agent badge moved to Batch 7.

Files to create:

• apps/server/src/services/agents.ts — parser, six builtin defaults, mtime-keyed cache.
• apps/server/src/routes/agents.ts — GET /api/projects/:id/agents.
• apps/web/src/components/AgentPicker.tsx — dropdown, matches ModelPicker pattern.

Files to modify:

• apps/server/src/schema.sql — ALTER TABLE sessions ADD COLUMN IF NOT EXISTS agent_id TEXT;
• apps/server/src/services/inference.ts — resolution order: effective_system_prompt, effective_model, effective_temperature, effective_tools from session + agent + project. Filter tools array against agent whitelist before sending to llama-swap.
• apps/server/src/routes/sessions.ts — PATCH accepts agent_id.
• apps/server/src/types/api.ts — Agent type, extend Session with agent_id.
• apps/web/src/api/client.ts, apps/web/src/api/types.ts — Agent type, api.agents.list(projectId).
• apps/web/src/components/ChatInput.tsx — mount AgentPicker.

Testing plan (manual, before locking temps):

• Drop /opt/boocode/AGENTS.md (six agents, no model field on any).
• For each of the 7 keeper models, switch session model and run the same target prompt against each agent. Log tok/s, instruction-following quality.
• Adjust per-agent temperature in AGENTS.md based on results.
• A/B candidates: qwen3.6-35b-a3b-mxfp4 (daily), qwopus3.6-35b-a3b-q4 (reasoning), qwopus3.5-27b-q4, qwen3.6-27b-ud-q4-xl, nemotron-3-nano-30b, gemma-4-26b-a4b-mxfp4, qwen3-coder-30b-apex.

Dependencies: v1.6.2 merged.

---

Batch 11 — Architect: codebase map (REVISED)

Inspiration / lift: nmakod/codecontext (MIT, Go binary).

What it gives BooCode: an architect-grade codebase overview without embeddings. Codecontext parses the repo with tree-sitter, extracts symbols, builds import/dependency relationships, and exposes the result via an MCP server with 8 tools. The model gets a structural map of any codebase on demand.

Why this replaces the original Batch 11 (aider PageRank port): codecontext is a finished binary in our stack language (Go), with watch mode, incremental updates, framework detection, and git-co-change-based semantic neighborhoods (no embeddings). The aider port would be reimplementing what codecontext already ships.

Scope:

• Add codecontext sidecar container to docker-compose.yml. Mount the project root read-only. One sidecar per BooCode instance — projects are addressed by absolute path.
• Wire each codecontext MCP tool into BooCode’s inference/tools.ts as a native tool the model can call:
• repo_overview(project_id) → codecontext get_codebase_overview
• repo_file_analysis(project_id, path) → get_file_analysis
• repo_symbol_info(project_id, symbol) → get_symbol_info
• repo_search_symbols(project_id, query) → search_symbols
• repo_dependencies(project_id, path) → get_dependencies
• repo_semantic_neighborhoods(project_id, path) → get_semantic_neighborhoods (git co-change)
• repo_framework_analysis(project_id) → get_framework_analysis
• path_guard.ts extension: incorporate continuedev/continue DEFAULT_SECURITY_IGNORE_FILETYPES so codecontext can’t surface .env, .pem, keys, etc.
• Fallback grammars: drop Aider-AI/aider‘s aider/queries/tree-sitter-*.scm files for any language codecontext doesn’t cover. Use them via an in-process tree-sitter wrapper only if a project needs an unsupported language. Defer wrapper build until that’s an actual gap.

Where it goes: new apps/server/src/architect/ directory. No new tables — codecontext maintains its own state on disk. New env: CODECONTEXT_URL=http://codecontext:8765 (MCP endpoint).

Decisions to make at recon time:

• Bundle the binary directly in the BooCode Dockerfile, or run codecontext as its own service? Sidecar is cleaner. Bundle is one less container.
• How does the model discover codecontext tools — register them statically in the tools registry, or proxy MCP tools/list at startup?

Dependencies: none. Can ship before Batches 5–10.

---

Batch 11b — Architect: repo health (NEW)

Inspiration / lift: spirituslab/codesight (MIT-ish, TS/Node).

What it gives BooCode: complement to Batch 11. Where codecontext answers “what is this codebase,” repo health answers “what’s wrong with this codebase.” Call graph, circular dependency detection, dead code flagging.

Scope:

• Port codesight’s analyze.mjs analyzer core into apps/server/src/architect/repo_health.ts. Drop the VS Code extension shell. Keep:
• Symbol extraction (already overlaps codecontext — call codecontext where possible, only redo what’s needed for graph edges).
• Call graph builder (function-to-function edges).
• Circular dependency detector.
• Dead code detector (exported symbols never imported or called).
• New tool: repo_health(project_id) returning { circular_dependencies: [...], dead_code: [...] }. Output respects codesight’s documented false-positive caveats (customElements.define, framework entry points, dynamic imports) — surface those in the tool description so the model doesn’t trust dead-code flags blindly.
• Cache results in boocode_db keyed by (project_id, file_hashes). Invalidate on file change via file-index hash check.

Decisions:

• Build it in-process (Node) vs spawn a CLI? In-process is simpler. Spawn matches codecontext sidecar pattern but adds latency.

Dependencies: Batch 11 merged (so we can reuse codecontext’s parse output where possible). Can be deferred until after Batches 5–10.

---

Batch 12 — Tool approval gating + plan/act mode

Inspiration / lift: cline/cline (Apache-2.0).

What it gives BooCode: per-session control over which tools the model can call. Lays the groundwork for BooCoder by building the gating mechanism before there are any write tools to gate.

Scope:

• New column sessions.tool_approval_mode TEXT — values: read_only (v1.x default), plan, act_auto, act_approve.
• New column sessions.approved_tools JSONB — per-session whitelist for act_approve mode.
• Tool registry refactor: tools tagged read_only or write. In read_only mode (v1.x), write tools never appear in the model’s tools array. In plan mode, same — write tools hidden, model produces a plan only. act_* modes unlock writes (post-v1.x).
• UI: mode picker in SettingsDrawer (Batch 7 dependency). Inline indicator in chat header.

Dependencies: Batch 7 (SettingsDrawer).

---

Batch 13 — Append-only event log

Inspiration / lift: OpenHands/OpenHands V1 (MIT).

What it gives BooCode: replaces the ad-hoc messages table semantics with a typed event stream. Unlocks rewind, time-travel, and clean handoff semantics for multi-agent flows.

Scope:

• New session_events table: (id, session_id, ts, kind, payload JSONB, parent_id). Event kinds: user_message, assistant_message, tool_call, tool_result, pane_action, mode_change, system.
• Existing messages table becomes a derived view over session_events for backward compatibility, then deprecated over a release.
• Inference loop emits events instead of mutating message rows.
• Frontend useSessionStream reducer rewritten to consume events.

Migration is non-trivial. Plan in a dedicated batch with explicit cutover window.

Dependencies: Batches 5 (fork/delete) and 7 (settings) merged. Must not be in flight with other backend work.

---

Batch 14 — BooCoder: pending changes

Inspiration / lift: plandex-ai/plandex (MIT).

What it gives BooCode: safe write tools. Edits queue in a virtual layer; nothing touches the filesystem until explicit /apply.

Scope:

• New container boocoder at 100.114.205.53:9502. Owns write tools (edit_file, create_file, delete_file, apply_pending, rewind).
• New table pending_changes (id, session_id, file_path, diff TEXT, status, created_at). Status: pending, applied, rejected.
• Tools execute against the pending-changes layer, not the filesystem. apply_pending is the only path that touches disk. rewind rolls back a pending-id back to disk state.
• BooCode chat container stays read-only (/opt:/opt:ro). BooCoder mounts /opt/repos:/opt/repos:rw and uses git worktree pattern from paseo for isolation.
• Frontend: new pane kind pending_diff shows the queued diff inline with Approve/Reject per chunk.

Dependencies: Batches 12 (gating) + 13 (events). Don’t start until both are live.

---

Batch 15 — BooCoder runtime isolation

Inspiration / lift: OpenHands/OpenHands (MIT).

What it gives BooCode: per-session Docker sandbox for BooCoder writes. Closes the /opt:ro mount risk identified in v1.x open items.

Scope:

• Per-session container spawned by BooCoder on first write. Container has only the project’s path mounted, not /opt.
• Container lifecycle: spawn on first write call, idle-timeout after 30 min, recreate on resume.
• Action execution server pattern: HTTP API inside the container, BooCoder calls in. Standard OpenHands runtime contract.

Dependencies: Batch 14.

---

Batch 16 — Multi-provider LLM abstraction

Inspiration / lift: earendil-works/pi pi-ai (MIT).

What it gives BooCode: optional non-llama-swap inference paths (Anthropic, OpenAI, Mistral direct). Currently we have one provider (llama-swap) and the existing streamCompletion is hardcoded to OpenAI-compatible at that endpoint.

Scope:

• Provider abstraction: interface LLMProvider { stream(req): AsyncIterator<Frame> }.
• Built-in: llama-swap (current), Anthropic, OpenAI (Codex-style).
• Per-session provider_id column.

Status: Optional. Skip unless a concrete need surfaces. llama-swap covers daily driver work.

---

Batch 17 — Workflow graphs

Inspiration / lift: microsoft/agent-framework (MIT) — concepts only.

What it gives BooCode: multi-agent coordination. Architect → Coder → Reviewer → Verifier handoffs orchestrated by a YAML-defined workflow.

Status: Far future. Read agent-framework’s docs/decisions/ ADRs. Don’t port code — Azure/.NET-heavy.

Dependencies: Batches 12 (modes), 13 (events). Realistically a v2.x topic.

---

Order of operations

Two tracks. Pick one to drive next.

Track A — Finish v1.x mobile + polish then agents:

• v1.6.2 ships (in flight)
• Batch 9 (agents) — decoupled, can land next; no UI dependency on 5/6/7
• Batches 5, 6, 7, 8 in order. Each is small, frontend-heavy, no architecture risk. Batch 7 absorbs SettingsDrawer agent entry.

Track B — Begin architect capabilities in parallel:

• Batch 11 (codecontext sidecar) — biggest single capability jump. Frontend stays the same; new tools appear to the model.
• Batch 11b (repo health) — follow-up.
• Batch 12 (gating) — sets up everything post-v1.x.

Recommendation: ship v1.6.2, then Batch 9 (agents) next so the test bed exists before Track A continues. Then Track A through Batch 7. Batch 11 can run in parallel with Batches 8–10 since 11 has no UI dependency.

---

Architecture target state

Containers

Container	Port	Mount	Purpose	Status
boocode	100.114.205.53:9500	/opt:/opt:ro	Chat + read-only tools + SPA	Live
boocode_db	127.0.0.1:5500	boocode_pgdata volume	Postgres 16-alpine	Live
codecontext	100.114.205.53:8765 (internal)	project root :ro	MCP server for architect tools	Batch 11
booterm	100.114.205.53:9501	/opt/repos:/opt/repos:rw	Terminals (tmux + node-pty)	Batch 10
boocoder	100.114.205.53:9502	per-session sandbox	Write tools	Batch 14

Schema additions

Batch 9: sessions.agent_id TEXT (nullable; references AGENTS.md by slug). Batch 11: none (codecontext stateless on disk). Batch 11b: repo_health_cache (project_id, file_hashes_sig, payload JSONB, created_at). Batch 12: sessions.tool_approval_mode, sessions.approved_tools. Batch 13: session_events; deprecate messages long-tail. Batch 14: pending_changes.

---

Lift sources (summary)

Full inventory in boocode_code_review.md. Headline items:

Source	Used for	Where
nmakod/codecontext (MIT, Go)	Architect: codebase map sidecar	Batch 11
spirituslab/codesight (MIT-ish, TS)	Architect: repo health analyzer	Batch 11b
Aider-AI/aider (Apache-2.0)	Fallback .scm grammars (60+ languages)	Batch 11 (fallback)
continuedev/continue (Apache-2.0)	DEFAULT_SECURITY_IGNORE_FILETYPES	Batch 11 prep
cline/cline (Apache-2.0)	Plan/Act mode pattern	Batch 12
plandex-ai/plandex (MIT)	Pending-changes data model	Batch 14
OpenHands/OpenHands (MIT)	Event log + sandbox runtime	Batches 13, 15
aimasteracc/tree-sitter-analyzer (MIT)	Outline-first response patterns	Reference
earendil-works/pi (MIT)	Multi-provider LLM	Batch 16 (optional)
rshah515/claude-code-subagents (MIT)	Reference for builtin agent prompts	Batch 9 (six builtins)
microsoft/agent-framework (MIT)	Workflow concepts	Batch 17 (far future)

---

Decisions log

• Embeddings dropped from BooCode. Replaced RAG with file-view tools + sidecar analyzers.
• Original Batch 11 (aider PageRank port) replaced by codecontext sidecar approach.
• Original Batch 12 (codebase indexer w/ Harrier) removed entirely. No embedding infrastructure in BooCode v1.x.
• Globstar parked — not an architect tool, future verify-before-commit candidate only.
• codeprysm rejected — embedding-based; node/edge taxonomy noted as reference if we ever build our own graph.
• Batch 9 decoupled from Batch 7 (2026-05-16). AgentPicker mounts in ChatInput.tsx toolbar only. SettingsDrawer agent entry and Header active-agent badge moved to Batch 7. Builtin defaults shipped: six agents (Code Reviewer, Debugger, Refactorer, Architect, Security Auditor, Prompt Builder) with no model field — session model wins by default.

Follow-ups (post-ship docs / cleanup)

• After v1.8.2 ships: Add explicit max_tool_calls: 30 to all 6 agents in /data/AGENTS.md and /opt/boocode/AGENTS.md. Purely for documentation/discoverability — defaults handle behavior identically (all 6 agents use only read-only tools, default is already 30).

---

Workflow

Each batch:

1. Verify previous batch merged.
2. Dispatch via Paseo to Claude Code at /opt/boocode.
3. Claude Code recon → blocking questions → implement → hand back.
4. Compliance review in separate Claude chat.
5. Deploy: docker compose up --build -d.
6. Smoke test.
7. Sam commits and pushes.

Sam reviews all diffs. Sam commits. Never git pull/push/commit on his behalf.