@@ -2,47 +2,62 @@
22
33 A code/pair programming tool for developers who use agents in their main workflows. Symbiotic pairing between developer and LLM. The developer has an agentic UI that provides the interface to the LLM, and a set of tools the LLM can use to cooperate in coding/development with the user.
44
5+## Vision
6+
57 Simple UI. Being a TUI, the goal is to be fast, have low memory usage, and avoid being a distraction to the code/content. Simple unicode border around the window. Agentic conversation on one side, code editor on the other. Matrix green for color (used rarely, only when a color is absolutely needed).
68
79 A TUI from the future. We want feature parity with a GUI editor: mouse selection, clicking, etc.
810
9-## Minimum viable product:
11+## Minimum Viable Product
12+
13+### Agentic UI
14+
15+- Support for clicking file references/diffs/snippets to open in Editor side.
16+- Optional Human-in-the-middle LLM tool call loop (with configurable permissions in global config)
17+- Auto Context, LLM is aware of file/project in question probably via tree-sitter?
18+- AGENTS.md support
19+
20+### Code/Diff Viewer (currently editor in read-only) UI
21+
22+- Line numbers, syntax highlighting
23+- LSP support
24+- Git integration (show file git status)
25+- Simple editting support, no advanced usages or keybinds. ** DONE BUT UNUSED FOR NOW, KEEP!! **
26+- Code browsing mouse features: click to go to definition/references. Search for word under cursor.
27+
28+### LLM Tools
29+
30+- Run in sandboxed version of the working directory to allow multiple agents working on the same file. Use git to merge sandboxed changes to real repo.
31+- Grep, Read, Write: optimized for code changes (LSP and linting checks after each edit). These appear in agentic UI as a diff message (not actual diff). Clicking on it takes us to that edit in the editor tab.
32+- Undo: Either perform an intelligent step back or use git to reset.
33+- Subagent tool: Performs a single task based on prompt.
34+- Mutation tools create a new branch worktress for the sandboxed environment. Perform the mutation. Once the user approves the mutation or tells the agent to merge, a git merge happens.
1035
11-- Agentic UI:
12- - Support for clicking file references/diffs/snippets to open in Editor side.
13- - Optional Human-in-the-middle LLM tool call loop (with configurable permissions in global config)
14- - Auto Context, LLM is aware of file/project in question probably via tree-sitter?
15- - AGENTS.md support
36+### Features
1637
17-- Code/Diff viewer (currently editor in read-only) UI:
18- - Line numbers, syntax highlighting
19- - LSP support
20- - Git integration (show file git status)
21- - Simple editting support, no advanced usages or keybinds. ** DONE BUT UNUSED FOR NOW, KEEP!! **
22- - Code browsing mouse features: click to go to definition/references. Search for word under cursor.
38+#### File Search: `<CTRL> + <f>`
2339
24-- LLM Tools:
25- - Run in sandboxed version of the working directory to allow multiple agents working on the same file. Use git to merge sandboxed changes to real repo.
26- - Grep, Read, Write: optimized for code changes (LSP and linting checks after each edit). These appear in agentic UI as a diff message (not actual diff). Clicking on it takes us to that edit in the editor tab.
27- - Undo: Either perform an intelligent step back or use git to reset.
28- - Subagent tool: Performs a single task based on prompt.
29- - Mutation tools create a new branch worktress for the sandboxed environment. Perform the mutation. Once the user approves the mutation or tells the agent to merge, a git merge happens.
40+Search files by filename or content (fuzzy matches, fast)
3041
31-- Features:
32- - `<CTRL> + <f>`: Search files by filename or content (fuzzy matches, fast)
33- - Opens a modal/overlay with a search box and a dynamic list of matches.
34- - Searching filters the list.
35- - Up/Down arrows select item in the list.
36- - Enter opens the currently matched/selected file.
37- - Includes the currently "opened" buffers in search at the top of the matches.
38- - We should find a library that does this for us, before trying to code our own fuzzy
42+- Opens a modal/overlay with a search box and a dynamic list of matches.
43+- Searching filters the list.
44+- Up/Down arrows select item in the list.
45+- Enter opens the currently matched/selected file.
46+- Includes the currently "opened" buffers in search at the top of the matches.
47+- We should find a library that does this for us, before trying to code our own fuzzy
3948
40- - `<CTRL> + <g>`: Open git diff in the editor.
49+#### Git Diff: `<CTRL> + <g>`
4150
42- - Selected text + `<CTRL> + <k>`: Send selected text to the LLM input.
43- - `<CTRL> + <k>`: Prompt at cursor, focus the input with information for the LLM about the user's cursor.
51+Open git diff in the editor.
4452
45-- Theme: Clean, straight corners, _suit and tie_-like. Use dark grayscale for almost everything on a clean black background. Matrix green used lightly (animated activity spinner). Single clean unicode lines (like in the drawing bellow)
53+#### LLM Interaction
54+
55+- Selected text + `<CTRL> + <k>`: Send selected text to the LLM input.
56+- `<CTRL> + <k>`: Prompt at cursor, focus the input with information for the LLM about the user's cursor.
57+
58+### Theme
59+
60+Clean, straight corners, _suit and tie_-like. Use dark grayscale for almost everything on a clean black background. Matrix green used lightly (animated activity spinner). Single clean unicode lines (like in the drawing bellow)
4661
4762 ## Mockup
4863
@@ -91,114 +106,133 @@ XXs 00:00 ───────────────────────
91106
92107 ```
93108
94-### Post mvp:
109+### Post-MVP
95110
96111 - Send input text to editor and send editor text to input/llm via keybinds
97112 - Send cursor position/filename to llm via keybind
98113 - Send selected text to llm via keybind
99114
100-## Tech:
115+## Technology Stack
116+
117+### Architecture
101118
102119 - True ELM architecture (no exceptions ever).
103120 - Strict project structure with separation of concern by internal modules.
104121 - Go (see https://github.com/tj/go-tea) For ELM architecture in TUI app (documentation).
105-- BubbleTea:
122+
123+### Core Libraries
124+
125+- **BubbleTea**:
106126 - Base library for TUI, use their bubbles, and all of the ecosystem.
107127 - Golden files based testing for the TUI.
108128 - https://github.com/charmbracelet/bubbletea Root BubbleTea.
109-- LLM Providers: Ollama local + Opencode Zen.
110-- Config driven: `./config.toml`.
129+- **LLM Providers**: Ollama local + Opencode Zen.
130+- **Config driven**: `./config.toml`.
131+
132+### Dependencies
111133
112-### References:
134+#### LSP Client
135+
136+- Candidate: `github.com/sourcegraph/go-lsp` (Battle-tested by Sourcegraph).
137+- Alternative: `go.lsp.dev/protocol` (Modern, modular).
138+
139+#### Mouse Support
140+
141+- Candidate: `github.com/lrstanley/bubblezone` (Wrapper for easier hit-testing/zoning).
142+
143+#### Editor
144+
145+- Official: `github.com/charmbracelet/bubbles/textarea` (Basic text input).
146+- Vim-like: `github.com/mieubrisse/vim-bubble` (Vim buffer emulation).
147+
148+#### Syntax Highlighting
149+
150+- Candidate: `github.com/alecthomas/chroma` (Standard Go syntax highlighter).
151+
152+### References
113153
114154 - ZOEA NOVA `~/src/zoea-nova`: A past project with a lot of overlap, also focused on LLM agentic loop.
115155 - Mysis `~/src/mysis`: Also a past project: raw CLI agentic tool for a dedicated agent (lots of overlap).
116156 - Cursor IDE (Cursor has this UX, but it's slow, leaks memory and it's more distracting than most other editors).
117157 - Opencode (TUI in `ink` does the same without the text editor, 75% feature overlap).
118158
119-### Dependencies:
159+## Implementation Roadmap
120160
121-- A LSP client implementation in Go.
122- - Candidate: `github.com/sourcegraph/go-lsp` (Battle-tested by Sourcegraph).
123- - Alternative: `go.lsp.dev/protocol` (Modern, modular).
124-- Mouse events/mouse support for BubbleTea.
125- - Candidate: `github.com/lrstanley/bubblezone` (Wrapper for easier hit-testing/zoning).
126-- Editor:
127- - Official: `github.com/charmbracelet/bubbles/textarea` (Basic text input).
128- - Vim-like: `github.com/mieubrisse/vim-bubble` (Vim buffer emulation).
129-- Syntax Highlighting:
130- - Candidate: `github.com/alecthomas/chroma` (Standard Go syntax highlighter).
161+### MVP Phases
131162
132-# The Main Challenge Remaining:
163+#### Phase 1: Basic TUI with editor + agent pane (no LSP, no git sandbox)
133164
134-State Management. You have three asynchronous "gods" to serve:
165+- File viewer with syntax highlighting
166+- Agent conversation with tool calls (Read/Write/Grep)
135167
136- 1. User Input (Keyboard/Mouse) -> Instant.
137- 2. LSP Server (Diagnostics/Completions) -> Fast (ms).
138- 3. LLM Agent (Thinking/Tools) -> Slow (seconds).
168+#### Phase 2: Git integration
139169
140-BubbleTea's ELM architecture (Update() loop) is perfect for this if you keep the heavy lifting (LLM/LSP) in separate Go routines that send messages back to the main thread. If you block the main thread, the UI will freeze.
141-Confidence Level: High for a prototype. The ecosystem is ready.
170+- Show git status in editor
171+- Ctrl+g for diffs
172+- Simple diff preview before applying
173+- Agent commits to real repo (no sandbox yet)
142174
143-## MVP Phases:
144-
145-1. Phase 1: Basic TUI with editor + agent pane (no LSP, no git sandbox)
146- - File viewer with syntax highlighting
147- - Agent conversation with tool calls (Read/Write/Grep)
148- - Simple diff preview before applying
149-2. Phase 2: Git integration
150- - Show git status in editor
151- - Ctrl+g for diffs
152- - Agent commits to real repo (no sandbox yet)
153-3. Phase 3: LSP integration
154- - Start with diagnostics only
155- - Add go-to-definition later
156-4. Phase 4: Advanced features
157- - Sandboxed worktrees
158- - Sub-agents
159- - Context optimization with tree-sitter
160-
161-# TODO:
175+#### Phase 3: LSP integration
162176
163-- Grep is not matching pathname:
177+- Start with diagnostics only
178+- Add go-to-definition later
164179
165-```
166-The Grep tool was called with the following arguments:
167-
168-- `pattern`: `"mcp_tools.go"`
169-- `content_search`: `false` (filename search, not content grep)
170-- `case_sensitive`: `false` (default, case-insensitive)
171-- `max_results`: `100` (default)
172-
173-This means the tool was searching for files named
174-`mcp_tools.go` (or similar, due to fuzzy matching) in the
175-current directory and tracked paths (while respecting
176-`.gitignore`). Let me know if you'd like to tweak these
177-parameters!
178-```
180+#### Phase 4: Advanced features
179181
180-- Show tool call arguments expanded:
182+- Sandboxed worktrees
183+- Sub-agents
184+- Context optimization with tree-sitter
181185
182-```
183- Grep(pattern="...", ...)
184-```
186+### The Main Challenge: State Management
185187
186-- truncate tool reposnses. (time for verbose?)
188+You have three asynchronous "gods" to serve:
187189
188-- Add Prompt, and AGENTS.md support.
190+1. User Input (Keyboard/Mouse) -> Instant.
191+2. LSP Server (Diagnostics/Completions) -> Fast (ms).
192+3. LLM Agent (Thinking/Tools) -> Slow (seconds).
189193
190-- websearch tool (exa tools?)
194+BubbleTea's ELM architecture (Update() loop) is perfect for this if you keep the heavy lifting (LLM/LSP) in separate Go routines that send messages back to the main thread. If you block the main thread, the UI will freeze.
191195
192-- Make file references clickable in coversation (including tool calls output.)
196+Confidence Level: High for a prototype. The ecosystem is ready.
193197
194-- Copy text selection to clipboard (shift + arrows) then (ctrl + shift + c)
198+## TODO
195199
196-- file searching and opening, buffer switching. do I even want this, just make llm tools and ask it.
200+### Bug Fixes
197201
198-- streamed assistant response
202+- Grep is not matching pathname:
203+
204+ ```
205+ The Grep tool was called with the following arguments:
199206
207+ - `pattern`: `"mcp_tools.go"`
208+ - `content_search`: `false` (filename search, not content grep)
209+ - `case_sensitive`: `false` (default, case-insensitive)
210+ - `max_results`: `100` (default)
211+
212+ This means the tool was searching for files named
213+ `mcp_tools.go` (or similar, due to fuzzy matching) in the
214+ current directory and tracked paths (while respecting
215+ `.gitignore`). Let me know if you'd like to tweak these
216+ parameters!
217+ ```
218+
219+### UI Enhancements
220+
221+- Show tool call arguments expanded:
222+ ```
223+ Grep(pattern="...", ...)
224+ ```
225+- truncate tool reposnses. (time for verbose?)
226+- Make file references clickable in coversation (including tool calls output.)
227+- Copy text selection to clipboard (shift + arrows) then (ctrl + shift + c)
228+- streamed assistant response
200229 - Fun: Show icon in unicode and a highlight color clock centered in the right panel when there are no messages.
201230
231+### Features
232+
233+- websearch tool (exa tools?)
234+- file searching and opening, buffer switching. do I even want this, just make llm tools and ask it.
235+
202236 ## Future Enhancements
203237
204238 ### Planned Features