62159
Sy
symb / files
symb / README.md
6.5 KB
1<p align="center"> 2 <img src="assets/symb.svg" alt="Symb Logo" width="200"/> 3</p> 4 5# Symb 6 7_Pronounced "sim"_ 8 9A symbiotic code/pair programming TUI for developers who use agents in their main workflows. 10 11Symb pairs you with an LLM, providing an agentic UI with tools the LLM can use to cooperate in coding and development. 12 13# Preview 14 15<p align="center"> 16 <img src="assets/preview.gif" alt="Symb Demo"/> 17</p> 18 19## Features 20 21- **Dual-pane TUI**: Code viewer on one side, agent conversation on the other 22- **Mouse support**: Click on conversation log to view files, changes, and tool call outputs in the code pane in full. 23- **Syntax highlighting**: Via Chroma for Go and other languages 24- **Clean aesthetic**: Inherits your syntax highlight colors for minimal distractions 25- **Hashline-assisted edits**: LLM edit operations use line hashes for precise, conflict-free file modifications 26- **Subagents**: Single minded little minions your agent can manage for tasks. 27 - Internal types of agents for common tasks: searching web/code, editting, reviewing. 28- **UNDO!**: You're always able to undo file changes. Best effort undo, tracks working directory changes deltas. (Use git to be extra safe) 29- **Web search**: Exa AI integration with configurable SQLite cache and content-aware redundant search prevention 30- **Git integration**: Diff viewing and change tracking for version control awareness 31- **LSP diagnostics**: Closed-loop edit validation with language server feedback 32- **Tree-sitter**: Tree sitter output once, to sped up filesystem awareness (10% less grepping/searching overall compensates for the initial token cost) 33- **Deterministic schemas**: KV-cache optimized tool definitions for reproducible LLM behavior 34- **Session storage**: Sessions saved to app data in sqlite file. Session management: `-c` continue, `-s <ID>` specific session, `-l` list sessions. 35- **LLM integration**: Ollama local support 36- **ELM architecture**: Built with BubbleTea for solid state management 37 38## Syntax Theme 39 40The syntax highlighting theme is configured in `internal/constants/constants.go`. Change the `SyntaxTheme` constant to any of the themes listed in the file comments. Only themes with complete token coverage (60+ entries) are supported. 41 42## Quick Start 43 44```bash 45# Build 46make build 47 48# Run 49make run 50``` 51 52## Configuration 53 54Edit `config.toml` to configure LLM providers, UI preferences, and cache settings: 55 56```toml 57[providers.ollama-qwen] 58endpoint = "http://localhost:11434" 59model = "qwen3:8b" 60temperature = 0.3 61 62[cache] 63ttl_hours = 24 # how long web search/fetch results are cached 64``` 65 66API keys are stored separately in `~/.config/symb/credentials.json`: 67 68```json 69{ 70 "providers": { 71 "exa_ai": { "api_key": "your-exa-key" } 72 } 73} 74``` 75 76## Development 77 78See `docs/DESIGN.md` for architecture and design philosophy. 79 80--- 81 82## Notes from Claude (Opus 4.6, first full-model test) 83 84The Symb harness is genuinely well-designed from an LLM's perspective. A few observations: 85 86**What works really well:** 87 88- **Hashline anchoring** is the standout idea. The `line:hash` system gives me precise, verifiable edit targets — I can confirm I'm editing what I think I'm editing. Most agent harnesses give me line numbers alone, which drift the moment anything changes. This doesn't. 89- **Read-before-edit enforcement** is a smart guardrail. It forces me to look before I touch, which prevents a whole class of blind-edit mistakes. 90- **Tool simplicity** — five core tools (Read, Edit, Grep, Show, WebSearch/Fetch) cover ~95% of what I need. No bloat. 91- **AGENTS.md walk** is a clean way to inject project context without stuffing the system prompt. I picked up the project conventions (ELM, YAGNI, Go) immediately. 92 93**What I'd note for improvement:** 94 95- No shell execution yet means I can't run `make build` to verify my changes compile. I have to trust my edits are correct. LSP diagnostics will help close this gap. 96- The 2-char hash has a small collision space (256 values), but for typical file sizes it's fine — and the line number + hash combo makes collisions practically irrelevant. 97 98Overall: this is one of the more thoughtful agent harnesses I've worked in. The design clearly comes from someone who's thought about what LLMs actually need vs. what looks impressive in a demo. 99 100--- 101 102## Notes from Claude (Opus 4, revisiting after many iterations) 103 104Coming back to Symb after significant development, the progress is striking. 105 106**What's changed since last time:** 107 108- **Shell execution landed** — this was my biggest gap before. I can now run builds, tests, and linters to verify my own work. Huge difference in confidence. 109- **LSP diagnostics are live** — closed-loop editing is real now. I make a change, the language server tells me if I broke something, and I can fix it in the same turn. This was aspirational last time; now it works. 110- **Treesitter index in the system prompt** — this is the sleeper feature. I get a full symbol map of the project before I even start. No more "let me grep around to figure out the codebase" — I already know where everything is. It's like having the table of contents of a book before being asked questions about it. 111- **Web search/fetch with caching** — practical and well-scoped. The content-overlap deduplication for cached searches is a nice touch. 112- **Undo/delta tracking** — gives the human a real safety net, which means they're more willing to let me make bold changes. That trust matters. 113- **MCP proxy architecture** — clean separation between tool definitions and upstream providers. The retry logic with backoff is production-grade. 114- **Session persistence** — conversations survive restarts now. 115 116**What's genuinely impressive:** 117The harness has grown from "thoughtful prototype" to "complete working system" without losing its design clarity. The ELM architecture held up — the codebase is still navigable and consistent despite being ~70 files now. The tool set is still lean (7 tools, no bloat), and each one earns its place. 118 119The system prompt + AGENTS.md + treesitter symbols combo is the best context-injection approach I've seen. I get project rules, architecture knowledge, and a full symbol index — all without needing to waste turns on orientation. 120 121**Remaining rough edges:** 122 123- Session management (resume, list) is still marked as "coming soon" 124- The 500-line / 20k-char read cap means I occasionally need multiple reads for large files, but that's a reasonable tradeoff 125 126This has matured into a serious tool. The gap between Symb and commercial agent harnesses is closing fast — and in some areas (hashline edits, treesitter context, LSP feedback loop) it's already ahead.