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 in v1.x — pick a project, chat with a local LLM that has file-inspection tools, get streaming responses over WebSocket. Built May 2026 after the in-boolab BooCode mode stalled.

v1 shipped in a single Claude Code session. v1.1 onwards is a batched build-out. Original Batch 1–10 plan was reordered mid-stream — chats-inside-sessions, archive, and fork/delete work was prioritized over the mobile pass.

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

---

Version summary

Version	Theme	Status	Notes
v1.0	Initial scaffold, read-only tools, WS streaming	✅ Done	Shipped in one Claude Code session
v1.1-batch1	Markdown, Copy + Regen, tok/s + ctx, AI chat naming	✅ Merged	—
v1.1-batch2	Sidebar restructure: projects → sessions, max 5 + “view all”	✅ Merged	—
v1.1-batch3	Pane system, FileBrowserPane + Shiki, chat→file click, cross-tab	✅ Merged	—
v1.1-batch3.5	Chip infrastructure, @file picker, line-select-attach	✅ Merged	—
v1.2	Chats inside sessions refactor, right-rail, /compact, archive, force-send	✅ Merged	Replaced original “Batch 4 = mobile” plan
v1.2-project-ux	Project archive UX, sidebar context menu, full-bootstrap, Gitea API	✅ Merged	—
v1.3	Tab-close + chat-archive	✅ Merged	—
v1.4	Fork from message + delete message + header polish + housekeeping	✅ Merged	Was original “Batch 5”
v1.5	Refactor splits, vitest harness (23 tests), error-log surfacing, /opt:ro + BOOTSTRAP_ROOT, persistent context-window tracker	✅ Merged	—
v1.5.1	Bootstrap hotfix: git in container, SSH keypair, known_hosts, SSH URL rewrite, /opt/projects label	✅ Merged	4a9f207
v1.6-mobile-pass	Mobile pass: drawer, pane stacking, long-press, swipe-to-close, pull-to-refresh, IME safety, safe-area, tap targets + H1 path-guard fix	✅ Merged	57c883b..943ae7d (6 commits)
v1.6.1-cleanup	Mostly audit-only; one fix shipped: RightRail max-md:hidden wrapper. Audit reports for secrets, stale code, panes, mount scope, hand-rolled patterns deferred to follow-ups	✅ Merged	6a9fe18
v1.6.2-mobile-ui-fixes	Mobile UI polish from device testing: kill single-pane navigator chrome, header rework, “New chat” in long-press menu, RightRail as mobile drawer (reverts v1.6.1 wrapper)	🔄 Hand-back received, uncommitted	—
v1.7	Drag-drop + paste-as-attachment (chip infra extension)	Planned	Was Batch 6
v1.8	Settings drawer (system prompt per project + session, web search toggle)	Planned	Was Batch 7
v1.9	Web search backend: SearXNG web_search + web_fetch tools	Planned	Was Batch 8
v1.10	Agents (Tier 2): AGENTS.md, per-agent model/temp/tools, picker	Planned	Was Batch 9
v1.11	BooTerm: separate container, xterm.js + node-pty + tmux, terminal pane	Planned	Was Batch 10

---

Version details

v1.1-batch1 — Message polish ✅

Markdown (react-markdown + remark-gfm), Copy + Regenerate, tok/s + context counter, AI session naming.

Key decisions:

• sessions.name (not title).
• enable_thinking: false + max_tokens: 30 for Qwen3 utility calls.
• messages_deleted WS frame added for multi-tab regen.
• In-app event bus (sessionEvents.ts, module-scope Set<Listener>).

Schema: messages.tokens_used, messages.ctx_used, messages.ctx_max, messages.started_at, messages.finished_at.

---

v1.1-batch2 — Sidebar restructure ✅

Projects as expandable groups, up to 5 recent sessions per project, “View all (N)”, GET /api/sidebar, useSidebar singleton hook.

Key decisions:

• useSidebar module-scope singleton.
• localStorage['boocode.sidebar.expanded'].
• session_renamed payload {session_id, name}.

---

v1.1-batch3 — Pane system ✅

