xonecas.io
62159
Sy

symb / files

symb / docs / DESIGN.md

9.6 KB
1# Symb (pronounced "sim")
2
3Symbiotic pairing between developer and LLM. TUI with an agentic conversation
4on one side, code editor on the other. Fast, low memory, not a distraction.
5
6## What It Is Now
7
8### TUI (BubbleTea, ELM architecture)
9
10Alt-screen, mouse cell-motion mode with 15ms
11throttle on wheel/motion events.
12
13```
14╭─────────────────────────────────────────────╮
15│ conversation log                            │
16│ - reasoning (muted)                         │
17│ - → tool calls                              │
18│ - ← tool results                            │
19│ - content                                   │
20│ - scroll, select, copy                      │
21├─────────────────────────────────────────────┤
22│ input (editable)                            │
23├─────────────────────────────────────────────┤
24│ status bar with spinner                     │
25╰─────────────────────────────────────────────╯
26```
27
28### Log
29
30Conversation log, an interactive conversation log where the user can click on tool messages to open a modal
31and view the contents of that tool call (call and results). Streams results in modal if tool is running.
32
33### Agent input interactivity:
34
35Editor component (`internal/tui/editor`): full editing capability (insert,
36delete, paste, tab indent)
37
38Agent input, simple multiline textarea with markdown highlighting.
39
40Use a special key `@` to spawn an autocomplete/filesearch modal. This can match files, skills, commands or subagents.
41When the user selects a match with `Enter` it replaces the @ with the selected item once the message is sent to the, includes hashes when injected into the user message.
42Start with file search only for the initial implementation.
43Remove the ctrl+f keybind
44
45TODO: Call shell commands and send the content as the user message with `!` as the first character in the input
46
47### Search modal
48
49Opens via keybind: `@` in the agent input
50
51Search modal:
52
53- Centered in the UI, 80% of length and width of the main app window, resizable with the rest of the app.
54- Top row is the input for the file search query
55- Rest of the modal is the list of matches.
56- Results update after the user stops typing for a few hundred miliseconds.
57- Up/down arrow select from the search results. If focus is on input and user presses down arrow, it focus the list. If focus is on first result and user presses up arrow focus the input.
58- `Enter` on input selects the first match closing the modal
59- `Enter` on result list row selected the selected row. closing the modal
60- `ESC` cancels the file search closing the modal.
61
62Selection is inserted into the user message on send at the place of the `@`.
63
64### Statusbar implementation
65
66Status bar, a simple bar showing the current git status current model and animated icon
67
68(in order: left to right)
69
70Left:
71
72- Show current branch + dirty status in status bar. (needs to be updated every X frames/time) to be responsive
73- Count of files added/changed/removed in git tracking // TODO
74
75Right (right aligned text)
76
77- Current llm provider config name
78- Animated icon:
79  - Slow animation when idle.
80  - Fast animation while a request to the LLM is in-flight (whole turn)
81  - Animated icon becomes red on network errors until next successful request.
82
83### Other modals:
84
85- Select active model (lists all available models from all providers)
86- Show keybinds/help
87
88### LLM Loop (`internal/llm`)
89
90Streaming multi-turn. Up to 20 tool rounds per turn. Calls
91`Provider.ChatStream()` — returns `<-chan StreamEvent`. Forwards deltas via
92`OnDelta` callback for incremental TUI rendering, emits complete messages via
93`OnMessage` callback. Tool call limit is handled by forcing the llm to give a status
94report.
95
96Prompt system: model-specific base prompts (Claude, Gemini, Qwen, GPT).
97`AGENTS.md` support: walks directory tree upward collecting all AGENTS.md files,
98prepends to system prompt. Checks `~/.config/symb/AGENTS.md` too.
99
100// TODO: guard against massive folders needed.
101
102### Providers (`internal/provider`)
103
104- **Ollama**, **Zen** — local, and remote.
105- SSE streaming with retry on initial connection (3 retries, 429/5xx).
106- Single `ChatStream()` interface method replaces `Chat`/`ChatWithTools`/`Stream`.
107- Deterministic JSON tool schemas, provider kv cache support
108
109### MCP (`internal/mcp`)
110
111Proxy merges local tool handlers with optional upstream MCP server (HTTP
112Streamable-HTTP transport, SSE support, session tracking). Retry with
113Retry-After parsing.
114
115Used for exa.ai tools
116
117### Tools (`internal/mcptools`)
118
1197 tools registered:
120
121- **Read** — reads file, returns hashline-tagged content (`linenum:hash|content`). Path traversal prevention.
122- **Edit** — hash-anchored file editing (replace, insert, delete, create).
123  Validates hashes before modifying. Returns fresh hashes after edit. Enforces
124  read-before-edit via `FileReadTracker`. Includes LSP Diagnostics.
125- **Grep** — file/content search. Regex, gitignore-aware, case sensitivity,
126  max results.
127- **Shell** — sandboxed shell execution. Command blocking for dangerous ops,
128  streaming output, timeout support.
129- **TodoWrite** — LLM scratchpad/plan persistence. Visible at end of context window.
130- **WebSearch** and **WebFetch** — read and search the web (by exa.ai via mcp).
131
132### Git Integration
133
134// TODO: Reconsider git integration without the editor pane
135// Use git diffs and worktrees for edits?
136
137- git markers in the number column for editted files in the editor (needs work but does what it's meant to do)
138- TODO: Read includes diff for the file (or diff status, we need to consider token usage) edit tool includes updated file diff after change
139
140### LSP Integration
141
142- Show closed loop feedback on mutations done by the llm.
143- Start with diagnostics (show errors/warnings in the number line, a error line has a red color number, warnings yellow).
144
145### Basic Session storage
146
147- table for conversation messages
148- each message includes all tool calls
149- opening the app opens a new session (more controls later). Same behaviour
150- modal to resume past sessions
151
152### Tree-Sitter Context
153
154// TODO: remove context injection. Use project treesitter info to improve Grep tool
155
156Parse project with tree-sitter for structural awareness. Feed relevant
157symbols/scope to LLM as auto-context instead of whole files.
158**Uses 4k tokens on a small project like this** -- ohoh... Maybe return updated treesiter information with Grep matches for less token usage overall? Context inhection then can reduced/compacted?
159
160### Undo!
161
162- User should be able to undo conversation turns. The most recent entry should show a clear clickable area labelled undo.
163- Clicking undo reverses context history, tool calls, filesystem changes, file changes. Resets the conversation to that exact point
164
165### Interrupt!
166
167// TODO: Interrupted messages should still show the message footer in the TUI
168
169- User can interrupt the LLM on exit or via `ESC` when an assitant is replying
170- Should complete the assistant message with "Agent interrupted before answering" as the content.
171
172### Shell Execution Tool
173
174Run commands in sandbox (container isolation or restricted shell). Command
175whitelisting. Output streaming to conversation.
176
177### TUI Rendering loop
178
179- 60fps baseline
180- Optimized frame render logic.
181- Integrates with hl theme.
182
183### Context management
184
1851. Context token count: input, output, and total tokens. Store them in db. Shown each message with the timestamp:
186
187```
188<time elapsed> <timestamp> <tokens in current count>/<tokens out current count> (<total tokens in context at current count).
189<undo if most recent agent message>
190```
191
192**DONE**
193
194- Read tool caps output at 500 lines / 20k chars; tells LLM to use line ranges for larger files.
195
1962. Gather baseline data with no context management. Then study:
197   **INPROGRESS**
198
199https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
200(Search for more resources like the one above, build a document with concise knowledge base (500 lines max)
201
202Implement findings?
203
204### Session cli flags:
205
206- `-s`, `--session`: Takes a session id
207- `-l`, `--list`: Lists sessions with id, last user message timestamp, and 50 characters of the last user user message.
208- `-c`, `--continue`: continues last session (most recent user message)
209
210### Sub-Agent Tool
211
212Spawn a child LLM turn scoped to a single task. Useful for parallel work
213or decomposing complex operations.
214
215- Have a short max iteration
216- Customized prompt for single purpose agents
217- TODO: Custom agents from community configs
218- TODO: Worktress so they don't colide (needs to be an option, not all users use or like gitworktrees)
219
220Testing, cleaning up.
221
222## Features waiting implementation for current version:
223
224### Community configs support:
225
226- CLAUDE/AGENTS/CURSOR/ETC.md (or just AGENTS.md at this point?) -- Is there a standard?
227- Custom subagent prompts for custom agents
228- Commands and skills implementation to match community expectations
229
230### Tool hooks:
231
232Like git hooks, but after a specific tool call (lint after edit, or format when Y, etc).
233
234## Next version plans:
235
236### Git write commands and worktrees
237
238- sandboxed git worktrees for agents edits.
239
240### Human-in-the-Middle Tool Approval
241
242Pause before executing tool calls. Show tool name + args in a dialog. User
243approves/rejects. Configurable per-tool permissions in `config.toml` (allow,
244ask, deny). Some tools (Read/Grep) default allow, mutations (Edit) default ask.
245
246### UI Polish
247
248- Empty-state decoration in conversation pane and editor