From d7a1dca40d029af9f4136c2600486e09cb6fc440 Mon Sep 17 00:00:00 2001 From: Hibryda Date: Fri, 6 Mar 2026 13:46:37 +0100 Subject: [PATCH] docs: update all docs for Phase 5 agent tree, status bar, notifications, settings --- .claude/CLAUDE.md | 6 +++- CLAUDE.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++ docs/phases.md | 31 ++++++++++------ docs/progress.md | 14 +++++++- docs/task_plan.md | 4 ++- 5 files changed, 133 insertions(+), 13 deletions(-) create mode 100644 CLAUDE.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 398425e..3936b92 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -4,7 +4,7 @@ - v1 is a single-file Python app (`bterminal.py`). Changes are localized. - v2 docs are in `docs/`. Architecture decisions are in `docs/task_plan.md`. -- MVP complete (Phases 1-4). Phase 3 polish done (crash detection, restart UI, auto-scroll lock). Phase 4 done (SQLite sessions, file watcher, markdown viewer). +- MVP complete (Phases 1-4). Phase 5 (Agent Tree + Polish) in progress: agent tree viz, status bar, notifications, settings dialog done. Remaining: tree node click-to-focus, subtree cost display, ctx integration. - Consult Memora (tag: `bterminal`) before making architectural changes. ## Documentation References @@ -33,6 +33,10 @@ - Session persistence uses rusqlite (bundled) with WAL mode. Data dir: `dirs::data_dir()/bterminal/sessions.db`. - Layout store persists to SQLite on every addPane/removePane/setPreset change (fire-and-forget). Restores on app startup via `restoreFromDb()`. - File watcher uses notify crate v6, watches parent directory (NonRecursive), emits `file-changed` Tauri events. +- Settings use key-value `settings` table in SQLite (session.rs). Frontend: `settings-bridge.ts` adapter, `SettingsDialog.svelte` component. +- Notifications use ephemeral toast system: `notifications.svelte.ts` store (max 5, 4s auto-dismiss), `ToastContainer.svelte` display. Agent dispatcher emits toasts on agent complete/error/crash. +- StatusBar component spans full grid width (grid-column: 1 / -1), shows pane counts, active agents, tokens, cost. +- Agent tree (AgentTree.svelte) uses SVG with recursive layout. Tree data built by `agent-tree.ts` utility from agent messages. ## Memora Tags diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..820eacb --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,91 @@ +# BTerminal — Project Guide for Claude + +## Project Overview + +Terminal emulator with SSH and Claude Code session management. v1 (GTK3+VTE Python) is production-stable. v2 redesign (Tauri 2.x + Svelte 5 + Claude Agent SDK) MVP complete, Phase 5 (polish) in progress. + +- **Repository:** github.com/DexterFromLab/BTerminal +- **License:** MIT +- **Primary target:** Linux x86_64 + +## Documentation (SOURCE OF TRUTH) + +**All project documentation lives in [`docs/`](docs/README.md). This is the single source of truth for this project.** Before making changes, consult the docs. After making changes, update the docs. No exceptions. + +## Key Paths + +| Path | Description | +|------|-------------| +| `bterminal.py` | v1 main application (2092 lines, GTK3+VTE) | +| `ctx` | Context manager CLI tool (SQLite-based) | +| `install.sh` | System installer | +| `docs/task_plan.md` | v2 architecture decisions and strategies | +| `docs/phases.md` | v2 implementation phases (1-6) | +| `docs/findings.md` | v2 research findings | +| `docs/progress.md` | Session progress log | +| `v2/src-tauri/src/pty.rs` | PTY backend (portable-pty, PtyManager) | +| `v2/src-tauri/src/lib.rs` | Tauri commands (pty + agent + session + file + settings) | +| `v2/src-tauri/src/sidecar.rs` | SidecarManager (Node.js lifecycle, NDJSON) | +| `v2/src-tauri/src/session.rs` | SessionDb (rusqlite, sessions + layout + settings persistence) | +| `v2/src-tauri/src/watcher.rs` | FileWatcherManager (notify crate, file change events) | +| `v2/src/lib/stores/layout.svelte.ts` | Layout store (panes, presets, persistence, Svelte 5 runes) | +| `v2/src/lib/stores/agents.svelte.ts` | Agent session store (messages, cost) | +| `v2/src/lib/components/Terminal/TerminalPane.svelte` | xterm.js terminal pane | +| `v2/src/lib/components/Agent/AgentPane.svelte` | Agent session pane (prompt, messages, cost) | +| `v2/src/lib/adapters/pty-bridge.ts` | PTY IPC wrapper (Tauri invoke/listen) | +| `v2/src/lib/adapters/agent-bridge.ts` | Agent IPC wrapper (Tauri invoke/listen) | +| `v2/src/lib/adapters/sdk-messages.ts` | SDK message adapter (stream-json parser) | +| `v2/src/lib/agent-dispatcher.ts` | Routes sidecar events to agent store + toast notifications | +| `v2/src/lib/adapters/file-bridge.ts` | File watcher IPC wrapper | +| `v2/src/lib/adapters/settings-bridge.ts` | Settings IPC wrapper (get/set/list) | +| `v2/src/lib/utils/agent-tree.ts` | Agent tree builder (hierarchy from messages) | +| `v2/src/lib/stores/notifications.svelte.ts` | Toast notification store (notify, dismiss) | +| `v2/src/lib/components/Agent/AgentTree.svelte` | SVG agent tree visualization | +| `v2/src/lib/components/StatusBar/StatusBar.svelte` | Global status bar (pane counts, cost) | +| `v2/src/lib/components/Notifications/ToastContainer.svelte` | Toast notification display | +| `v2/src/lib/components/Settings/SettingsDialog.svelte` | Settings modal dialog | +| `v2/src/lib/adapters/session-bridge.ts` | Session/layout persistence IPC wrapper | +| `v2/src/lib/components/Markdown/MarkdownPane.svelte` | Markdown file viewer (marked.js, live reload) | +| `v2/sidecar/agent-runner.ts` | Node.js sidecar (spawns claude CLI) | + +## v1 Stack + +- Python 3, GTK3 (PyGObject), VTE 2.91 +- Config: `~/.config/bterminal/` (sessions.json, claude_sessions.json) +- Context DB: `~/.claude-context/context.db` +- Theme: Catppuccin Mocha + +## v2 Stack (Phase 5 in progress, branch: v2-mission-control) + +- Tauri 2.x (Rust backend) + Svelte 5 (frontend) +- xterm.js with Canvas addon (no WebGL on WebKit2GTK) +- Agent sessions via `claude` CLI subprocess with `--output-format stream-json` +- Node.js sidecar manages claude processes (stdio NDJSON to Rust) +- portable-pty for terminal management +- SQLite session persistence (rusqlite, WAL mode) + layout restore on startup +- File watcher (notify crate) for live markdown viewer +- Rust deps: tauri, portable-pty, rusqlite (bundled), dirs, notify, uuid, serde, tokio +- npm deps: @xterm/xterm, @xterm/addon-canvas, @xterm/addon-fit, @tauri-apps/api, marked +- Source: `v2/` directory + +## Build / Run + +```bash +# v1 (current production) +./install.sh # Install system-wide +bterminal # Run + +# v1 Dependencies (Debian/Ubuntu) +sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-vte-2.91 + +# v2 (development, branch v2-mission-control) +cd v2 && npm install && npm run tauri dev # Dev mode +cd v2 && npm run tauri build # Release build +``` + +## Conventions + +- Catppuccin Mocha theme for all UI elements +- Session configs stored as JSON +- Single-file Python app (v1) — will change to multi-file Rust+Svelte (v2) +- Polish language in some code comments (v1 legacy) diff --git a/docs/phases.md b/docs/phases.md index 30a761a..a7dc21f 100644 --- a/docs/phases.md +++ b/docs/phases.md @@ -36,19 +36,28 @@ bterminal-v2/ TerminalPane.svelte # xterm.js terminal pane Agent/ AgentPane.svelte # SDK agent structured output - AgentTree.svelte # Subagent tree visualization - ToolCallCard.svelte # Individual tool call display + AgentTree.svelte # Subagent tree visualization (SVG) Markdown/ MarkdownPane.svelte # Live markdown file viewer Sidebar/ SessionList.svelte # Session browser + StatusBar/ + StatusBar.svelte # Global status bar (pane counts, cost) + Notifications/ + ToastContainer.svelte # Toast notification display + Settings/ + SettingsDialog.svelte # Settings modal dialog stores/ sessions.svelte.ts # Session state ($state runes) agents.svelte.ts # Active agent tracking layout.svelte.ts # Pane layout state + notifications.svelte.ts # Toast notification state adapters/ sdk-messages.ts # SDK message abstraction layer pty-bridge.ts # PTY IPC wrapper + settings-bridge.ts # Settings IPC wrapper + utils/ + agent-tree.ts # Agent tree builder (hierarchy from messages) styles/ catppuccin.css # Theme CSS variables app.css @@ -163,15 +172,17 @@ bterminal-v2/ --- -## Phase 5: Agent Tree + Polish [status: not_started] — Post-MVP +## Phase 5: Agent Tree + Polish [status: in_progress] — Post-MVP -- [ ] Agent tree visualization (SVG, compact horizontal layout) -- [ ] Click tree node -> focus agent pane -- [ ] Aggregate cost per subtree -- [ ] Global status bar (total cost, active agents, uptime) -- [ ] Notification system (agent done, error) -- [ ] Global keyboard shortcuts -- [ ] Settings dialog +- [x] Agent tree visualization (SVG, compact horizontal layout) — AgentTree.svelte + agent-tree.ts utility +- [ ] Click tree node -> focus agent pane (onNodeClick prop exists, not wired) +- [ ] Aggregate cost per subtree (subtreeCost util exists, not displayed in UI) +- [x] Global status bar (terminal/agent counts, active agents pulse, token/cost totals) — StatusBar.svelte +- [x] Notification system (toast: success/error/warning/info, auto-dismiss 4s, max 5) — notifications.svelte.ts + ToastContainer.svelte +- [x] Agent dispatcher toast integration (agent complete, error, sidecar crash notifications) +- [x] Global keyboard shortcuts — Ctrl+W close focused pane, Ctrl+, open settings +- [x] Settings dialog (default shell, cwd, max panes) — SettingsDialog.svelte + settings-bridge.ts +- [x] Settings backend — settings table in SQLite (session.rs), Tauri commands settings_get/set/list (lib.rs) - [ ] ctx integration (port from v1) --- diff --git a/docs/progress.md b/docs/progress.md index d5c070b..4e0db38 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -97,8 +97,20 @@ Architecture decision: Uses `claude` CLI with `--output-format stream-json` inst - [x] Sidebar "M" button opens file picker for .md/.markdown/.txt files - [x] TilingGrid routes markdown pane type to MarkdownPane component +### Phase 5: Agent Tree + Polish (2026-03-06, in progress) +- [x] Agent tree visualization (SVG): AgentTree.svelte component with horizontal tree layout, bezier edges, status-colored nodes; agent-tree.ts utility (buildAgentTree, countTreeNodes, subtreeCost) +- [x] Agent tree toggle in AgentPane: collapsible tree view shown when tool_call messages exist +- [x] Global status bar: StatusBar.svelte showing terminal/agent pane counts, active agents with pulse animation, total tokens and cost +- [x] Notification system: notifications.svelte.ts store (notify, dismissNotification, max 5 toasts, 4s auto-dismiss) + ToastContainer.svelte (slide-in animation, color-coded by type) +- [x] Agent dispatcher notifications: toast on agent_stopped (success), agent_error (error), sidecar crash (error), cost result (success with cost/turns) +- [x] Settings dialog: SettingsDialog.svelte modal (default shell, cwd, max panes) with settings-bridge.ts adapter +- [x] Settings backend: settings table (key/value) in session.rs, Tauri commands settings_get/set/list in lib.rs +- [x] Keyboard shortcuts: Ctrl+W close focused pane, Ctrl+, open settings dialog +- [x] CSS grid update: app.css grid-template-rows '1fr' -> '1fr auto' for status bar row +- [x] App.svelte: integrated StatusBar, ToastContainer, SettingsDialog components + ### Next Steps - [ ] Markdown rendering in agent text messages - [ ] Testing: vitest for sdk-messages adapter, cargo test for sidecar -- [ ] Phase 5: Agent Tree + Polish +- [ ] Phase 5 remaining: click tree node -> focus pane, subtree cost display, ctx integration - [ ] Phase 6: Packaging + Distribution diff --git a/docs/task_plan.md b/docs/task_plan.md index 3c869a8..0ad36e3 100644 --- a/docs/task_plan.md +++ b/docs/task_plan.md @@ -3,7 +3,7 @@ ## Goal Redesign BTerminal from a GTK3 terminal emulator into a **multi-session Claude agent dashboard** optimized for 32:9 ultrawide (5120x1440). Simultaneous visibility of all active sessions, agent tree visualization, inline markdown rendering, maximum information density. -## Status: MVP COMPLETE (Phase 4 done — Rev 2) +## Status: Phase 5 IN PROGRESS (MVP complete, post-MVP polish underway — Rev 2) --- @@ -125,6 +125,8 @@ See [phases.md](phases.md) for the full phased implementation plan (Phases 1-6). | Canvas addon (not WebGL) | WebKit2GTK has no WebGL. Explicit Canvas addon avoids silent fallback | 2026-03-05 | | claude CLI over Agent SDK query() | Use `claude -p --output-format stream-json` instead of SDK npm package. Avoids dependency + version churn, identical structured output | 2026-03-06 | | `.svelte.ts` for rune stores | Svelte 5 `$state`/`$derived` runes require `.svelte.ts` extension (not `.ts`). Compiler silently passes `.ts` but runes fail at runtime. All store files must use `.svelte.ts`. | 2026-03-06 | +| SQLite settings table for app config | Key-value `settings` table in session.rs for persisting user preferences (shell, cwd, max panes). Simple and extensible without schema migrations. | 2026-03-06 | +| Toast notifications over persistent log | Ephemeral toasts (4s auto-dismiss, max 5) for agent events rather than a persistent notification log. Keeps UI clean; persistent logs can be added later if needed. | 2026-03-06 | ## Open Questions