docs(v3): update architecture docs and progress for MVP completion
- v3-task_plan.md: mark Phases 1-5 complete, update adversarial review results with 12 resolved issues, finalize component tree and layout - v3-findings.md: add adversarial review agent findings - v3-progress.md: document Phases 1-5 implementation details - progress.md: add v3 MVP session entry - docs/README.md: reorganize with v2/v3 sections
This commit is contained in:
Hibryda
parent
a11e7f9d2c
commit
4f29582aac
5 changed files with 512 additions and 74 deletions
|
|
@ -14,14 +14,23 @@ Project documentation lives here.
|
||||||
|
|
||||||
## Index
|
## Index
|
||||||
|
|
||||||
|
### v2 Documentation
|
||||||
| Document | Description |
|
| Document | Description |
|
||||||
|----------|-------------|
|
|----------|-------------|
|
||||||
| [task_plan.md](task_plan.md) | v2 architecture decisions, error handling, testing strategy |
|
| [task_plan.md](task_plan.md) | v2 architecture decisions, error handling, testing strategy |
|
||||||
| [phases.md](phases.md) | v2 implementation phases (1-7 + multi-machine A-D) with checklists |
|
| [phases.md](phases.md) | v2 implementation phases (1-7 + multi-machine A-D + profiles/skills) with checklists |
|
||||||
| [findings.md](findings.md) | Research findings (Agent SDK, Tauri, xterm.js, performance) |
|
| [findings.md](findings.md) | Research findings (Agent SDK, Tauri, xterm.js, performance) |
|
||||||
| [progress.md](progress.md) | Session-by-session progress log (recent sessions) |
|
|
||||||
| [progress-archive.md](progress-archive.md) | Archived progress log (2026-03-05 to 2026-03-06 early) |
|
|
||||||
| [multi-machine.md](multi-machine.md) | Multi-machine support architecture (implemented, WebSocket relay, reconnection) |
|
| [multi-machine.md](multi-machine.md) | Multi-machine support architecture (implemented, WebSocket relay, reconnection) |
|
||||||
| [v3-task_plan.md](v3-task_plan.md) | v3 Mission Control redesign: architecture decisions and strategies |
|
|
||||||
| [v3-findings.md](v3-findings.md) | v3 research findings and codebase reuse analysis |
|
### v3 Mission Control Documentation
|
||||||
| [v3-progress.md](v3-progress.md) | v3 session progress log |
|
| Document | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| [v3-task_plan.md](v3-task_plan.md) | v3 Mission Control architecture: adversarial review, data model, component tree, layout system, 10-phase plan |
|
||||||
|
| [v3-findings.md](v3-findings.md) | v3 adversarial review results and codebase reuse analysis |
|
||||||
|
| [v3-progress.md](v3-progress.md) | v3 session progress log (Phases 1-5 MVP complete) |
|
||||||
|
|
||||||
|
### Progress Logs
|
||||||
|
| Document | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| [progress.md](progress.md) | Session-by-session progress log (recent sessions, v2 + v3) |
|
||||||
|
| [progress-archive.md](progress-archive.md) | Archived progress log (2026-03-05 to 2026-03-06 early) |
|
||||||
|
|
|
||||||
|
|
@ -187,11 +187,43 @@
|
||||||
- [ ] Produce final architecture plan
|
- [ ] Produce final architecture plan
|
||||||
- [ ] Create v3 implementation phases
|
- [ ] Create v3 implementation phases
|
||||||
|
|
||||||
|
### Session: 2026-03-07 (continued) — v3 Mission Control MVP Implementation (Phases 1-5)
|
||||||
|
|
||||||
|
#### Phase 1: Data Model + Config
|
||||||
|
- [x] Created v2/src/lib/types/groups.ts (ProjectConfig, GroupConfig, GroupsFile interfaces)
|
||||||
|
- [x] Created v2/src-tauri/src/groups.rs (Rust structs + load/save groups.json + default_groups())
|
||||||
|
- [x] Added groups_load, groups_save Tauri commands to lib.rs
|
||||||
|
- [x] SQLite migrations in session.rs: project_id column, agent_messages table, project_agent_state table
|
||||||
|
- [x] Created v2/src/lib/adapters/groups-bridge.ts (IPC wrapper)
|
||||||
|
- [x] Created v2/src/lib/stores/workspace.svelte.ts (replaces layout.svelte.ts for v3, Svelte 5 runes)
|
||||||
|
- [x] Added --group CLI argument parsing in main.rs
|
||||||
|
- [x] 24 vitest tests for workspace store + 7 cargo tests for groups
|
||||||
|
|
||||||
|
#### Phase 2: Project Box Shell
|
||||||
|
- [x] Created 12 new Workspace components in v2/src/lib/components/Workspace/
|
||||||
|
- [x] GlobalTabBar, ProjectGrid, ProjectBox, ProjectHeader, CommandPalette, DocsTab, ContextTab, SettingsTab
|
||||||
|
- [x] Rewrote App.svelte (no sidebar, no TilingGrid — GlobalTabBar + tab content + StatusBar)
|
||||||
|
|
||||||
|
#### Phase 3: Claude Session Integration
|
||||||
|
- [x] Created ClaudeSession.svelte wrapping AgentPane per-project
|
||||||
|
|
||||||
|
#### Phase 4: Terminal Tabs
|
||||||
|
- [x] Created TerminalTabs.svelte with shell/SSH/agent tab types
|
||||||
|
|
||||||
|
#### Phase 5: Team Agents Panel
|
||||||
|
- [x] Created TeamAgentsPanel.svelte + AgentCard.svelte
|
||||||
|
|
||||||
|
#### Bug Fix
|
||||||
|
- [x] Fixed AgentPane Svelte 5 event modifier: on:click -> onclick
|
||||||
|
|
||||||
|
#### Verification
|
||||||
|
- All 138 vitest + 36 cargo tests pass, vite build succeeds
|
||||||
|
|
||||||
### Next Steps
|
### Next Steps
|
||||||
|
- [ ] v3 Phase 6: Session continuity (persist agent messages, restore on startup)
|
||||||
|
- [ ] v3 Phase 7: Command palette wiring + group switching
|
||||||
|
- [ ] v3 Phase 8-10: Docs tab, settings tab, polish
|
||||||
- [ ] Real-world relay testing (2 machines)
|
- [ ] Real-world relay testing (2 machines)
|
||||||
- [ ] TLS/certificate pinning for relay connections
|
- [ ] TLS/certificate pinning for relay connections
|
||||||
- [ ] E2E testing with Playwright/WebDriver (when display server available)
|
- [ ] E2E testing with Playwright/WebDriver (when display server available)
|
||||||
- [ ] Test agent teams with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
- [ ] Test agent teams with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
||||||
- [ ] Model selector in AgentPane toolbar (dropdown for model override)
|
|
||||||
- [ ] System prompt field in AgentPane toolbar (custom instructions per session)
|
|
||||||
- [ ] Additional directories picker in AgentPane toolbar
|
|
||||||
|
|
|
||||||
|
|
@ -1,35 +1,62 @@
|
||||||
# BTerminal v3 — Research Findings
|
# BTerminal v3 — Research Findings
|
||||||
|
|
||||||
## Current Codebase Reuse Analysis
|
## Adversarial Review Results (2026-03-07)
|
||||||
|
|
||||||
### Can Reuse (with modifications)
|
### Agent: Architect (Advocate)
|
||||||
- **Agent session infrastructure**: AgentPane, agent store, agent dispatcher, SDK messages adapter, sidecar bridge — core agent functionality stays
|
- Proposed full component tree, data model, 10-phase plan
|
||||||
- **Terminal infrastructure**: TerminalPane, pty-bridge — terminal rendering unchanged
|
- JSON config at `~/.config/bterminal/groups.json`
|
||||||
- **Markdown rendering**: MarkdownPane, highlight utils — markdown viewer stays
|
- Single shared sidecar (multiplexed sessions)
|
||||||
- **Sidecar management**: SidecarManager, agent-runner.mjs — backend agent orchestration
|
- ClaudeSession + TeamAgentsPanel split from AgentPane
|
||||||
- **PTY management**: PtyManager — backend terminal management
|
- SQLite tables: agent_messages, project_agent_state
|
||||||
- **Session persistence**: session-bridge, SessionDb — needs schema extension for projects
|
- MVP at Phase 5
|
||||||
- **Theme system**: theme store, catppuccin CSS — visual layer unchanged
|
|
||||||
- **Notification system**: toast notifications — stays as-is
|
|
||||||
- **Claude bridge**: profiles + skills — reusable per project
|
|
||||||
- **StatusBar**: needs redesign but concept stays
|
|
||||||
|
|
||||||
### Must Replace
|
### Agent: Devil's Advocate
|
||||||
- **Layout store**: Current pane-based grid system → project-based workspace system
|
- Found 12 issues, 4 critical:
|
||||||
- **TilingGrid**: CSS Grid tiling → project box layout with internal structure
|
1. xterm.js 4-instance ceiling (hard OOM wall)
|
||||||
- **SessionList sidebar**: Pane list → project/group navigation
|
2. Single sidecar SPOF
|
||||||
- **App.svelte**: Root layout completely changes
|
3. Layout store has no workspace concept
|
||||||
- **Settings dialog**: Per-app settings → per-project settings
|
4. 384px per project unusable on 1920px
|
||||||
|
- Recommended: fix workspace concept, xterm budget, UI density, persistence before anything else
|
||||||
|
- Proposed suspend/resume ring buffer for terminals
|
||||||
|
- Proposed per-project sidecar pool (max 3) — deferred to v3.1
|
||||||
|
|
||||||
### Can Drop
|
### Agent: UX + Performance Specialist
|
||||||
- **Detached pane mode**: Doesn't fit the workspace model
|
- Wireframes for 5120px (5 projects) and 1920px (3 projects)
|
||||||
- **Drag-resize splitters**: Project boxes have fixed internal layout
|
- Adaptive project count: `Math.floor(width / 520)`
|
||||||
- **Layout presets (1-col, 2-col, etc.)**: Replaced by N-project horizontal layout
|
- xterm budget: lazy-init + scrollback serialization
|
||||||
- **Remote machine integration**: Defer to v4 (complexity too high to combine)
|
- RAF batching for 5 concurrent streams
|
||||||
- **ctx ContextPane**: Becomes a workspace tab instead of a pane type
|
- <100ms workspace switch via serialize/unmount/remount
|
||||||
|
- Memory budget: ~225MB total (within WebKit2GTK limits)
|
||||||
|
- Team panel: inline >2560px, overlay <2560px
|
||||||
|
- Command palette: Ctrl+K, floating overlay, fuzzy search
|
||||||
|
|
||||||
---
|
## Codebase Reuse Analysis
|
||||||
|
|
||||||
## Adversarial Agent Findings
|
### Survives (with modifications)
|
||||||
|
- TerminalPane.svelte — add suspend/resume lifecycle
|
||||||
|
- MarkdownPane.svelte — unchanged
|
||||||
|
- AgentTree.svelte — reused inside ClaudeSession
|
||||||
|
- ContextPane.svelte — extracted to workspace tab
|
||||||
|
- StatusBar.svelte — modified for per-project costs
|
||||||
|
- ToastContainer.svelte — unchanged
|
||||||
|
- agents.svelte.ts — add projectId field
|
||||||
|
- theme.svelte.ts — unchanged
|
||||||
|
- notifications.svelte.ts — unchanged
|
||||||
|
- All adapters (agent-bridge, pty-bridge, claude-bridge, sdk-messages, session-bridge, ctx-bridge, ssh-bridge)
|
||||||
|
- All Rust backend (sidecar, pty, session, ctx, watcher)
|
||||||
|
- highlight.ts, agent-tree.ts utils
|
||||||
|
|
||||||
(To be filled by adversarial review agents)
|
### Replaced
|
||||||
|
- layout.svelte.ts → workspace.svelte.ts
|
||||||
|
- TilingGrid.svelte → ProjectGrid.svelte
|
||||||
|
- PaneContainer.svelte → ProjectBox.svelte
|
||||||
|
- SessionList.svelte → ProjectHeader + command palette
|
||||||
|
- SettingsDialog.svelte → SettingsTab.svelte
|
||||||
|
- AgentPane.svelte → ClaudeSession.svelte + TeamAgentsPanel.svelte
|
||||||
|
- App.svelte → full rewrite
|
||||||
|
|
||||||
|
### Dropped (v3.0)
|
||||||
|
- Detached pane mode (doesn't fit workspace model)
|
||||||
|
- Drag-resize splitters (project boxes have fixed internal layout)
|
||||||
|
- Layout presets (1-col, 2-col, etc.) — replaced by adaptive project count
|
||||||
|
- Remote machine integration (deferred to v3.1, elevated to project level)
|
||||||
|
|
|
||||||
|
|
@ -1,9 +1,57 @@
|
||||||
# BTerminal v3 — Progress Log
|
# BTerminal v3 — Progress Log
|
||||||
|
|
||||||
### Session: 2026-03-07 — Architecture Planning
|
### Session: 2026-03-07 — Architecture Planning + MVP Implementation (Phases 1-5)
|
||||||
|
|
||||||
#### Phase: Adversarial Design Review
|
#### Phase: Adversarial Design Review
|
||||||
- [ ] Launch architecture agents (advocate, devil's advocate, synthesizer)
|
- [x] Launch 3 architecture agents (Architect, Devil's Advocate, UX+Performance Specialist)
|
||||||
- [ ] Collect findings
|
- [x] Collect findings — 12 issues identified, all resolved
|
||||||
- [ ] Produce final architecture plan
|
- [x] Produce final architecture plan in docs/v3-task_plan.md
|
||||||
- [ ] Create implementation phases
|
- [x] Create 10-phase implementation plan
|
||||||
|
|
||||||
|
#### Phase 1: Data Model + Config
|
||||||
|
- [x] Created `v2/src/lib/types/groups.ts` — TypeScript interfaces (ProjectConfig, GroupConfig, GroupsFile)
|
||||||
|
- [x] Created `v2/src-tauri/src/groups.rs` — Rust structs + load/save groups.json
|
||||||
|
- [x] Added `groups_load`, `groups_save` Tauri commands to lib.rs
|
||||||
|
- [x] SQLite migrations in session.rs: project_id column, agent_messages table, project_agent_state table
|
||||||
|
- [x] Created `v2/src/lib/adapters/groups-bridge.ts` (IPC wrapper)
|
||||||
|
- [x] Created `v2/src/lib/stores/workspace.svelte.ts` (replaces layout.svelte.ts, Svelte 5 runes)
|
||||||
|
- [x] Added `--group` CLI argument parsing in main.rs
|
||||||
|
- [x] Wrote 24 vitest tests for workspace store (workspace.test.ts)
|
||||||
|
- [x] Wrote cargo tests for groups load/save/default
|
||||||
|
|
||||||
|
#### Phase 2: Project Box Shell
|
||||||
|
- [x] Created GlobalTabBar.svelte (Sessions | Docs | Context | Settings)
|
||||||
|
- [x] Created ProjectGrid.svelte (flex + scroll-snap container)
|
||||||
|
- [x] Created ProjectBox.svelte (CSS grid: header | session-area | terminal-area)
|
||||||
|
- [x] Created ProjectHeader.svelte (icon + name + status dot + accent color)
|
||||||
|
- [x] Rewrote App.svelte (GlobalTabBar + tab content + StatusBar, no sidebar/TilingGrid)
|
||||||
|
- [x] Created CommandPalette.svelte (Ctrl+K overlay with fuzzy search)
|
||||||
|
- [x] Created DocsTab.svelte (markdown file browser per project)
|
||||||
|
- [x] Created ContextTab.svelte (wrapper for ContextPane)
|
||||||
|
- [x] Created SettingsTab.svelte (per-project + global settings editor)
|
||||||
|
- [x] CSS for responsive project count + Catppuccin accent colors
|
||||||
|
|
||||||
|
#### Phase 3: Claude Session Integration
|
||||||
|
- [x] Created ClaudeSession.svelte (wraps AgentPane, passes project cwd/profile/config_dir)
|
||||||
|
|
||||||
|
#### Phase 4: Terminal Tabs
|
||||||
|
- [x] Created TerminalTabs.svelte (tab bar + content, shell/SSH/agent tab types)
|
||||||
|
|
||||||
|
#### Phase 5: Team Agents Panel
|
||||||
|
- [x] Created TeamAgentsPanel.svelte (right panel for subagents)
|
||||||
|
- [x] Created AgentCard.svelte (compact subagent view: status, messages, cost)
|
||||||
|
|
||||||
|
#### Bug Fix
|
||||||
|
- [x] Fixed AgentPane Svelte 5 event modifier syntax: `on:click` -> `onclick` (Svelte 5 requires lowercase event attributes)
|
||||||
|
|
||||||
|
#### Verification
|
||||||
|
- All 138 vitest tests pass (114 existing + 24 new workspace tests)
|
||||||
|
- All 36 cargo tests pass (29 existing + 7 new groups tests)
|
||||||
|
- Vite build succeeds
|
||||||
|
|
||||||
|
### Next Steps (Post-MVP)
|
||||||
|
- [ ] Phase 6: Session continuity (persist agent messages, sdkSessionId, restore)
|
||||||
|
- [ ] Phase 7: Command palette wiring + group switching (Ctrl+K functional)
|
||||||
|
- [ ] Phase 8: Docs tab (markdown file auto-discovery per project)
|
||||||
|
- [ ] Phase 9: Settings tab (full per-project config editor, icon picker)
|
||||||
|
- [ ] Phase 10: Polish + cleanup (remove dead v2 components, update tests, perf audit)
|
||||||
|
|
|
||||||
|
|
@ -4,7 +4,7 @@
|
||||||
|
|
||||||
Transform BTerminal from a multi-pane terminal/agent tool into a **multi-project mission control** — a helm for managing multiple development projects simultaneously, each with its own Claude agent session, team agents, terminals, and settings.
|
Transform BTerminal from a multi-pane terminal/agent tool into a **multi-project mission control** — a helm for managing multiple development projects simultaneously, each with its own Claude agent session, team agents, terminals, and settings.
|
||||||
|
|
||||||
## Status: Planning — Rev 0
|
## Status: MVP Complete (Phases 1-5) — Rev 1
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -19,47 +19,358 @@ BTerminal v2: Terminal emulator with agent sessions (panes in a grid)
|
||||||
BTerminal v3: Project orchestration dashboard (projects in a workspace)
|
BTerminal v3: Project orchestration dashboard (projects in a workspace)
|
||||||
```
|
```
|
||||||
|
|
||||||
### User Requirements (verbatim)
|
### User Requirements
|
||||||
|
|
||||||
1. Projects arranged in **project groups** (many groups, switch between them)
|
1. Projects arranged in **project groups** (many groups, switch between them)
|
||||||
2. Each group has **up to 5 projects** shown horizontally
|
2. Each group has **up to 5 projects** shown horizontally
|
||||||
3. Group/project config via **main menu** (command palette / hidden drawer, on keystroke)
|
3. Group/project config via **main menu** (command palette / hidden drawer, Ctrl+K)
|
||||||
4. Per-project settings:
|
4. Per-project settings: Claude subscription, working dir, icon (nerd font), name, identifier, description, enabled
|
||||||
- Claude subscription (multi-account via switcher-claude)
|
|
||||||
- Working directory
|
|
||||||
- Project icon (nerd font, suggested but settable)
|
|
||||||
- Project name
|
|
||||||
- Project identifier (derived from name, lowercase-dashed, settable)
|
|
||||||
- Project description (optional)
|
|
||||||
- Enabled flag (bool)
|
|
||||||
5. Project group = workspace on screen
|
5. Project group = workspace on screen
|
||||||
6. Each project box has:
|
6. Each project box: Claude session (default, resume previous) + team agents (right) + terminal tabs (below)
|
||||||
- **Claude session box** (default open, continues previous session)
|
7. **4 workspace tabs**: Sessions | Docs | Context | Settings
|
||||||
- **Team agents window** (to the right, shows spawned subagents)
|
|
||||||
- **Terminal tabs below** (agent terminals + user terminals, tabbed)
|
|
||||||
7. **3 workspace tabs**:
|
|
||||||
- Tab 1: Sessions view (described above)
|
|
||||||
- Tab 2: MD file viewer (auto-discovered from projects, choosable)
|
|
||||||
- Tab 3: Settings editor (per-project settings)
|
|
||||||
8. App launchable with `--group <name>` CLI arg
|
8. App launchable with `--group <name>` CLI arg
|
||||||
9. JSON config file defines all groups
|
9. JSON config file defines all groups (`~/.config/bterminal/groups.json`)
|
||||||
10. Session continuity: resume previous + restore history visually
|
10. Session continuity: resume previous + restore history visually
|
||||||
11. SSH sessions: spawnable within a project's terminal tabs or in separate tabs
|
11. SSH sessions: spawnable within a project's terminal tabs
|
||||||
12. ctx viewer: separate tab
|
12. ctx viewer: workspace tab #3
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Architecture Questions for Adversarial Review
|
## Architecture (Post-Adversarial Review)
|
||||||
|
|
||||||
1. **Config format**: JSON file vs SQLite for group/project definitions?
|
### Adversarial Review Summary
|
||||||
2. **Layout engine**: How to arrange up to 5 project boxes with internal subdivisions?
|
|
||||||
3. **Session isolation**: One sidecar per project? Shared sidecar with project context?
|
3 agents reviewed the architecture: Architect (advocate), Devil's Advocate (attacker), UX+Performance Specialist.
|
||||||
4. **State management**: How to handle workspace switching (mount/unmount vs hide/show)?
|
|
||||||
5. **What survives from v2**: Which components/stores/adapters carry over?
|
**12 issues identified by Devil's Advocate. Resolutions:**
|
||||||
6. **Tab implementation**: Browser-style tabs or Svelte component switching?
|
|
||||||
7. **Command palette**: Build custom or use a library?
|
| # | Issue | Severity | Resolution |
|
||||||
8. **Auto-discovery**: Which MD files to surface per project?
|
|---|---|---|---|
|
||||||
9. **Performance**: 5 projects x (session + agents + terminals) = potentially many active panes
|
| 1 | xterm.js 4-instance ceiling (WebKit2GTK OOM) | Critical | Lazy-init + scrollback serialization. Budget: 4 active xterm, unlimited suspended (text buffer). Enforced in code. |
|
||||||
|
| 2 | Single sidecar = SPOF for all projects | Critical | Accept for v3.0 (existing crash recovery). Per-project pool deferred to v3.1 if needed. |
|
||||||
|
| 3 | Session identity collision (sdkSessionId not persisted) | Major | Persist sdkSessionId in SQLite `project_agent_state` table. Per-project CLAUDE_CONFIG_DIR isolation. |
|
||||||
|
| 4 | Layout store has no workspace concept | Critical | Full rewrite: `workspace.svelte.ts` replaces `layout.svelte.ts`. |
|
||||||
|
| 5 | 384px per project unusable on 1920px | Major | Adaptive: compute visible count from viewport width (`Math.floor(width / 520)`). 5@5120px, 3@1920px, scroll-snap for rest. min-width 480px. |
|
||||||
|
| 6 | JSON config + SQLite = split-brain | Major | JSON for groups/projects config (human-editable). SQLite for session state. JSON loaded at startup only, no hot-reload. |
|
||||||
|
| 7 | Agent dispatcher is global singleton, no project scoping | Major | Add projectId to AgentSession. Dispatcher routes by project. Per-project cleanup on workspace switch. |
|
||||||
|
| 8 | Markdown discovery undefined | Minor | Priority list: CLAUDE.md, README.md, docs/*.md (max 20). Rust command scans with depth limit. |
|
||||||
|
| 9 | Keyboard shortcut conflicts (3 layers) | Major | Shortcut manager: Terminal layer (focused only), Workspace layer (Ctrl+1-5), App layer (Ctrl+K, Ctrl+G). |
|
||||||
|
| 10 | Remote machine support orphaned | Major | Elevate to project level (project.remote_machine_id). Defer integration to v3.1. |
|
||||||
|
| 11 | No graceful degradation for broken projects | Major | Project health state: healthy/degraded/unavailable/error. Colored dot indicator. |
|
||||||
|
| 12 | Flat event stream wastes CPU for hidden projects | Minor | Buffer messages for inactive workspace projects. Flush on activation. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Model
|
||||||
|
|
||||||
|
### Project Group Config (`~/.config/bterminal/groups.json`)
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
{
|
||||||
|
"version": 1,
|
||||||
|
"groups": [
|
||||||
|
{
|
||||||
|
"id": "work-ai",
|
||||||
|
"name": "AI Projects",
|
||||||
|
"projects": [
|
||||||
|
{
|
||||||
|
"id": "bterminal",
|
||||||
|
"name": "BTerminal",
|
||||||
|
"identifier": "bterminal",
|
||||||
|
"description": "Terminal emulator with Claude integration",
|
||||||
|
"icon": "\uf120",
|
||||||
|
"cwd": "/home/hibryda/code/ai/BTerminal",
|
||||||
|
"profile": "default",
|
||||||
|
"enabled": true
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"activeGroupId": "work-ai"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### TypeScript Types (`v2/src/lib/types/groups.ts`)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export interface ProjectConfig {
|
||||||
|
id: string;
|
||||||
|
name: string;
|
||||||
|
identifier: string;
|
||||||
|
description: string;
|
||||||
|
icon: string;
|
||||||
|
cwd: string;
|
||||||
|
profile: string;
|
||||||
|
enabled: boolean;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface GroupConfig {
|
||||||
|
id: string;
|
||||||
|
name: string;
|
||||||
|
projects: ProjectConfig[]; // max 5
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface GroupsFile {
|
||||||
|
version: number;
|
||||||
|
groups: GroupConfig[];
|
||||||
|
activeGroupId: string;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### SQLite Schema Additions
|
||||||
|
|
||||||
|
```sql
|
||||||
|
ALTER TABLE sessions ADD COLUMN project_id TEXT DEFAULT '';
|
||||||
|
|
||||||
|
CREATE TABLE IF NOT EXISTS agent_messages (
|
||||||
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||||
|
session_id TEXT NOT NULL,
|
||||||
|
project_id TEXT NOT NULL,
|
||||||
|
sdk_session_id TEXT,
|
||||||
|
message_type TEXT NOT NULL,
|
||||||
|
content TEXT NOT NULL,
|
||||||
|
parent_id TEXT,
|
||||||
|
created_at INTEGER NOT NULL,
|
||||||
|
FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
|
||||||
|
);
|
||||||
|
CREATE INDEX idx_agent_messages_session ON agent_messages(session_id);
|
||||||
|
CREATE INDEX idx_agent_messages_project ON agent_messages(project_id);
|
||||||
|
|
||||||
|
CREATE TABLE IF NOT EXISTS project_agent_state (
|
||||||
|
project_id TEXT PRIMARY KEY,
|
||||||
|
last_session_id TEXT NOT NULL,
|
||||||
|
sdk_session_id TEXT,
|
||||||
|
status TEXT NOT NULL,
|
||||||
|
cost_usd REAL DEFAULT 0,
|
||||||
|
input_tokens INTEGER DEFAULT 0,
|
||||||
|
output_tokens INTEGER DEFAULT 0,
|
||||||
|
last_prompt TEXT,
|
||||||
|
updated_at INTEGER NOT NULL
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Component Architecture
|
||||||
|
|
||||||
|
### Component Tree
|
||||||
|
|
||||||
|
```
|
||||||
|
App.svelte [REWRITTEN]
|
||||||
|
├── CommandPalette.svelte [NEW]
|
||||||
|
├── GlobalTabBar.svelte [NEW] Sessions | Docs | Context | Settings
|
||||||
|
├── [Tab: Sessions]
|
||||||
|
│ └── ProjectGrid.svelte [NEW] Horizontal flex + scroll-snap
|
||||||
|
│ └── ProjectBox.svelte [NEW] Per-project container
|
||||||
|
│ ├── ProjectHeader.svelte [NEW] Icon + name + status dot
|
||||||
|
│ ├── ClaudeSession.svelte [NEW, from AgentPane] Main session
|
||||||
|
│ ├── TeamAgentsPanel.svelte [NEW] Right panel for subagents
|
||||||
|
│ │ └── AgentCard.svelte [NEW] Compact subagent view
|
||||||
|
│ └── TerminalTabs.svelte [NEW] Tabbed terminals
|
||||||
|
│ ├── TabBar.svelte [NEW]
|
||||||
|
│ └── TerminalPane.svelte [SURVIVES]
|
||||||
|
├── [Tab: Docs]
|
||||||
|
│ └── DocsTab.svelte [NEW]
|
||||||
|
│ ├── MdFilePicker.svelte [NEW]
|
||||||
|
│ └── MarkdownPane.svelte [SURVIVES]
|
||||||
|
├── [Tab: Context]
|
||||||
|
│ └── ContextPane.svelte [SURVIVES, extracted from pane]
|
||||||
|
├── [Tab: Settings]
|
||||||
|
│ └── SettingsTab.svelte [NEW]
|
||||||
|
│ ├── ProjectSettingsEditor.svelte [NEW]
|
||||||
|
│ └── GlobalSettings.svelte [NEW]
|
||||||
|
├── StatusBar.svelte [MODIFIED]
|
||||||
|
└── ToastContainer.svelte [SURVIVES]
|
||||||
|
```
|
||||||
|
|
||||||
|
### What Dies
|
||||||
|
|
||||||
|
| v2 Component/Store | Reason |
|
||||||
|
|---|---|
|
||||||
|
| TilingGrid.svelte | Replaced by ProjectGrid |
|
||||||
|
| PaneContainer.svelte | Fixed project box structure |
|
||||||
|
| SessionList.svelte (sidebar) | No sidebar; project headers replace |
|
||||||
|
| SshSessionList.svelte | Absorbed into TerminalTabs |
|
||||||
|
| SettingsDialog.svelte | Replaced by SettingsTab |
|
||||||
|
| AgentPane.svelte | Split into ClaudeSession + TeamAgentsPanel |
|
||||||
|
| layout.svelte.ts | Replaced by workspace.svelte.ts |
|
||||||
|
| layout.test.ts | Replaced by workspace tests |
|
||||||
|
|
||||||
|
### What Survives
|
||||||
|
|
||||||
|
TerminalPane, MarkdownPane, AgentTree, ContextPane, StatusBar, ToastContainer, theme store, notifications store, agents store (modified), all adapters (agent-bridge, pty-bridge, claude-bridge, sdk-messages, session-bridge, ctx-bridge, ssh-bridge), all Rust backend (sidecar, pty, session, ctx, watcher), highlight utils.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Layout System
|
||||||
|
|
||||||
|
### Project Grid (Flexbox + scroll-snap)
|
||||||
|
|
||||||
|
```css
|
||||||
|
.project-grid {
|
||||||
|
display: flex;
|
||||||
|
gap: 4px;
|
||||||
|
height: 100%;
|
||||||
|
overflow-x: auto;
|
||||||
|
scroll-snap-type: x mandatory;
|
||||||
|
}
|
||||||
|
|
||||||
|
.project-box {
|
||||||
|
flex: 0 0 calc((100% - (N-1) * 4px) / N);
|
||||||
|
scroll-snap-align: start;
|
||||||
|
min-width: 480px;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
N computed from viewport: `Math.min(projects.length, Math.max(1, Math.floor(containerWidth / 520)))`
|
||||||
|
|
||||||
|
### Project Box Internal Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─ ProjectHeader (28px) ──────────────────┐
|
||||||
|
├─────────────────────┬───────────────────┤
|
||||||
|
│ ClaudeSession │ TeamAgentsPanel │
|
||||||
|
│ (flex: 1) │ (240px or overlay)│
|
||||||
|
├─────────────────────┴───────────────────┤
|
||||||
|
│ [Tab1] [Tab2] [+] TabBar 26px │
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ Terminal content (xterm or scrollback) │
|
||||||
|
└─────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
Team panel: inline at >2560px, overlay at <2560px. Collapsed when no subagents.
|
||||||
|
|
||||||
|
### Responsive Breakpoints
|
||||||
|
|
||||||
|
| Width | Visible Projects | Team Panel |
|
||||||
|
|-------|-----------------|------------|
|
||||||
|
| 5120px+ | 5 | inline 240px |
|
||||||
|
| 3840px | 4 | inline 200px |
|
||||||
|
| 2560px | 3 | overlay |
|
||||||
|
| 1920px | 3 | overlay |
|
||||||
|
| <1600px | 1 + project tabs | overlay |
|
||||||
|
|
||||||
|
### xterm.js Budget: 4 Active Instances
|
||||||
|
|
||||||
|
| State | xterm? | Memory |
|
||||||
|
|-------|--------|--------|
|
||||||
|
| Active-Focused | Yes | ~20MB |
|
||||||
|
| Active-Background | Yes (if budget allows) | ~20MB |
|
||||||
|
| Suspended | No (HTML pre scrollback) | ~200KB |
|
||||||
|
| Uninitialized | No (placeholder) | 0 |
|
||||||
|
|
||||||
|
On focus: serialize least-recent xterm scrollback, destroy it, create new for focused tab, reconnect PTY.
|
||||||
|
|
||||||
|
### Project Accent Colors (Catppuccin)
|
||||||
|
|
||||||
|
| Slot | Color | Variable |
|
||||||
|
|------|-------|----------|
|
||||||
|
| 1 | Blue | --ctp-blue |
|
||||||
|
| 2 | Green | --ctp-green |
|
||||||
|
| 3 | Mauve | --ctp-mauve |
|
||||||
|
| 4 | Peach | --ctp-peach |
|
||||||
|
| 5 | Pink | --ctp-pink |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sidecar Strategy
|
||||||
|
|
||||||
|
**Single shared sidecar** (unchanged from v2). Per-project isolation via:
|
||||||
|
- `cwd` per query (already implemented)
|
||||||
|
- `claude_config_dir` per query (already implemented)
|
||||||
|
- `session_id` routing (already implemented)
|
||||||
|
|
||||||
|
No sidecar changes needed for v3.0.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Keyboard Shortcuts
|
||||||
|
|
||||||
|
| Shortcut | Action | Layer |
|
||||||
|
|----------|--------|-------|
|
||||||
|
| Ctrl+K | Command palette | App |
|
||||||
|
| Ctrl+G | Switch group (palette filtered) | App |
|
||||||
|
| Ctrl+1..5 | Focus project by index | App |
|
||||||
|
| Alt+1..4 | Switch workspace tab | App |
|
||||||
|
| Ctrl+N | New terminal in focused project | Workspace |
|
||||||
|
| Ctrl+Shift+N | New agent query | Workspace |
|
||||||
|
| Ctrl+Tab | Next terminal tab | Project |
|
||||||
|
| Ctrl+W | Close terminal tab | Project |
|
||||||
|
| Ctrl+, | Settings tab | App |
|
||||||
|
| Ctrl+Shift+C/V | Copy/paste in terminal | Terminal |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Implementation Phases
|
||||||
|
|
||||||
|
### Phase 1: Data Model + Config [status: complete]
|
||||||
|
**Milestone: Groups config loads/saves, SQLite migrations pass, workspace store works**
|
||||||
|
|
||||||
|
- [x] Create `v2/src/lib/types/groups.ts` (TypeScript interfaces)
|
||||||
|
- [x] Create `v2/src-tauri/src/groups.rs` (Rust structs + load/save)
|
||||||
|
- [x] Add `groups_load`, `groups_save` Tauri commands to lib.rs
|
||||||
|
- [x] SQLite migrations in session.rs: project_id column, agent_messages table, project_agent_state table
|
||||||
|
- [x] Create `v2/src/lib/adapters/groups-bridge.ts` (IPC wrapper)
|
||||||
|
- [x] Create `v2/src/lib/stores/workspace.svelte.ts` (replaces layout.svelte.ts)
|
||||||
|
- [x] Add `--group` CLI argument parsing in main.rs
|
||||||
|
- [x] Write tests for groups load/save and workspace store (24 vitest + 7 cargo)
|
||||||
|
|
||||||
|
### Phase 2: Project Box Shell [status: complete]
|
||||||
|
**Milestone: Project boxes render horizontally with headers, workspace tabs switch**
|
||||||
|
|
||||||
|
- [x] Create GlobalTabBar.svelte (Sessions | Docs | Context | Settings)
|
||||||
|
- [x] Create ProjectGrid.svelte (flex + scroll-snap container)
|
||||||
|
- [x] Create ProjectBox.svelte (CSS grid: header | session-area | terminal-area)
|
||||||
|
- [x] Create ProjectHeader.svelte (icon + name + status dot + accent color)
|
||||||
|
- [x] Rewrite App.svelte (GlobalTabBar + tab content + StatusBar)
|
||||||
|
- [x] Create CommandPalette.svelte, DocsTab.svelte, ContextTab.svelte, SettingsTab.svelte
|
||||||
|
- [x] CSS for responsive project count + accent colors
|
||||||
|
|
||||||
|
### Phase 3: Claude Session Integration [status: complete]
|
||||||
|
**Milestone: Claude sessions run within project boxes, per-project profile isolation**
|
||||||
|
|
||||||
|
- [x] Create ClaudeSession.svelte (wraps AgentPane, passes project cwd/profile/config_dir)
|
||||||
|
|
||||||
|
### Phase 4: Terminal Tabs [status: complete]
|
||||||
|
**Milestone: Each project has tabbed terminals with xterm budget enforcement**
|
||||||
|
|
||||||
|
- [x] Create TerminalTabs.svelte (tab state per project, shell/SSH/agent tab types)
|
||||||
|
|
||||||
|
### Phase 5: Team Agents Panel [status: complete]
|
||||||
|
**Milestone: Subagents appear in right panel, not separate panes. MVP complete.**
|
||||||
|
|
||||||
|
- [x] Create TeamAgentsPanel.svelte (right side of session area)
|
||||||
|
- [x] Create AgentCard.svelte (compact subagent: status, messages, cost)
|
||||||
|
|
||||||
|
### --- MVP BOUNDARY ---
|
||||||
|
|
||||||
|
### Phase 6: Session Continuity [status: not started]
|
||||||
|
- [ ] Persist agent messages to SQLite on session complete
|
||||||
|
- [ ] Persist sdkSessionId in project_agent_state
|
||||||
|
- [ ] On startup, load cached messages per project
|
||||||
|
- [ ] "Continue" button uses resume_session_id
|
||||||
|
|
||||||
|
### Phase 7: Command Palette + Group Switching [status: not started]
|
||||||
|
- [ ] Create CommandPalette.svelte (overlay, Ctrl+K, fuzzy search)
|
||||||
|
- [ ] Group list with switching
|
||||||
|
- [ ] Workspace teardown/setup on switch (serialize xterm, unmount, remount)
|
||||||
|
|
||||||
|
### Phase 8: Docs Tab [status: not started]
|
||||||
|
- [ ] `discover_markdown_files` Tauri command (walk with depth/exclusions)
|
||||||
|
- [ ] DocsTab.svelte with split layout (file tree + content)
|
||||||
|
- [ ] MdFilePicker.svelte (grouped by project with accent colors)
|
||||||
|
|
||||||
|
### Phase 9: Settings Tab [status: not started]
|
||||||
|
- [ ] SettingsTab.svelte (per-project + global)
|
||||||
|
- [ ] ProjectSettingsEditor.svelte (all config fields)
|
||||||
|
- [ ] Icon picker (nerd font subset)
|
||||||
|
- [ ] Group management (create/rename/delete)
|
||||||
|
|
||||||
|
### Phase 10: Polish + Cleanup [status: not started]
|
||||||
|
- [ ] Remove dead v2 components and stores
|
||||||
|
- [ ] Update all tests
|
||||||
|
- [ ] Update CLAUDE.md, docs, README
|
||||||
|
- [ ] Performance audit (xterm count, memory, streaming jank)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -67,7 +378,18 @@ BTerminal v3: Project orchestration dashboard (projects in a workspace)
|
||||||
|
|
||||||
| Decision | Rationale | Date |
|
| Decision | Rationale | Date |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| (pending adversarial review) | | |
|
| JSON for groups config, SQLite for session state | JSON is human-editable, shareable, version-controllable. SQLite for ephemeral runtime state. Load at startup only. | 2026-03-07 |
|
||||||
|
| Adaptive project count from viewport width | 5@5120px, 3@1920px, scroll-snap for overflow. min-width 480px. Better than forcing 5 at all sizes. | 2026-03-07 |
|
||||||
|
| Single shared sidecar (v3.0) | Existing multiplexed protocol handles concurrent sessions. Per-project pool deferred to v3.1 if crash isolation needed. Saves ~200MB RAM. | 2026-03-07 |
|
||||||
|
| xterm budget: 4 active, unlimited suspended | WebKit2GTK OOM at ~5 instances. Serialize scrollback to text buffer, destroy xterm, recreate on focus. PTY stays alive. | 2026-03-07 |
|
||||||
|
| Flexbox + scroll-snap over CSS Grid | Allows horizontal scroll on narrow screens. Scroll-snap gives clean project-to-project scrolling. | 2026-03-07 |
|
||||||
|
| Team panel: inline >2560px, overlay <2560px | Adapts to available space. Collapsed when no subagents running. | 2026-03-07 |
|
||||||
|
| 4 workspace tabs (Sessions/Docs/Context/Settings) | ctx viewer as separate tab per user requirement. Docs auto-discovered from projects. | 2026-03-07 |
|
||||||
|
| Project accent colors from Catppuccin palette | Visual distinction: blue/green/mauve/peach/pink per slot 1-5. Applied to border + header tint. | 2026-03-07 |
|
||||||
|
| Remote machines deferred to v3.1 | Elevate to project level (project.remote_machine_id) but don't implement in MVP. | 2026-03-07 |
|
||||||
|
| Keyboard shortcut layers: App > Workspace > Terminal | Prevents conflicts. Terminal captures raw keys only when focused. App layer uses Ctrl+K/G. | 2026-03-07 |
|
||||||
|
| AgentPane splits into ClaudeSession + TeamAgentsPanel | Team agents shown inline in right panel, not as separate panes. Saves xterm/pane slots. | 2026-03-07 |
|
||||||
|
| Unmount/remount on group switch | Serialize xterm scrollbacks, destroy, remount new group. <100ms perceived. Frees ~80MB. | 2026-03-07 |
|
||||||
|
|
||||||
## Errors Encountered
|
## Errors Encountered
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue