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.

Installation

# On macOS or Linux, install Rust tool chain via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# On Linux, install libxkbcommon‑dev and libxkbcommon‑x11‑dev

# On macOS, you need the metal tool chain:
xcodebuild -downloadComponent MetalToolchain

# Then clone the repo and build it:
git clone https://github.com/stippi/code-assistant
cd code-assistant
cargo build --release

The binary will be available at target/release/code-assistant.

Initial Setup

After building, create your configuration files:

# Create config directory
mkdir -p ~/.config/code-assistant

# Copy example configurations
cp providers.example.json ~/.config/code-assistant/providers.json
cp models.example.json ~/.config/code-assistant/models.json

# Edit the files to add your API keys
# Set environment variables or update the JSON files directly
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

See the Configuration section for detailed setup instructions.

Project Configuration

Create ~/.config/code-assistant/projects.json to define available projects:

{
  "code-assistant": {
    "path": "/Users/<username>/workspace/code-assistant",
    "format_on_save": {
      "**/*.rs": "cargo fmt" // Formats all files in project, so make sure files are already formatted
    }
  },
  "my-project": {
    "path": "/Users/<username>/workspace/my-project",
    "format_on_save": {
      "**/*.ts": "prettier --write {path}" // If the formatter accepts a path, provide "{path}"
    }
  }
}

Format-on-Save Feature

The optional format_on_save field allows automatic formatting of files after modifications. It maps file patterns (using glob syntax) to shell commands:

• Files matching the glob patterns will be automatically formatted after being modified by the assistant
• The tool parameters are updated to reflect the formatted content, keeping the LLM's mental model in sync
• This prevents edit conflicts caused by auto-formatting

See docs/format-on-save-feature.md for detailed documentation.

Important Notes:

• When launching from a folder not in this configuration, a temporary project is created automatically
• The assistant has access to the current project (including temporary ones) plus all configured projects
• Each chat session is permanently associated with its initial project and folder - this cannot be changed later
• Tool syntax (native/xml/caret) is also fixed per session at creation time

Usage

GUI Mode (Recommended)

# Start with graphical interface
code-assistant --ui

# Start GUI with initial task
code-assistant --ui --task "Analyze the authentication system"

Terminal Mode

# Basic usage
code-assistant --task "Explain the purpose of this codebase"

# With specific model
code-assistant --task "Add error handling" --model "GPT-5"

Working Directory Matters

The directory from which you launch code-assistant determines the project context for your session. The assistant uses your current working directory (PWD) to understand which codebase you're working on — it scopes file operations, searches, and tool execution to that directory.

Best practice: Always cd into your project's root directory before starting code-assistant.

cd ~/workspace/my-project
code-assistant --ui

Chats are grouped by directory, so starting a new chat from the correct project directory ensures:

• The assistant has the right file context and can navigate your codebase
• Your conversation history stays organized per project
• AGENTS.md or CLAUDE.md guidance files from that project are automatically loaded

If you need to work on a different project, open a new chat from that project's directory rather than reusing an existing session from another location.

MCP Server Mode

code-assistant server

ACP Agent Mode

# Run as ACP-compatible agent
code-assistant acp

# With specific model
code-assistant acp --model "Claude Sonnet 4.5"

The ACP mode enables integration with editors that support the Agent Client Protocol, such as Zed. 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.

Configuration

Model Configuration

The code-assistant uses two JSON configuration files to manage LLM providers and models:

~/.config/code-assistant/providers.json - Configure provider credentials and endpoints:

{
  "anthropic": {
    "label": "Anthropic Claude",
    "provider": "anthropic",
    "config": {
      "api_key": "${ANTHROPIC_API_KEY}",
      "base_url": "https://api.anthropic.com/v1"
    }
  },
  "openai": {
    "label": "OpenAI",
    "provider": "openai-responses",
    "config": {
      "api_key": "${OPENAI_API_KEY}"
    }
  }
}

~/.config/code-assistant/models.json - Define available models:

{
  "Claude Sonnet 4.5 (Thinking)": {
    "provider": "anthropic",
    "id": "claude-sonnet-4-5",
    "config": {
      "max_tokens": 32768,
      "thinking": {
        "type": "enabled",
        "budget_tokens": 8192
      }
    }
  },
  "Claude Sonnet 4.5": {
    "provider": "anthropic",
    "id": "claude-sonnet-4-5",
    "config": {
      "max_tokens": 32768
    }
  },
  "GPT-5": {
    "provider": "openai",
    "id": "gpt-5-codex",
    "config": {
      "temperature": 0.7
    }
  }
}

Environment Variable Substitution: Use ${VAR_NAME} in provider configs to reference environment variables for API keys.

Full Examples: See providers.example.json and models.example.json for complete configuration examples with all supported providers (Anthropic, OpenAI, Ollama, SAP AI Core, Vertex AI, Groq, Cerebras, MistralAI, OpenRouter).

Tool Configuration

Some tools require external API keys to function. Configure these in ~/.config/code-assistant/tools.json:

{
  "perplexity_api_key": "${PERPLEXITY_API_KEY}"
}

Available Tool Settings:

• perplexity_api_key - Enables the perplexity_ask tool for AI-powered web search

Tools without their required configuration will not be available to the assistant.

List Available Models:

# See all configured models
code-assistant --list-models

# See all configured providers
code-assistant --list-providers

Configure in Claude Desktop settings (Developer tab → Edit Config):

{
  "mcpServers": {
    "code-assistant": {
      "command": "/path/to/code-assistant/target/release/code-assistant",
      "args": ["server"],
      "env": {
        "SHELL": "/bin/zsh"                 // Your login shell
      }
    }
  }
}

Configure in Zed settings:

{
  "agent_servers": {
    "Code-Assistant": {
      "command": "/path/to/code-assistant/target/release/code-assistant",
      "args": ["acp", "--model", "Claude Sonnet 4.5"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Make 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.

For detailed setup instructions, see Zed's documentation on adding custom agents.

Tool Syntax Modes:

• --tool-syntax native: Use the provider's built-in tool calling (most reliable, but streaming of parameters depends on provider)
• --tool-syntax xml: XML-style tags for streaming of parameters
• --tool-syntax caret: Triple-caret blocks for token-efficiency and streaming of parameters