xonecas.io
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.