docs: update all docs for Phase 5 agent tree, status bar, notifications, settings
This commit is contained in:
Hibryda
parent
be24d07c65
commit
d7a1dca40d
5 changed files with 133 additions and 13 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
91
CLAUDE.md
Normal file
91
CLAUDE.md
Normal file
|
|
@ -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)
|
||||
|
|
@ -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)
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue