code-assistant

What is Code Assistant?

Code Assistant is an LLM-powered, autonomous coding assistant built in Rust. It is designed to help developers with various code-related tasks by intelligently exploring codebases, reading and writing files, and interacting with users for better decision-making. It also offers an MCP (Model Context Protocol) server mode, allowing it to function as a plugin for MCP client applications like Claude Desktop.

How to use Code Assistant?

Installation

1. Prerequisites: Ensure you have Rust installed on your system.
2. Clone the repository:

   git clone https://github.com/stippi/code-assistant
   

3. Navigate to the project directory:

   cd code-assistant
   

4. Build the project:

   cargo build --release
   

   The executable will be located at target/release/code-assistant.

Configuration in Claude Desktop (for MCP Server Mode)

1. Configure Your Projects: Create a file ~/.config/code-assistant/projects.json to define available projects for the MCP server mode. This file maps project names to their absolute paths.

   {
     "code-assistant": {
       "path": "/Users/<username>/workspace/code-assistant"
     },
     "asteroids": {
       "path": "/Users/<username>/workspace/asteroids"
     }
   }
   

2. Configure MCP Servers: In Claude Desktop settings, go to the Developer tab and click Edit Config. Open claude_desktop_config.json and add a configuration for code-assistant under mcpServers.

   {
     "mcpServers": {
       "code-assistant": {
         "command": "/Users/<username>/workspace/code-assistant/target/release/code-assistant",
         "args": [
           "server"
         ]
       }
     }
   }
   

Usage Modes

1. Agent Mode (Default)

Run tasks directly from the command line:

code-assistant --task <TASK> [OPTIONS]

Key Options:

• --path <PATH>: Path to the code directory (default: current directory).
• -t, --task <TASK>: Task to perform (required in terminal mode, optional with --ui).
• --ui: Start with a GUI interface.
• -p, --provider <PROVIDER>: LLM provider to use (e.g., anthropic, openai, ollama).
• -m, --model <MODEL>: Specific model name to use.

Examples:

• code-assistant --task "Explain the purpose of this codebase"
• code-assistant --ui --task "Refactor the authentication module"
• code-assistant --task "Document this API" --provider ollama --model llama2

2. Server Mode

Run as a Model Context Protocol server:

code-assistant server [OPTIONS]

• -v, --verbose: Enable verbose logging.

Key Features of Code Assistant

• Autonomous Exploration: The agent can intelligently explore codebases and build a working memory of project structure.
• Reading/Writing Files: Ability to read file contents and make necessary changes to files.
• User Interface: Can run with a GUI based on Zed's gpui.
• Interactive Communication: Facilitates asking users questions and receiving responses for informed decision-making.
• MCP Server Mode: Functions as a Model Context Protocol server, providing tools and resources to LLMs in an MCP client.
• Multiple LLM Provider Support: Supports various LLM providers including Anthropic, OpenAI, Ollama, Vertex, and OpenRouter.

Use Cases of Code Assistant

• Codebase Understanding: Quickly grasp the purpose and structure of unfamiliar codebases.
• Automated Code Modifications: Perform tasks like adding error handling, refactoring modules, or optimizing code.
• Security Reviews: Analyze code for potential security vulnerabilities.
• API Documentation: Generate documentation for APIs.
• Interactive Development: Collaborate with the AI assistant through a GUI for complex tasks.
• Integration with MCP Clients: Extend the capabilities of MCP client applications like Claude Desktop by providing code-related tools.

FAQ from Code Assistant

Q: What LLM providers does Code Assistant support? A: Code Assistant supports Anthropic, OpenAI, Ollama, Vertex, and OpenRouter.

Q: Can I use Code Assistant with a GUI? A: Yes, you can start Code Assistant with a GUI using the --ui flag.

Q: How do I configure Code Assistant for use with Claude Desktop? A: You need to configure projects.json to define your projects and claude_desktop_config.json to add Code Assistant as an MCP server in Claude Desktop's settings.

Q: Is there a way to record and playback sessions? A: Yes, you can record API responses to a file (currently for Anthropic provider only) using --record and play them back using --playback.

Q: What are the security considerations when using Code Assistant? A: The project notes that it has insufficient protection against prompt injections and should be used with trusted repositories only. The execute_command tool runs a shell with the provided command line, which is currently unchecked. Future improvements aim to enhance security by sandboxing tool execution and restricting file access.

Code Assistant

A CLI tool built in Rust for assisting with code-related tasks.

Features

• Autonomous Exploration: The agent can intelligently explore codebases and build up working memory of the project structure.
• Reading/Writing Files: The agent can read file contents and make changes to files as needed.
• User Interface: The agent can run with a UI based on Zed's gpui.
• Interactive Communication: Ability to ask users questions and get responses for better decision-making.
• MCP Server Mode: Can run as a Model Context Protocol server, providing tools and resources to LLMs running in an MCP client.

Installation

Ensure you have Rust installed on your system. Then:

# Clone the repository
git clone https://github.com/stippi/code-assistant

# Navigate to the project directory
cd code-assistant

# Build the project
cargo build --release

# The binary will be available in target/release/code-assistant

Configuration in Claude Desktop

The code-assistant implements the Model Context Protocol by Anthropic. This means it can be added as a plugin to MCP client applications such as Claude Desktop.

Configure Your Projects

Create a file ~/.config/code-assistant/projects.json. This file adds available projects in MCP server mode (list_projects and file operation tools). It has the following structure:

{
  "code-assistant": {
    "path": "/Users/<username>/workspace/code-assistant"
  },
  "asteroids": {
    "path": "/Users/<username>/workspace/asteroids"
  },
  "zed": {
    "path": "Users/<username>/workspace/zed"
  }
}

Notes:

• The absolute paths are not provided by the tool, to avoid leaking such information to LLM cloud providers.
• This file can be edited without restarting Claude Desktop, respectively the MCP server.

Configure MCP Servers

• Open the Claude Desktop application settings (Claude -> Settings)
• Switch to the Developer tab.
• Click the Edit Config button.

A Finder window opens highlighting the file claude_desktop_config.json. Open that file in your favorite text editor.

An example configuration is given below:

{
  "mcpServers": {
    "code-assistant": {
      "command": "/Users/<username>/workspace/code-assistant/target/release/code-assistant",
      "args": [
        "server"
      ],
      "env": {
        "PERPLEXITY_API_KEY": "pplx-...", // optional, enables perplexity_ask tool
        "SHELL": "/bin/zsh" // your login shell, required when configuring "env" here
      }
    }
  }
}

Usage

Code Assistant can run in two modes:

Agent Mode (Default)

code-assistant --task <TASK> [OPTIONS]

Available options:

• --path <PATH>: Path to the code directory to analyze (default: current directory)
• -t, --task <TASK>: Task to perform on the codebase (required in terminal mode, optional with --ui)
• --ui: Start with GUI interface
• --continue-task: Continue from previous state
• -v, --verbose: Enable verbose logging
• -p, --provider <PROVIDER>: LLM provider to use [ai-core, anthropic, open-ai, ollama, vertex, open-router] (default: anthropic)
• -m, --model <MODEL>: Model name to use (provider-specific defaults: anthropic="claude-sonnet-4-20250514", open-ai="gpt-4o", vertex="gemini-2.5-pro-preview-06-05", open-router="anthropic/claude-3-7-sonnet", ollama=required)
• --base-url <BASE_URL>: API base URL for the LLM provider to use
• --tools-type <TOOLS_TYPE>: Type of tool declaration [native, xml] (default: xml) - native = tools via API, xml = custom system message
• --num-ctx <NUM_CTX>: Context window size in tokens (default: 8192, only relevant for Ollama)
• --record <RECORD>: Record API responses to a file (only supported for Anthropic provider currently)
• --playback <PLAYBACK>: Play back a recorded session from a file
• --fast-playback: Fast playback mode - ignore chunk timing when playing recordings

Environment variables:

• ANTHROPIC_API_KEY: Required when using the Anthropic provider
• OPENAI_API_KEY: Required when using the OpenAI provider
• GOOGLE_API_KEY: Required when using the Vertex provider
• OPENROUTER_API_KEY: Required when using the OpenRouter provider
• PERPLEXITY_API_KEY: Required to use the Perplexity search API tools
• Note: AI Core authentication is configured on the command line (the tool will prompt for the parameters and store them in your default keychain)

Examples:

# Analyze code in current directory using Anthropic's Claude
code-assistant --task "Explain the purpose of this codebase"

# Use a different provider and model
code-assistant --task "Review this code for security issues" --provider openai --model gpt-4o

# Analyze a specific directory with verbose logging
code-assistant --path /path/to/project --task "Add error handling" --verbose

# Start with GUI interface
code-assistant --ui

# Start GUI with an initial task
code-assistant --ui --task "Refactor the authentication module"

# Use Ollama with a local model
code-assistant --task "Document this API" --provider ollama --model llama2 --num-ctx 4096

# Record a session for later playback (Anthropic only)
code-assistant --task "Optimize database queries" --record ./recordings/db-optimization.json

# Play back a recorded session with fast-forward (no timing delays)
code-assistant --playback ./recordings/db-optimization.json --fast-playback

Server Mode

Runs as a Model Context Protocol server:

code-assistant server [OPTIONS]

Available options:

• -v, --verbose: Enable verbose logging

Roadmap

This section is not really a roadmap, as the items are in no particular order. Below are some topics that are likely the next focus.

• Improve UI: There are various ways in which the UI can be improved.
• Add Memory Tools: Add tools that facilitate building up a knowledge base useful work working in a given project.
• 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. 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. The execute_command tool runs a shell with the provided command line, which at the moment is completely unchecked.
• Fuzzy matching search blocks: Investigate the benefit of fuzzy matching search blocks. Currently, files are normalized (always \n line endings, no trailing white space). This increases the success rate of matching search blocks quite a bit, but certain ways of fuzzy matching might increase the success even more. Failed matches introduce quite a bit of inefficiency, since they almost always trigger the LLM to re-read a file. 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.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.