ctxai

Local-first coding agent with persistent, syntax-aware semantic repository memory

ctxai indexes repository structure and code into a durable local intelligence layer, then uses that evidence to answer questions and perform bounded, reviewable code changes through CLI, chat, dashboard, Python, or MCP.

Features:

• 🤖 AI Coding Agent: Interactive chat with multi-provider LLM support (OpenRouter, GitHub Copilot, Ollama, Anthropic, OpenAI)
• 🔍 Semantic Search: Natural language queries across your entire codebase
• 🧭 Grounded Planning: Evidence-backed plans and exact-action approval for complex or risky work
• 🔐 OAuth Authentication: Secure one-click login for OpenRouter and GitHub Copilot
• 🛠️ Safe Repository Tools: Project-rooted file, command, semantic-search, and read-only Git operations with audit records
• 📊 MCP Server: Integrate with Claude Desktop and other MCP-compatible tools
• 🎯 Local & Cloud: Use free local models (Ollama) or powerful cloud models

All nine product slices in plan.md—persistent indexing, safe tools, grounded retrieval, verified changes, sessions, MCP, provider conformance, planning, and dashboard operations—have executable acceptance coverage.

Quick Start

🚀 AI Coding Agent (Recommended)

# 1. Install ctxai with all features
pip install ctxai[all]
# Or using uv (faster): uv pip install ctxai[all]

# 2. Authenticate with a provider (easiest: OpenRouter)
ctxai login openrouter
# One-click OAuth in browser - no manual API key needed!

# 3. Start coding with AI
ctxai chat
# Interactive agent with access to 100+ models

# Or execute one-shot tasks
ctxai code "Create a Python function to validate email addresses"

🔍 Semantic Code Search

# 1. Install ctxai (basic)
pip install ctxai

# 2. Index your codebase (uses local embeddings - no API key needed!)
ctxai index /path/to/your/project "my-project"

# 3. Query your codebase using natural language
ctxai query my-project "Find authentication functions"

# 4. (Optional) Start the web dashboard
pip install ctxai[dashboard]
ctxai dashboard  # Open http://localhost:3000

⚠️ Windows Users

Set encoding to UTF-8 to avoid emoji display issues:

# PowerShell
$env:PYTHONIOENCODING="utf-8"

# CMD
set PYTHONIOENCODING=utf-8

# Or add to your system environment variables permanently

Features

🤖 AI Coding Agent

• Interactive Chat: REPL interface for conversational coding assistance
• Multi-Provider Support: OpenRouter (100+ models), GitHub Copilot, Ollama (local), Anthropic, OpenAI
• OAuth Authentication: Secure one-click login for OpenRouter and GitHub Copilot
• Verified Task Workflow: Retrieved evidence, scoped planning, exact-action approval, diffs, focused checks, and stable reports
• Hardened Tool Execution: Allowlisted subprocess environments (no secret inheritance), bounded tool output with explicit truncation markers, and uniqueness-checked edits that fail closed
• Rich Tool Support: File operations, bash execution, git tools, code search
• Repository Context: Automatic repository mapping for better code understanding
• Flexible Presets: default, premium, budget, cheap, local, mixed configurations

🔍 Semantic Code Search

• Smart Indexing: Tree-sitter based parsing for semantic code understanding
• Natural Language Queries: Find code by describing what you want, not just keywords
• Multiple Embedding Providers: Local (default, no API key), OpenAI, HuggingFace
• Fast & Accurate: Intelligent chunking preserves code context and meaning
• Local-First: Works offline with local embeddings (all-MiniLM-L6-v2)
• Configurable Limits: Control project size, file count, and indexing behavior

🛠️ Developer Experience

• CLI & MCP Server: Use from command line or integrate with Claude Desktop
• Web Dashboard: Interactive UI for browsing indexes and querying code
• GitHub Copilot Integration: Query via @ctxai in Copilot Chat
• Safety Features: Bash command filtering, file size limits, sandboxing
• Provider-independent: Executable capability contracts across advertised local and cloud providers

Provider Comparison

| Provider | Cost | Setup | Models | Best For | |----------|------|-------|--------|----------| | OpenRouter | Pay-as-you-go | OAuth (1-click) | 100+ (Claude, GPT-4o, o1, DeepSeek, etc.) | Recommended: Best flexibility + cost | | GitHub Copilot | $10-19/mo | OAuth (device code) | GPT-4, Claude, o1 | If you have subscription | | Ollama | Free | Install + pull models | CodeLlama, DeepSeek-Coder, Qwen, etc. | Privacy, offline, no cost | | Anthropic | Pay-as-you-go | API key | Claude models | Direct Claude access | | OpenAI | Pay-as-you-go | API key | GPT models | Direct GPT access |

Recommendation for most users: Start with OpenRouter (easiest OAuth setup, access to 100+ models, flexible pricing)

Usage

Prerequisites

No API key needed for default local embeddings!

For OpenAI embeddings (optional, better quality):

export OPENAI_API_KEY=your-api-key-here

Or configure in .ctxai/config.json:

{
  "embedding": {
    "provider": "openai",
    "api_key": "your-api-key-here"
  }
}

Indexing Your Codebase

Index your project to enable semantic search:

# Basic usage
ctxai index /path/to/codebase "index_name"

# With Python module
python -m ctxai index /path/to/codebase "index_name"

# Include only specific file patterns
ctxai index /path/to/codebase "my-index" --include "*.py" --include "*.js"

# Exclude additional patterns beyond .gitignore
ctxai index /path/to/codebase "my-index" --exclude "*.test.js" --exclude "migrations/*"

# Don't follow .gitignore
ctxai index /path/to/codebase "my-index" --no-follow-gitignore

The indexing process will:

1. Traverse your codebase recursively (respecting .gitignore by default)
2. Parse code using tree-sitter for semantic understanding
3. Chunk code intelligently (functions, classes, etc.)
4. Generate embeddings locally by default (or use the configured provider)
5. Persist vectors and a versioned manifest in .ctxai/indexes/<name>
6. Reuse unchanged files and replace only changed or deleted file chunks on later runs

Index writes are verified before the manifest is published, and each index also builds an inspectable symbol graph (graph.sqlite3: definitions, imports, inheritance, calls, references, and test associations with file:start-end evidence — see docs/SYMBOL_GRAPH.md). Inspect and manage indexes with:

ctxai indexes list
ctxai indexes info my-index
ctxai indexes doctor my-index
ctxai indexes delete my-index

# Symbol graph inspection
ctxai graph stats my-index
ctxai graph symbol calculate --kind function
ctxai graph neighbors <SYMBOL_ID> --direction in --edge tests

CLI Commands

View all available commands:

ctxai --help

Available Commands:

AI Agent:

• chat - Start interactive chat mode with AI coding agent
• code - Execute a one-shot coding task
• login - Authenticate with an LLM provider using OAuth
• logout - Remove stored credentials for a provider

Code Search:

• index - Index a codebase for semantic search
• query - Query an indexed codebase using natural language
• indexes - List, inspect, diagnose, and delete persistent indexes
• graph - Inspect the repository symbol graph: stats, symbol lookup, and bounded relationship traversal (see docs/SYMBOL_GRAPH.md)
• dashboard - Start the web dashboard for browsing and querying

Evaluation:

• eval retrieval - Run the versioned retrieval quality benchmark against a local index (Recall@K, MRR, nDCG@10, latency, context-efficiency) with baseline regression gates (see docs/RETRIEVAL_BENCHMARK.md)
• eval retrieval validate - Validate a benchmark document without running retrieval

Configuration:

• config - Manage ctxai configuration settings
• server - Start the MCP server for AI agents

Querying Your Codebase

Once you've indexed a codebase, you can query it using natural language:

# Basic query
ctxai query my-project "Find authentication functions"

# Limit number of results
ctxai query my-project "How to connect to database" --n-results 3

# Show only metadata (no code content)
ctxai query my-project "Find error handling code" --no-content

The query command will:

1. Generate an embedding for your query
2. Search the vector database for similar code
3. Display results with:
   • File paths and line numbers
   • Chunk types (function, class, etc.)
   • Similarity scores
   • Syntax-highlighted code previews

AI Coding Agent

Start an interactive coding session with AI:

# OpenRouter with Claude (recommended)
ctxai chat --provider openrouter --model anthropic/claude-3.5-sonnet

# GitHub Copilot (if you have subscription)
ctxai chat --provider github-copilot --model gpt-4

# Local Ollama (free!)
ctxai chat --provider ollama --model codellama:13b

Architect/editor mode is intentionally disabled pending benchmark evidence. Complex tasks use the validated single-agent structured planning and approval workflow.

Planning control (--plan): choose when the agent must submit an evidence-backed plan before mutations — auto (default; keyword classification), force (always plan, even for simple tasks), or off (never plan; tools stay approval-gated):

ctxai chat --plan force        # every chat task goes through submit_plan
ctxai code --plan off "Fix the typo in README.md"

Inside chat, /plan shows the current mode and /plan auto|force|off overrides it for the next tasks. Approval prompts offer [y] once / [a] always this session / [n] no; a session approval is bound to the exact tool + file (or command executable) and expires with the session. Approvals bind to the exact diff shown: if the file changes before execution, the agent re-prompts with a fresh diff instead of executing a stale approval (see docs/AGENT_LOOP.md, "Approvals, session memory, and plan modes").

One-Shot Tasks:

# Execute a coding task
ctxai code "Create a FastAPI endpoint for user authentication"

# With verbose output
ctxai code "Add error handling to main.py" --verbose

OAuth Authentication:

Secure one-click authentication (no manual API key needed):

# OpenRouter (100+ models)
ctxai login openrouter
# Opens browser for OAuth flow

# GitHub Copilot (device code flow)
ctxai login github-copilot
# Follow instructions to enter code at github.com/login/device

# Check provider status
ctxai chat  # Shows provider availability

Web Dashboard

Start the interactive web dashboard to manage your indexes:

# Start dashboard (default port 3000)
ctxai dashboard

# Use custom port
ctxai dashboard --port 8080

The dashboard provides:

• Index health, freshness, schema, embedding identity, and chunk statistics
• Natural-language query results with file and line evidence
• Index inspection and explicit deletion

Open your browser to http://localhost:3000 to access the dashboard.

The dashboard binds to 127.0.0.1 by default and has no authentication or TLS. Remote binding is rejected unless both a non-loopback --host and --allow-remote are supplied. Only use that override on a trusted network behind appropriate access controls; for example:

ctxai dashboard --host 0.0.0.0 --allow-remote

Note: Dashboard requires FastHTML. Install it with:

pip install ctxai[dashboard]
# Or install all optional dependencies
pip install ctxai[all]

MCP Server for AI Agents

Start the MCP server to expose ctxai functionality to AI agents like Claude:

# Star