session_panes table, pane CRUD with transactional position-shift, Workspace + tab strip + drag-to-reorder (native HTML5), ChatPane (extracted), FileBrowserPane (tree + Shiki + filter), chat→file click, PaneTab context menu, file_ops + file_index shared services, broker user channel + /ws/user, session_updated, session_loaded, idempotent default-Chat-pane backfill.

Schema: session_panes (id, session_id, position, kind CHECK, state JSONB).

---

v1.1-batch3.5 — Chips + @file + line-select ✅

Attachment type + flattenToMessage + LANG_MAP, AttachmentChip, AttachmentPreviewModal, ChatInput chip-row, hand-rolled @file mention popover, line-select-attach in FileBrowserPane via local FileViewer, FileBrowserPane filter upgrade (empty=tree, non-empty=flat).

---

v1.2 — Chats inside sessions ✅

Originally planned as the mobile pass. Reshuffled: structural refactor — chats inside sessions, right-rail, /compact (chat’s own model summarizes via kind='compact' system message), force-send.

Schema: chats table, sessions.status, messages.chat_id, messages.kind (regular | compact).

---

v1.2-project-ux ✅

Full new-project bootstrap (mkdir + git init + .gitignore + first commit + Gitea remote + push), sidebar context menu (Rename / Archive / Open in Gitea), project landing page archived-list, Gitea API integration. Option B taken: BOOTSTRAP_ROOT env var, /opt stays read-only mount, /opt/projects writable.

Schema: projects.status, projects.archived_at.

Key decisions:

• execFile only, no exec shell strings.
• DB INSERT last in bootstrap sequence.
• Soft-fail on Gitea steps.
• Project Delete endpoint exists but stays unexposed (re-add INSERTs fresh row → FK cascade nukes history; archive is the safe pattern).

---

v1.3 — Tab close + chat archive ✅

Tab close UX cleanup, chat-level archive (separate from session archive).

---

v1.4 — Fork + delete + header polish ✅

Was originally planned as Batch 5.

Shipped: POST /api/sessions/:id/fork (deep copy messages up to target, new session in same project), DELETE /api/sessions/:id/messages/:id (cascading via messages_deleted frame), header breadcrumb (Projects → Project → Session), inline-editable session name, file path shown when File Browser pane is active, useActivePane hook.

---

v1.5 — Refactor + tests + security scoping + context tracker ✅

5-commit sequence:

1. Refactor: FileBrowserPane (865 → split with FileViewer extracted), Workspace, inference split.
2. Vitest harness: 23 tests covering routes + resolveProjectPath. Pinned to v3 (Vite 5 / vitest 4 incompatibility).
3. Error-log surfacing: dead-code removal from earlier H1/H2 audit items, structured error logs to client.
4. Mount scoping: /opt:/opt:ro + BOOTSTRAP_ROOT writable subdir. Container loses write to /opt proper.
5. Persistent context-window tracker: floating popover above chat input right edge, source = latest message_complete frame’s ctx_used / ctx_max, color-coded (neutral <60%, amber 60–85%, red 85%+), hides when ctx_max null.

Carried bug: resolveProjectPath whitelist-root bypass — discovered, asserted as “BEHAVIOR GAP” rather than silently patched. Fix landed in v1.6 (H1).

---

v1.5.1 — Bootstrap hotfix ✅ (4a9f207)

Dockerfile (git installed in container), docker-compose.yml, project_bootstrap.ts (SSH keypair, known_hosts, SSH URL Tailscale rewrite), CreateProjectModal.tsx, .gitignore. /opt/projects label clarified.

Known issue carried forward: dispatch used the in-repo secrets/boocode_gitea SSH key because the agent key was rejected. Key exposure flagged. Audit + rotation tracked in v1.6.1 below.

---

v1.6-mobile-pass ✅

Merged via 6 commits 57c883b..943ae7d (5 functional + 1 docs):

1. 57c883b chore: fix resolveProjectPath whitelist-root bypass (H1 — dropped real !== whitelistReal short-circuit; flipped the v1.5 BEHAVIOR GAP test; 23/23 pass).
2. a643b5f feat(mobile): viewport hook + sidebar drawer + hamburger headers (M1 + M2 + M6-header).
3. cd897d6 feat(mobile): single-pane stack + long-press tab menu + swipe-to-close (M3 + M4 + A2).
4. 273eeac feat(mobile): chat input keybinds + safe-area + tap targets + overflow safety (M5 + M6-bottom + M7 + M8).
5. 4b5b9b2 feat(mobile): pull-to-refresh sidebar list (A1).
6. 943ae7d docs: add v1.x roadmap snapshot (this file).

