Code Assistant

1# Code Assistant
2 
3[![CI](https://github.com/stippi/code-assistant/actions/workflows/build.yml/badge.svg)](https://github.com/stippi/code-assistant/actions/workflows/build.yml)
4[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/stippi/code-assistant)](https://archestra.ai/mcp-catalog/stippi__code-assistant)
5 
6An AI coding assistant built in Rust that provides both command-line and graphical interfaces for autonomous code analysis and modification.
7 
8## Key Features
9 
10**Multi-Modal Tool Execution**: Adapts to different LLM capabilities with pluggable tool invocation modes - native function calling, XML-style tags, and triple-caret blocks - ensuring compatibility across various AI providers.
11 
12**Real-Time Streaming Interface**: Advanced streaming processors parse and display tool invocations as they stream from the LLM, with smart filtering to prevent unsafe tool combinations.
13 
14**Session-Based Project Management**: Each chat session is tied to a specific project and maintains persistent state, working memory, and draft messages with attachment support.
15 
16**Multiple Interface Options**: Choose between a modern GUI built on Zed's GPUI framework, traditional terminal interface, or headless MCP server mode for integration with MCP clients such as Claude Desktop.
17 
18**Agent Client Protocol (ACP) Support**: Full compatibility with the [Agent Client Protocol](https://agentclientprotocol.com/) standard, enabling seamless integration with ACP-compatible editors like [Zed](https://zed.dev). See Zed's documentation on [adding custom agents](https://zed.dev/docs/ai/external-agents#add-custom-agents) for setup instructions.
19 
20**Session Compaction**: Before running out of context space, the agent generates a session summary and continues work.
21 
22**Auto-Loaded Repository Guidance**: Automatically includes `AGENTS.md` (or `CLAUDE.md` fallback) from the project root in the assistant's system context to align behavior with repo-specific instructions.
23 
24## Installation
25 
26```bash
27# On macOS or Linux, install Rust tool chain via rustup:
28curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
29 
30# On Linux, install libxkbcommon‑dev and libxkbcommon‑x11‑dev
31 
32# On macOS, you need the metal tool chain:
33xcodebuild -downloadComponent MetalToolchain
34 
35# Then clone the repo and build it:
36git clone https://github.com/stippi/code-assistant
37cd code-assistant
38cargo build --release
39```
40 
41The binary will be available at `target/release/code-assistant`.
42 
43### Initial Setup
44 
45After building, create your configuration files:
46 
47```bash
48# Create config directory
49mkdir -p ~/.config/code-assistant
50 
51# Copy example configurations
52cp providers.example.json ~/.config/code-assistant/providers.json
53cp models.example.json ~/.config/code-assistant/models.json
54 
55# Edit the files to add your API keys
56# Set environment variables or update the JSON files directly
57export ANTHROPIC_API_KEY="sk-ant-..."
58export OPENAI_API_KEY="sk-..."
59```
60 
61See the [Configuration](#configuration) section for detailed setup instructions.
62 
63## Project Configuration
64 
65Create `~/.config/code-assistant/projects.json` to define available projects:
66 
67```jsonc
68{
69  "code-assistant": {
70    "path": "/Users/<username>/workspace/code-assistant",
71    "format_on_save": {
72      "**/*.rs": "cargo fmt" // Formats all files in project, so make sure files are already formatted
73    }
74  },
75  "my-project": {
76    "path": "/Users/<username>/workspace/my-project",
77    "format_on_save": {
78      "**/*.ts": "prettier --write {path}" // If the formatter accepts a path, provide "{path}"
79    }
80  }
81}
82```
83 
84### Format-on-Save Feature
85 
86The _optional_ `format_on_save` field allows automatic formatting of files after modifications. It maps file patterns (using glob syntax) to shell commands:
87- Files matching the glob patterns will be automatically formatted after being modified by the assistant
88- The tool parameters are updated to reflect the formatted content, keeping the LLM's mental model in sync
89- This prevents edit conflicts caused by auto-formatting
90 
91See [docs/format-on-save-feature.md](docs/format-on-save-feature.md) for detailed documentation.
92 
93**Important Notes:**
94- When launching from a folder not in this configuration, a temporary project is created automatically
95- The assistant has access to the current project (including temporary ones) plus all configured projects
96- Each chat session is permanently associated with its initial project and folder - this cannot be changed later
97- Tool syntax (native/xml/caret) is also fixed per session at creation time
98 
99## Usage
100 
101### GUI Mode (Recommended)
102 
103```bash
104# Start with graphical interface
105code-assistant --ui
106 
107# Start GUI with initial task
108code-assistant --ui --task "Analyze the authentication system"
109```
110 
111### Terminal Mode
112 
113```bash
114# Basic usage
115code-assistant --task "Explain the purpose of this codebase"
116 
117# With specific model
118code-assistant --task "Add error handling" --model "GPT-5"
119```
120 
121### MCP Server Mode
122 
123```bash
124code-assistant server
125```
126 
127### ACP Agent Mode
128 
129```bash
130# Run as ACP-compatible agent
131code-assistant acp
132 
133# With specific model
134code-assistant acp --model "Claude Sonnet 4.5"
135```
136 
137The ACP mode enables integration with editors that support the [Agent Client Protocol](https://agentclientprotocol.com/), such as [Zed](https://zed.dev). When running in ACP mode, the code-assistant communicates via JSON-RPC over stdin/stdout, supporting features like pending messages, real-time streaming, and tool execution with proper permission handling.
138 
139## Configuration
140 
141### Model Configuration
142 
143The code-assistant uses two JSON configuration files to manage LLM providers and models:
144 
145**`~/.config/code-assistant/providers.json`** - Configure provider credentials and endpoints:
146```json
147{
148  "anthropic": {
149    "label": "Anthropic Claude",
150    "provider": "anthropic",
151    "config": {
152      "api_key": "${ANTHROPIC_API_KEY}",
153      "base_url": "https://api.anthropic.com/v1"
154    }
155  },
156  "openai": {
157    "label": "OpenAI",
158    "provider": "openai-responses",
159    "config": {
160      "api_key": "${OPENAI_API_KEY}"
161    }
162  }
163}
164```
165 
166**`~/.config/code-assistant/models.json`** - Define available models:
167```json
168{
169  "Claude Sonnet 4.5 (Thinking)": {
170    "provider": "anthropic",
171    "id": "claude-sonnet-4-5",
172    "config": {
173      "max_tokens": 32768,
174      "thinking": {
175        "type": "enabled",
176        "budget_tokens": 8192
177      }
178    }
179  },
180  "Claude Sonnet 4.5": {
181    "provider": "anthropic",
182    "id": "claude-sonnet-4-5",
183    "config": {
184      "max_tokens": 32768
185    }
186  },
187  "GPT-5": {
188    "provider": "openai",
189    "id": "gpt-5-codex",
190    "config": {
191      "temperature": 0.7
192    }
193  }
194}
195```
196 
197**Environment Variable Substitution**: Use `${VAR_NAME}` in provider configs to reference environment variables for API keys.
198 
199**Full Examples**: See [`providers.example.json`](providers.example.json) and [`models.example.json`](models.example.json) for complete configuration examples with all supported providers (Anthropic, OpenAI, Ollama, SAP AI Core, Vertex AI, Groq, Cerebras, MistralAI, OpenRouter).
200 
201### Tool Configuration
202 
203Some tools require external API keys to function. Configure these in `~/.config/code-assistant/tools.json`:
204 
205```json
206{
207  "perplexity_api_key": "${PERPLEXITY_API_KEY}"
208}
209```
210 
211**Available Tool Settings**:
212- `perplexity_api_key` - Enables the `perplexity_ask` tool for AI-powered web search
213 
214Tools without their required configuration will not be available to the assistant.
215 
216**List Available Models**:
217```bash
218# See all configured models
219code-assistant --list-models
220 
221# See all configured providers
222code-assistant --list-providers
223```
224 
225<details>
226<summary>Claude Desktop Integration (MCP)</summary>
227 
228Configure in Claude Desktop settings (**Developer** tab → **Edit Config**):
229 
230```jsonc
231{
232  "mcpServers": {
233    "code-assistant": {
234      "command": "/path/to/code-assistant/target/release/code-assistant",
235      "args": ["server"],
236      "env": {
237        "SHELL": "/bin/zsh"                 // Your login shell
238      }
239    }
240  }
241}
242```
243 
244</details>
245 
246<details>
247<summary>Zed Editor Integration (ACP)</summary>
248 
249Configure in Zed settings:
250 
251```json
252{
253  "agent_servers": {
254    "Code-Assistant": {
255      "command": "/path/to/code-assistant/target/release/code-assistant",
256      "args": ["acp", "--model", "Claude Sonnet 4.5"],
257      "env": {
258        "ANTHROPIC_API_KEY": "sk-ant-..."
259      }
260    }
261  }
262}
263```
264 
265Make sure your `providers.json` and `models.json` are configured with the model you specify. The agent will appear in Zed's assistant panel with full ACP support.
266 
267For detailed setup instructions, see [Zed's documentation on adding custom agents](https://zed.dev/docs/ai/external-agents#add-custom-agents).
268</details>
269 
270<details>
271<summary>Advanced Options</summary>
272 
273**Tool Syntax Modes**:
274- `--tool-syntax native`: Use the provider's built-in tool calling (most reliable, but streaming of parameters depends on provider)
275- `--tool-syntax xml`: XML-style tags for streaming of parameters
276- `--tool-syntax caret`: Triple-caret blocks for token-efficiency and streaming of parameters
277 
278**Session Recording**:
279```bash
280# Record session (Anthropic only)
281code-assistant --record session.json --model "Claude Sonnet 4.5" --task "Optimize database queries"
282 
283# Playback session
284code-assistant --playback session.json --fast-playback
285```
286 
287**Other Options**:
288- `--model <name>`: Specify model from models.json (use `--list-models` to see available options)
289- `--continue-task`: Resume from previous session state
290- `--use-diff-format`: Enable alternative diff format for file editing
291- `--sandbox-mode <danger-full-access|read-only|workspace-write>`: Choose the sandbox policy for command execution (default `danger-full-access`)
292- `--sandbox-network`: When combined with `--sandbox-mode workspace-write`, allow outbound network access - inside the sandbox
293- `--verbose` / `-v`: Enable detailed logging (use multiple times for more verbosity)
294</details>
295 
296## Architecture Highlights
297 
298The code-assistant features several innovative architectural decisions:
299 
300**Adaptive Tool Syntax**: Automatically generates different system prompts and streaming processors based on the target LLM's capabilities, allowing the same core logic to work across providers with varying function calling support.
301 
302**Smart Tool Filtering**: Real-time analysis of tool invocation patterns prevents logical errors like attempting to edit files before reading them, with the ability to truncate responses mid-stream when unsafe combinations are detected.
303 
304**Multi-Threaded Streaming**: Sophisticated async architecture that handles real-time parsing of tool invocations while maintaining responsive UI updates and proper state management across multiple chat sessions.
305 
306## Contributing
307 
308Contributions are welcome! The codebase demonstrates advanced patterns in async Rust, AI agent architecture, and cross-platform UI development.
309 
310## Roadmap
311 
312This section is not really a roadmap, as the items are in no particular order.
313Below are some topics that are likely the next focus.
314 
315- **Block Replacing in Changed Files**: When streaming a tool use block, we already know the LLM attempts to use `replace_in_file` and we know in which file quite early.
316  If we also know this file has changed since the LLM last read it, we can block the attempt with an appropriate error message.
317- **Compact Tool Use Failures**: When the LLM produces an invalid tool call, or a mismatching search block, we should be able to strip the failed attempt from the message history, saving tokens.
318- **Improve UI**: There are various ways in which the UI can be improved.
319- **Add Memory Tools**: Add tools that facilitate building up a knowledge base useful work working in a given project.
320- **Security**: Ideally, the execution for all tools would run in some sort of sandbox that restricts access to the files in the project tracked by git.
321  Currently, the tools reject absolute paths, but do not check whether the relative paths point outside the project or try to access git-ignored files.
322  The `execute_command` tool runs a shell with the provided command line, which at the moment is completely unchecked.
323- **Fuzzy matching search blocks**: Investigate the benefit of fuzzy matching search blocks.
324  Currently, files are normalized (always `\n` line endings, no trailing white space).
325  This increases the success rate of matching search blocks quite a bit, but certain ways of fuzzy matching might increase the success even more.
326  Failed matches introduce quite a bit of inefficiency, since they almost always trigger the LLM to re-read a file.
327  Even when the error output of the `replace_in_file` tool includes the complete file and tells the LLM *not* to re-read the file.
328- **Edit user messages**: Editing a user message should create a new branch in the session.
329  The user should still be able to toggle the active banches.
330