squid 🦑🏴‍☠️

<div align="center"> <img src="docs/squid.JPG" alt="Squid Logo" width="300" /> </div>

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
• 🎤 Audio Input - Voice input for chat messages with automatic transcription using browser speech recognition or Docker Whisper
• 🧠 RAG (Retrieval-Augmented Generation) - Semantic search over your documents for context-aware responses
• ⏰ Background Jobs - Schedule recurring AI tasks with cron expressions and resource control
• 🔧 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:

| Approach | Examples | Data Sent Externally | |----------|----------|---------------------| | Maximum Privacy | LM Studio, Ollama, Docker AI | None | | Cloud Convenience | OpenAI, Mistral, OpenRouter | Yes, to provider |

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

| Variable | Default | Description | |----------|---------|-------------| | API_URL | — | OpenAI-compatible API endpoint (required) | | API_KEY | — | API key (not-needed for local services) | | SQUID_CONTEXT_WINDOW | 8192 | Max context tokens (see Context Window Sizes) | | SQUID_LOG_LEVEL | error | Console verbosity: error, warn, info, debug, trace | | SQUID_DB_LOG_LEVEL | debug | Database log level (viewable in Web UI Logs page) | | SQUID_DATABASE_PATH | squid.db | SQLite database path (auto-detected if relative) | | SQUID_WORKING_DIR | ./workspace | Root directory for file operations and plugin access | | server.allow_network | false | Bind to 0.0.0.0 for LAN access (default: 127.0.0.1 only) | | web.sounds | true | Enable notification sounds in Web UI | | audio.enabled | false | Enable audio transcription feature - opt-in (env: SQUID_AUDIO_ENABLED) | | audio.image | kesertki/whisper:latest | Docker image for Whisper transcription (env: SQUID_AUDIO_IMAGE) | | audio.model | tiny | Whisper model size: tiny, base, small, medium, large (env: SQUID_AUDIO_MODEL) | | audio.language | "" (auto-detect) | Language code for transcription, e.g., en, es, fr (env: SQUID_AUDIO_LANGUAGE) | | jobs.enabled | false | Enable background job scheduler | | jobs.max_concurrent_jobs | 2 | Maximum concurrent job executions | | jobs.max_cpu_percent | 70 | CPU threshold before jobs pause | | jobs.default_retries | 3 | Retry attempts for failed jobs |

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:

| Property | Required | Description | |----------|----------|-------------| | name | Yes | Display name in the UI | | enabled | No | Show in agent selector (default: true) | | description | No | Brief explanation of agent's purpose | | model | Yes | LLM model ID (use provider/model for cloud services) | | pricing_model | No | Cloud model ID for cost estimation (e.g., gpt-4o) | | context_window | No | Max context tokens (overrides global setting) | | use_tools | No | Enable tool usage (default: true, set false for persona-only agents) | | suggestions | No | Clickable prompt chips shown in Web UI | | permissions | Yes | Allow-only list of tools (everything else denied by default) |

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 extracted from the binary to ~/.local/share/squid/bundled/agents/

The default_agent field in squid.config.json specifies which agent is