Decisions:

• H2 (roadmap update) handled in this file rather than by Claude Code.
• M5: mobile = button-only send, Enter inserts newline. Desktop unchanged. isComposing guard for CJK IME.
• M6: kept max-w-[1000px] (mobile naturally full-width below cap).
• URL state: ?pane=<paneId>. Bare URL resets activePaneIdx to 0.
• Long-press dispatches synthetic contextmenu on [data-tab-id], opening Radix ContextMenuTrigger at touch coords. iOS callout suppressed.
• SwipeablePaneTab: 60px threshold, bails if vertical >30px, opacity 1→0.4.
• A2 bundled with M3 in Commit 3 (structural coupling).
• Home.tsx no hamburger.

Deferred from v1.6 → rolled into v1.6.1-cleanup:

• RightRail still renders on mobile (~32px column).
• Secrets hygiene audit.
• ProjectSidebar.tsx and ChatTabBar.tsx share content from two commits each — use git add -p.

---

v1.6.1-cleanup ✅ (6a9fe18)

Shipped: RightRail wrapped in <div className="max-md:hidden contents"> so it's hidden entirely below the md breakpoint on mobile. (Note: v1.6.2 reverses this and replaces with a proper mobile drawer — see below.)

Audited but not shipped (queued for follow-ups):

• Secrets hygiene: secrets/boocode_gitea is NOT tracked; never committed to any branch; .gitignore already covers secrets/. Rotation is a Gitea-side action, no repo change needed.
• .bak files: 3 leftover from v1.5.1 (docker-compose.yml.bak-20260516, Dockerfile.bak-20260516, apps/web/src/components/CreateProjectModal.tsx.bak-20260516). Git-invisible via global ~/.gitignore_global (*.bak*). Decide per file.
• Unused exports: neither knip nor ts-prune installed. Proposal pending.
• Dead WS frames: session_renamed HAS a server publisher (routes/sessions.ts:140, added in v1.4) — the roadmap's "no server publisher" open item is STALE, crossed off. The InferenceFrame union still declares session_renamed as a type variant but no code publishes it on the per-session channel; trivial 1-line cleanup deferred.
• Unused imports: web tsc --noUnusedLocals --noUnusedParameters returns 0 warnings.
• useSessionStream refcount: opportunity confirmed (~90 lines diff to apply the useSidebar-style module-scope singleton pattern). Risk LOW. Queued for v1.6.2 or later.
• PATCH /api/panes/:id ownership: MOOT — endpoint does not exist (the pane REST API was never re-introduced after pane state moved to client-side localStorage in v1.2). Crossed off open items.
• Hand-rolled patterns vs library: 5 hand-rolled hooks/components total 336 lines. None duplicates anything in existing deps; library swap (@use-gesture, react-pull-to-refresh) not worth the dep cost yet.
• /opt:/opt:ro mount tightening: Two-option plan documented for v1.6.2 — Option A (per-project bind-mounts) or Option B (deny .env pattern in pathGuard). Option B is the simpler short-term fix.

---

v1.6.2-mobile-ui-fixes 🔄

Hand-back received, uncommitted on v1.6.2-mobile-ui-fixes. 4-commit sequence proposed:

