squid 🦑🏴‍☠️

An AI-powered assistant for code reviews and improvement suggestions. Privacy-focused and local-first - your code never leaves your hardware when using local models.

[!WARNING] This is an ongoing research project under active development. Features and APIs may change without notice, and breaking changes may occur between versions. Use in production at your own risk.

Features

• 🌐 Web UI - Modern chat interface with persistent sessions and conversation management
• 🧠 RAG (Retrieval-Augmented Generation) - Semantic search over your documents for context-aware responses
• 🔧 Tool Calling - File operations, code search, and bash commands with built-in security
• 🔌 Plugin System - Extend capabilities with JavaScript plugins (NEW!)
• 🔍 AI Code Reviews - Language-specific analysis and suggestions
• 🌍 Environment Awareness - LLM receives system context for smarter responses
• 🔒 Security First - Path validation, .squidignore support, and user approval for all operations
• 🔌 Universal Compatibility - Works with LM Studio, OpenAI, Ollama, Mistral, and other OpenAI-compatible APIs

Privacy & Local-First

Your code never leaves your hardware when using local LLM services (LM Studio, Ollama, etc.).

• 🔒 Complete Privacy — Run models entirely on your own machine with local-first inference
• 🛡️ You Control Your Data — Choose between local models (private) or cloud APIs (convenient)
• 🔐 Secure by Default — All file operations require explicit approval regardless of LLM service

Privacy Options:

Prerequisites

Docker (recommended): Only Docker Desktop 4.34+ or Docker Engine with Docker Compose v2.38+. All AI models are automatically managed.

Manual installation:

1. Rust toolchain: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
2. An OpenAI-compatible LLM service — see LLM Provider Reference at the bottom of this page

Installation

Docker with AI Models (Recommended)

The easiest way to get started — automated setup with helpful checks:

git clone https://github.com/DenysVuika/squid.git
cd squid
cp .env.docker.example .env
./docker-setup.sh setup   # or: docker compose up -d

The setup script verifies Docker, checks disk space, builds the server image, pulls AI models, and starts services with health checks.

Services included:

• Squid server (web UI + API) on http://localhost:3000
• Qwen2.5-Coder 7B (~4GB) — Main LLM with Metal GPU acceleration on Apple Silicon
• Nomic Embed Text v1.5 (~270MB) — Embeddings for RAG

Useful commands:

./docker-setup.sh status    # Check service status
./docker-setup.sh logs      # View logs
./docker-setup.sh stop      # Stop services
./docker-setup.sh restart   # Restart services
./docker-setup.sh update    # Update models and images

Using External LLM Services (Optional)

Replace Docker AI models by editing the environment section in docker-compose.yml:

services:
  squid:
    environment:
      # For LM Studio (running on host)
      - API_URL=http://host.docker.internal:1234/v1
      # For Ollama
      # - API_URL=http://host.docker.internal:11434/v1
      # For OpenAI
      # - API_URL=https://api.openai.com/v1
      # - API_KEY=your-api-key-here

Use host.docker.internal to access services on your Mac/PC from inside Docker. Environment variables in docker-compose.yml always override squid.config.json.

Workspace Directory

The WORKSPACE_DIR env var controls what host directory is mounted into the container at /workspace. By default, it mounts the current directory.

# Work with a specific project
WORKSPACE_DIR=~/Projects/my-app docker compose up -d

All file operations, code search, and plugin access are restricted to the workspace directory and respect .squidignore patterns. See Security Features for details.

From crates.io

cargo install squid-rs

From Source

git clone https://github.com/DenysVuika/squid.git && cd squid && cargo install --path .

For Development

cargo build --release
# Use `cargo run --` instead of `squid` in examples below

Web UI: Automatically built during Rust compilation via build.rs. Manual build: cd web && npm install && npm run build.

Configuration

Manual Installation

For manual installations, configure Squid to connect to your LLM service:

Quick Setup:

# Interactive configuration (recommended)
squid init

# Or use command-line flags to skip prompts
squid init --url http://127.0.0.1:1234/v1 --log-level info

This creates a squid.config.json file with:

• API endpoint configuration: Connection to your LLM service
• Default agents: Pre-configured general-assistant (full access) and code-reviewer (read-only)
• Context window settings: Applied to each agent (can be customized per-agent later)
• Optional RAG setup: Document search and retrieval features

Note: CLI commands (squid ask, squid review) work with either:

• A squid.config.json file (recommended for agent configurations)
• Environment variables in a .env file (minimum: API_URL)
• A combination of both (environment variables override config file)

If neither is configured, commands will suggest running squid init or setting up environment variables.

See CLI Reference - Init Command for full configuration documentation.

Configuration Options

Template Variables: Agent prompts support Tera template syntax ({{persona}}, {{os}}, {{arch}}, {{now}}, etc.). See docs/TEMPLATE-VARIABLES.md for the full list and examples.

Agents

Squid uses an agent-based architecture where each agent has its own model, system prompt, and tool permissions. Agents are defined as individual .md files with YAML frontmatter in an agents/ folder.

Agent File Example (agents/code-reviewer.md):

---
name: Code Reviewer
enabled: true
description: Reviews code for best practices and potential issues
model: anthropic/claude-sonnet-4-5
context_window: 200000
pricing_model: gpt-4o
permissions:
  - now
  - read_file
  - grep
suggestions:
  - Review this file for security vulnerabilities
  - What are the biggest code quality issues here?
---
You are a code reviewer. Focus on security, performance, and maintainability.

Agent Properties:

Permissions:

• Supports granular bash permissions (e.g., "bash:ls", "bash:git status")
• Wildcard "plugin:*" grants access to all plugins
• ⚠️ Dangerous bash commands (rm, sudo, chmod, dd, curl, wget, kill) are always blocked regardless of permissions

Agents Directory Resolution:

1. SQUID_AGENTS_DIR env var (explicit override)
2. agents/ folder relative to squid.config.json
3. agents/ in the current working directory
4. Bundled agents shipped with the executable

The default_agent field in squid.config.json specifies which agent is selected by default when starting a new session.

Example Agent Workflows:

Common Context Window Sizes

{
  "agents": {
    "general-assistant": {
      "model": "local-model",
      "context_window": 32768,  // Qwen2.5-Coder: 32K
      ...
    },
    "code-reviewer": {
      "model": "gpt-4",
      "context_window": 128000,  // GPT-4: 128K
      ...
    }
  }
}

Usage

Squid provides both a modern Web UI and a command-line interface. We recommend the Web UI for the best experience.

Squid Web UI (Recommended)

Modern chat interface with session management, token usage tracking, and real-time cost estimates

Starting the Web UI

Docker:

docker compose up -d   # http://localhost:3000
WORKSPACE_DIR=/path/to/project docker compose up -d  # custom workspace

Manual:

squid serve                          # http://127.0.0.1:8080
squid serve --port 3000 --db=custom.db --dir=/path/to/project

Server Options:

Web UI Features:

• 📊 Token usage indicator — Real-time context utilization (e.g., "5.6% • 7.1K / 128K")
• 💰 Cost tracking — Estimates for both cloud and local models
• 📈 Lifetime agent statistics — Accumulated token usage and cost savings
• 🗂️ Session sidebar — Browse, rename, and switch between past conversations
• ✏️ Auto-generated titles — Sessions titled from first message, editable inline
• 📎 Multi-file attachments — Add context from multiple files
• 🔍 Logs page — Filterable application logs with pagination and session tracking

Web UI Development (Hot Reload):

# Terminal 1 - Backend
cargo run serve --port 8080
# Terminal 2 - Frontend
cd web && npm run dev

Open http://localhost:5173. Changes appear instantly. Production build: cd web && npm run build.

Command-Line Interface

For advanced users and automation, Squid provides a full CLI. See the CLI Reference for detailed documentation on:

• squid ask - Ask questions with optional file context
• squid review - Review code with language-specific analysis
• squid rag - Manage RAG document indexing
• squid logs - View, clear, and clean up application logs
• squid init - Initialize project configuration
• squid doctor - Run diagnostic checks to verify setup

Configuration Requirement: Most CLI commands (ask, review, serve) require either a squid.config.json file OR essential environment variables (at minimum API_URL). You can:

• Run squid init to create a config file with agent configurations
• Use a .env file with environment variables like API_URL, API_KEY, etc.
• Mix both approaches (environment variables override config file settings)

Quick Examples:

# Ask a question (uses default agent)
squid ask "What is Rust?"

# Ask with specific agent
squid ask "What is Rust?" --agent code-reviewer

# Review a file (uses default agent)
squid review src/main.rs

# Review with specific agent
squid review src/main.rs --agent general-assistant

# Initialize RAG for a project
squid rag init

# View application logs
squid logs show --level error

# Clear all logs from database
squid logs reset

# Remove logs older than 30 days (default)
squid logs cleanup

# Remove logs older than 7 days
squid logs cleanup --max-age-days 7

# Verify configuration and setup
squid doctor

For complete CLI documentation, see docs/CLI.md.

RAG (Retrieval-Augmented Generation)

Squid includes RAG capabilities for semantic search over your documents, enabling context-aware AI responses using your own documentation.

Quick Start:

# Docker (already configured)
docker compose up -d

