@@ -0,0 +1,111 @@
1+# (agent) Smith
2+
3+A code/pair programming tool for developers who use agents in their main workflows. Inspired by the Agent Smith character in the popular movie "The Matrix". 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.
4+
5+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).
6+
7+A TUI from the future. We want feature parity with a GUI editor: mouse selection, clicking, etc.
8+
9+## Minimum viable product:
10+
11+- Agentic UI:
12+ - Support for highlighted code snippets. Git diffs and shell outputs. (Mini editor components?)
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
16+
17+- Code/Diff viewer 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.
22+ - Code browsing mouse features: click to go to definition/references. Search for word under cursor.
23+
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. 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.
30+
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+
39+ - `<CTRL> + <g>`: Open git diff in the editor.
40+
41+ - Selected text + `<CTRL> + <k>`: Send selected text to the LLM input.
42+ - `<CTRL> + <k>`: Prompt at cursor, focus the input with information for the LLM about the user's cursor.
43+
44+- 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)
45+
46+## Mockup
47+
48+```text
49+╭─────────────────────────────────────┬────────────────────────────────────╮
50+│ 102 │ ● Agent Smith │ // Flexible height.
51+│ 103 pub fn wake_up(neo: &User) { │ │ // Panes split 50% each
52+│ 104 // TODO: Implement signal │ ┌─ Assistant ────────────────────┐ │
53+│ 105 let signal = Signal::new();│ │ I see you're working on the │ │ // Assistant message
54+│ 106 │ │ wake_up function. │ │ // - Messages have their embedded code highlighter for code blocks, diffs etc.
55+│ 107 if neo.is_ready() { │ │ │ │ // - Shows short reasoning (toggleable in the options)
56+│ 108 neo.disconnect(); │ │ Would you like me to generate │ │ // - Shows tool calls/tool response is stylized human readable format.
57+│ 109 } else { │ │ the Signal implementation? │ │
58+│ 110 neo.sleep(); │ │ │ │ // Conversation log takes a lot of inspiration from Opencode.
59+│ 111 } │ │ [Generate] [Diff] [Ignore] │ │
60+│ 112 } │ └────────────────────────────────┘ │
61+│ 113 │ │
62+│ 114 │ ┌─ Input ────────────────────────┐ │
63+│ 115 │ │ /bash cargo check │ │ // Input box, user can cycle history with arrows *up/down*
64+│ 116 │ └────────────────────────────────┘ │ // - Input supports commands /Read /Grep /Write (call the same tools as the LLM sees)
65+├─────────────────────────────────────┴────────────────────────────────────┤
66+│ master* │ src/matrix/core.rs[+] ⣽ │ // Git branch, current file if any ending with an
67+╰──────────────────────────────────────────────────────────────────────────╯ // animated icon: fast animation when LLM is thinking, slow when idle.
68+```
69+
70+## Tech:
71+
72+- True ELM architecture (no exceptions ever).
73+ - Strict project structure with separation of concern by internal modules.
74+- Go (see https://github.com/tj/go-tea) For ELM architecture in TUI app.
75+- BubbleTea:
76+ - Base library for TUI, use their bubbles, and all of the ecosystem.
77+ - Golden files based testing for the TUI.
78+ - https://github.com/charmbracelet/bubbletea Root BubbleTea.
79+- LLM Providers: Ollama local + Opencode Zen.
80+- Config driven: `./config.toml`.
81+
82+### References:
83+
84+- ZOEA NOVA `~/src/zoea-nova`: A past project with a lot of overlap, also focused on LLM agentic loop.
85+- Mysis `~/src/mysis`: Also a past project: raw CLI agentic tool for a dedicated agent (lots of overlap).
86+- Cursor IDE (Cursor has this UX, but it's slow, leaks memory and it's more distracting than most other editors).
87+- Opencode (TUI in `ink` does the same without the text editor, 75% feature overlap).
88+
89+### Dependencies:
90+
91+- A LSP client implementation in Go.
92+ - Candidate: `github.com/sourcegraph/go-lsp` (Battle-tested by Sourcegraph).
93+ - Alternative: `go.lsp.dev/protocol` (Modern, modular).
94+- Mouse events/mouse support for BubbleTea.
95+ - Candidate: `github.com/lrstanley/bubblezone` (Wrapper for easier hit-testing/zoning).
96+- Editor:
97+ - Official: `github.com/charmbracelet/bubbles/textarea` (Basic text input).
98+ - Vim-like: `github.com/mieubrisse/vim-bubble` (Vim buffer emulation).
99+- Syntax Highlighting:
100+ - Candidate: `github.com/alecthomas/chroma` (Standard Go syntax highlighter).
101+
102+# The Main Challenge Remaining:
103+
104+State Management. You have three asynchronous "gods" to serve:
105+
106+ 1. User Input (Keyboard/Mouse) -> Instant.
107+ 2. LSP Server (Diagnostics/Completions) -> Fast (ms).
108+ 3. LLM Agent (Thinking/Tools) -> Slow (seconds).
109+
110+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.
111+Confidence Level: High for a prototype. The ecosystem is ready.