62159
Sy
symb / files
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