1. fix(mobile): hide Split button + single-pane navigator chrome (G1 — wrap the Workspace Split row in !isMobile).
2. feat(mobile): rework Session and Project headers for narrow viewports (G2 — breadcrumb hidden sm:flex, session name cap max-w-[140px] sm:max-w-[280px], project page heading text-base sm:text-lg, “New session” icon-only on mobile).
3. feat(mobile): add "New chat" to tab long-press context menu (G3 — top of menu, separator, then existing items).
4. feat(mobile): right-rail as drawer on mobile, header toggle button (G4 option b — new useRightRailDrawer Context hook, RightRail renders as fixed w-[85vw] max-w-sm drawer on mobile, FolderTree button in Session header, reverts v1.6.1's max-md:hidden wrapper).

Decisions:

• G4 option b chosen: mobile file browsing IS useful; drawer pattern mirrors useSidebarDrawer.
• G2 single-row session-name+model layout (model picker right-aligned), per spec example.
• G3 "New chat" at top, separator, then Rename.
• G2 "New session" button: icon-only on mobile via <span className="hidden sm:inline">New session</span>.

Adjacent uncommitted change (not part of v1.6.2): MAX_TOOL_LOOP_DEPTH 5 → 15 in apps/server/src/services/inference.ts. Sam-authored, sitting in working tree on v1.6.2-mobile-ui-fixes. NOT on main as of this update. Commit separately.

---

v1.7 — Drag-drop + paste (planned, was Batch 6)

Depends on: v1.6.1 merged.

Scope (trimmed — chip infra exists from v1.1-batch3.5):

• Drag-drop files onto ChatInput → chip via addAttachment({kind: 'file', source: 'drop'}).
• Paste >8 lines → chip via addAttachment({kind: 'paste', source: 'paste'}). ≤8 lines inline.
• Drop overlay (dashed border + “Drop to attach”).
• Client-side 5 MB cap + binary detection (null-byte check in first 8KB).
• Max 10 attachments shared cap.
• Folder drop rejected. Image paste rejected. Binary files rejected with toast.

Frontend only.

---

v1.8 — Settings drawer (planned, was Batch 7)

Depends on: header gear (already in v1.4).

Scope:

• Right-side drawer (hand-rolled, no shadcn Sheet). Tabbed: Session + Project.
• Session tab: system prompt, web search toggle, model picker, session name.
• Project tab: default system prompt, default web search, project name, root path (read-only), delete project (consider whether to expose given the cascade concern).
• Resolution: session.system_prompt OR project.default_system_prompt OR "".
• Project defaults applied at session create (copied), not retroactively.
• Web search toggle persistent per session (sessions.web_search_enabled).

Schema: sessions.web_search_enabled, projects.default_system_prompt, projects.default_web_search.

---

v1.9 — Web search backend (planned, was Batch 8)

Depends on: v1.8.

Scope:

• web_search tool → SearXNG at http://100.114.205.53:8888/search?format=json, top-N {title, url, snippet}.
• web_fetch tool, regex HTML strip (no cheerio), 50KB cap.
• Tools conditionally included based on session.web_search_enabled.
• ToolCallCard.tsx renders results as clickable URL list, web_fetch as text preview.
• Env: SEARXNG_URL, WEB_FETCH_TIMEOUT_MS, WEB_FETCH_MAX_BYTES.

---

v1.10 — Agents (planned, was Batch 9)

Depends on: v1.8.

Scope:

• Tier 2 agents: system prompt + model + temperature + tools whitelist per agent.
• AGENTS.md (OpenCode-compatible): ## Agent Name blocks with YAML frontmatter.
• Three builtin defaults (Investigator, Architect, Reviewer) when no AGENTS.md.
• If AGENTS.md exists, only its agents shown.
• Agent picker in ChatInput toolbar + SettingsDrawer.
• Tools whitelist enforced at inference layer. BooChat agents read-only.
• File parsed on demand with mtime cache.
• Mid-conversation agent switch allowed; old messages retain their tool history.

Schema: sessions.agent_id TEXT.

---

v1.11 — BooTerm (planned, was Batch 10)

Depends on: v1.1-batch3 (pane system), v1.8 (settings drawer pattern).

Scope:

• New container booterm at 100.114.205.53:9501. Fastify + node-pty + tmux.
• Caddy path-based routing: /api/term/* + /ws/term/* → booterm.
• Shared boocode_db.
• Per-session tmux (bc-<session_id>), per-pane tmux window (term-<pane_id>).
• xterm.js terminal pane. New kind = 'terminal' in session_panes CHECK.
• PTY over binary WebSocket. Resize via tmux resize-window.
• Workspace mount: /opt/repos:/opt/repos:rw. BooCode chat container keeps /opt:/opt:ro.
• Send-to-terminal from chat: select text → right-click → “Send to terminal”.
• tmux persistence across WS reconnects, page refreshes, container restarts.
• No chroot/namespace isolation. Acceptable single-user homelab.

New app: apps/booterm/.

---

Architecture

Containers (current + planned)

Container	Port	Mount	Purpose	Status
boocode	100.114.205.53:9500	/opt:/opt:ro + /opt/projects:rw	Chat + read-only tools + SPA	Live
boocode_db	127.0.0.1:5500	boocode_pgdata	Postgres 16-alpine (shared)	Live
booterm	100.114.205.53:9501	/opt/repos:/opt/repos:rw	Terminal sessions	v1.11
boocoder	TBD	/opt/repos:/opt/repos:rw	Write tools	Post-v1.x

URL routing (target state after v1.11)

code.indifferentketchup.com
├── /                           → boocode (SPA)
├── /api/chat/*, /ws/chat/*     → boocode :9500
├── /api/term/*, /ws/term/*     → booterm :9501
├── /api/coder/*, /ws/coder/*   → boocoder (future)
└── /ws/user                    → boocode :9500

Database

Single Postgres boocode_db. All containers share. Projects shared. Sessions container-specific.

Current schema (post v1.5.1):

projects
├── id UUID PK
├── name TEXT
├── root_path TEXT
├── status TEXT                  (v1.2-project-ux: active | archived)
├── archived_at TIMESTAMPTZ      (v1.2-project-ux)
├── default_system_prompt TEXT   (v1.8)
├── default_web_search BOOLEAN   (v1.8)
└── created_at TIMESTAMPTZ

sessions
├── id UUID PK
├── project_id UUID FK → projects
├── name TEXT
├── model TEXT
├── system_prompt TEXT
├── status TEXT                  (v1.2: active | archived)
├── web_search_enabled BOOLEAN   (v1.8)
├── agent_id TEXT                (v1.10)
├── created_at TIMESTAMPTZ
└── updated_at TIMESTAMPTZ

chats                            (v1.2)
├── id UUID PK
├── session_id UUID FK → sessions
├── name TEXT
├── status TEXT
├── created_at TIMESTAMPTZ
└── updated_at TIMESTAMPTZ

messages
├── id UUID PK
├── session_id UUID FK → sessions
├── chat_id UUID FK → chats      (v1.2)
├── kind TEXT                    (v1.2: regular | compact)
├── role TEXT
├── content TEXT
├── tool_calls JSONB
├── tool_results JSONB
├── status TEXT
├── last_seq INTEGER
├── tokens_used INTEGER          (v1.1-batch1)
├── ctx_used INTEGER             (v1.1-batch1)
├── ctx_max INTEGER              (v1.1-batch1)
├── started_at TIMESTAMPTZ       (v1.1-batch1)
├── finished_at TIMESTAMPTZ      (v1.1-batch1)
└── created_at TIMESTAMPTZ

session_panes                    (v1.1-batch3)
├── id UUID PK
├── session_id UUID FK → sessions (CASCADE)
├── position INTEGER
├── kind TEXT CHECK (chat | file_browser | terminal)
├── state JSONB
└── created_at TIMESTAMPTZ

settings
├── k TEXT PK
└── v TEXT

Reusable patterns

Pattern	Where	Used by
In-app event bus	sessionEvents.ts	All batches. Module-scope Set<Listener>.
Singleton hooks	useSidebar.ts	Module-scope shared state.
User-channel WS broker	broker.ts + useUserEvents.ts	Cross-tab lifecycle. One WS per tab.
clock_timestamp()	All INSERT/UPDATE	Never NOW() in new code.
Additive schema only	schema.sql	ADD COLUMN IF NOT EXISTS, CREATE TABLE IF NOT EXISTS.
Idempotent backfills	schema.sql	INSERT ... WHERE NOT EXISTS.
enable_thinking: false	auto_name.ts	Required for Qwen3 utility calls.
pathGuard	tools/*, file_ops.ts	Realpath + project root enforcement.
Shared file_ops.ts	tools.ts, routes/projects.ts	Same core for inference tools and UI.
File index (file_index.ts)	routes/projects.ts	rg --files + mtime cache.
useViewport	hooks/useViewport.ts (v1.6)	matchMedia, SSR-safe.
useSidebarDrawer	hooks/useSidebarDrawer.tsx (v1.6)	Context + auto-close on route change.
Hand-rolled long-press	hooks/useLongPress.ts (v1.6)	500ms touchstart timer, dispatches synthetic contextmenu.
Hand-rolled pull-to-refresh	hooks/usePullToRefresh.ts (v1.6)	80px threshold, 600ms min hold.
Hand-rolled swipe	components/SwipeablePaneTab.tsx (v1.6)	60px threshold, vertical bail at 30px.

---

Tech stack

Layer	Tech
Backend	Node 20 + Fastify + @fastify/websocket + @fastify/static + zod + pg
Frontend	React + Vite + Tailwind v4 + shadcn nova preset
Inference	llama-swap http://100.101.41.16:8401 (OpenAI-compatible)
Search	SearXNG http://100.114.205.53:8888 (v1.9)
Syntax	Shiki (github-dark)
Terminal	xterm.js + node-pty + tmux (v1.11)
Auth	Remote-User from Authelia via Caddy forward_auth
Containerization	Docker Compose, Node 20-alpine, multi-stage, ripgrep apk, git apk (v1.5.1)
DB	Postgres 16-alpine, loopback 127.0.0.1:5500
Networking	Tailscale mesh, Caddy (DO droplet), Authelia SSO
Code hosting	Gitea git.indifferentketchup.com
Tests	vitest v3 (pinned, Vite 5 / vitest 4 incompatible)

---

Known open items

• useSessionStream refcount. Two ChatPanes = two WS. Apply singleton pattern. Audited in v1.6.1, queued.
• /opt:/opt:ro mount exposes all .env files. Whitelist scope before BooCoder. Two-option plan documented in v1.6.1 audit; ship in v1.6.2 or v1.7.
• secrets/boocode_gitea in repo working tree. Never committed (git-invisible via global ignore). Rotate the Gitea-side key when convenient; no repo action required.
• Dormant in-boolab BooCode mode. Reference only.
• BooCoder container. Post-v1.x.

Closed since last update:

• session_renamed no server WS publisher — server publishes via broker.publishUser from routes/sessions.ts:140 (added in v1.4). Confirmed in v1.6.1 audit.
• PATCH /api/panes/:id lacks session-ownership check — endpoint does not exist; the pane REST API was never re-introduced after v1.2 moved pane state to localStorage.

---

Dependency graph

v1.0 (initial)
  │
  ▼
v1.1-batch1 (markdown)
  │
  ▼
v1.1-batch2 (sidebar)
  │
  ▼
v1.1-batch3 (panes) ────────────────────────┐
  │                                          │
  ▼                                          │
v1.1-batch3.5 (chips) ──────┐                │
  │                          │                │
  ▼                          │                │
v1.2 (chats-in-sessions)     │                │
  │                          │                │
  ▼                          │                │
v1.2-project-ux              │                │
  │                          │                │
  ▼                          │                │
v1.3 (tab-close)             │                │
  │                          │                │
  ▼                          │                │
v1.4 (fork+delete+header) ◄──┼────────────────┘
  │                          │
  ▼                          │
v1.5 (refactor+tests+ctx)    │
  │                          │
  ▼                          │
v1.5.1 (bootstrap hotfix)    │
  │                          │
  ▼                          │
v1.6-mobile-pass             │
  │                          │
  ▼                          │
v1.6.1-cleanup               │
  │                          │
  ▼                          │
v1.6.2-mobile-ui-fixes ◄─────┘
  │
  ▼
v1.7 (drag-drop) ◄── v1.1-batch3.5
  │
  ▼
v1.8 (settings)
  │
  ├──▶ v1.9 (web search)
  │
  ├──▶ v1.10 (agents)
  │
  └──▶ v1.11 (BooTerm) ◄── v1.1-batch3

---

Workflow

1. Verify previous version merged to main.
2. Dispatch prompt via Paseo (Claude Code runs at /opt/boocode).
3. Claude Code recon → blocking questions → implement → hand back.
4. Review hand-back in separate Claude chat (spec compliance, code quality, drift, stale code).
5. Deploy: docker compose up --build -d.
6. Smoke test per the hand-back’s plan.
7. Sam commits manually, pushes to Gitea, merges to main.
8. Next version.

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