# Or manually setup
mkdir documents
cp docs/*.md documents/
squid rag init
squid serve
# Click the RAG toggle (🔍) in the Web UI

Features:

• 📚 Semantic search over your documentation
• 🔍 One-click toggle in Web UI
• 💾 Persistent knowledge base - index once, query many times
• 📎 Source attribution - see which documents were used
• 🔄 Auto-indexing - supports Markdown, code, configs, and more

Using RAG:

1. Add documents to ./documents directory
2. Run squid rag init to index them
3. Toggle RAG in the Web UI to enable semantic search
4. Ask questions about your documentation

For complete RAG documentation, see docs/RAG.md.

Database & Persistence:

• All chat sessions, messages, and logs are automatically saved to squid.db (SQLite database)
• Sessions persist across server restarts - your conversation history is always preserved
• The database location is automatically detected based on config file location, existing databases in parent directories, or the current working directory. Override with SQUID_DATABASE_PATH.

REST API

The web server exposes REST API endpoints for programmatic access. See docs/API.md for full documentation.

Tool Calling & Security

Squid's LLM can intelligently use tools (read files, write files, search code, execute safe commands) when needed. All tool operations are protected by multiple security layers and require user approval.

Security Features:

• 🛡️ Path Validation - Blocks system directories automatically
• 📂 Ignore Patterns - .squidignore file (like .gitignore)
• 🔒 User Approval - Manual confirmation for each operation
• 💻 Safe Bash - Dangerous commands always blocked

Available Tools:

• 📖 read_file - Read file contents
• 📝 write_file - Write to files with preview
• 🔍 grep - Search code with regex
• 🕐 now - Get current date/time
• 💻 bash - Execute safe commands (ls, git, cat, etc.)

For complete security and tool usage documentation, see docs/SECURITY.md.

Plugin System

Squid supports a powerful JavaScript-based plugin system that lets you extend its capabilities with custom tools. Plugins are invoked by the LLM alongside built-in tools.

Quick Start

1. Create a plugin:

mkdir -p plugins/my-plugin
cd plugins/my-plugin

2. Add plugin.json:

{
  "id": "my-plugin",
  "title": "My Plugin",
  "description": "Does something useful",
  "version": "0.1.0",
  "api_version": "1.0",
  "security": {
    "requires": ["read_file"],
    "network": false,
    "file_write": false
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "message": { "type": "string" }
    },
    "required": ["message"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "result": { "type": "string" }
    },
    "required": ["result"]
  }
}

3. Add index.js:

function execute(context, input) {
    context.log(`Processing: ${input.message}`);
    return { result: input.message.toUpperCase() };
}
globalThis.execute = execute;

4. Enable in config:

{
  "agents": {
    "general-assistant": {
      "permissions": {
        "allow": ["read_file", "plugin:*"]
      }
    }
  }
}

Features

• 🔌 Sandboxed Execution - QuickJS runtime with memory and CPU limits
• 🔒 Hybrid Security - Plugins declare needs, agents control access
• ✅ Schema Validation - JSON Schema for input/output
• 📁 Dual Location - Workspace (./plugins/) and global (~/.squid/plugins/)
• 🛠️ Context API - Safe file operations, logging, and HTTP (when permitted)

Example Plugins

Three example plugins are included:

• markdown-linter - Analyzes markdown files for style issues
• code-formatter - Formats code with basic rules
• http-fetcher - Fetches content from URLs

Testing Plugins

Test code-formatter (fully functional):

squid chat
> Format this JSON: {"name":"test","age":30}

Test markdown-linter (fully functional, reads files):

squid chat
> Lint the README.md file

Test http-fetcher (requires network permission):

squid chat
> Fetch content from https://api.github.com

Note: The http-fetcher plugin requires network: true permission in its plugin.json. All context APIs (readFile, writeFile, httpGet) are now fully implemented and functional.

See docs/PLUGINS.md for complete plugin documentation.

Documentation

• Quick Start Guide - Get started in 5 minutes
• CLI Reference - Complete command-line interface documentation
• Plugin Development Guide - Create custom JavaScript tools (NEW!)
• RAG Guide - Retrieval-Augmented Generation (semantic document search)
• Security Features - Tool approval and security safeguards
• System Prompts Reference - Guide to all system prompts and customization
• Examples - Comprehensive usage examples and workflows
• Changelog - Version history and release notes
• Sample File - Test file for trying out the file context feature
• Example Files - Test files for code review prompts
• AI Agents Guide - Instructions for AI coding assistants working on this project

Testing

./tests/test-reviews.sh       # Automated code review tests
./tests/test-security.sh      # Interactive security approval tests
squid review sample-files/example.rs  # Test individual review

See tests/README.md and sample-files/README.md for details.

LLM Provider Reference

Set API_URL and API_KEY in your .env file or via squid init. All providers use the OpenAI-compatible API format.

License

Apache-2.0 License. See LICENSE file for details.