# ACECode — Full Documentation Single-file corpus for LLM ingestion. Source: https://acecode.dev/docs/ Convention: https://llmstxt.org --- # Credits & Billing Source: https://acecode.dev/docs/billing/credits-v2/ > How ACECode credits work — what counts, what's free, and how your tier and model choice affect cost. import { Aside } from '@astrojs/starlight/components'; # Credits & Billing ACECode bills usage in **credits**. One credit equals $0.0001 of underlying LLM cost. You see credit totals in your dashboard — not raw token counts — because the dollar cost of a request depends on the model used, the context length, and the task, none of which we want you to track manually. ## What a credit pays for Every action that calls an LLM or runs a quality-tier task consumes credits: | Task | Typical credit cost (per call) | |---|---| | `search` (basic) | 0 — free, served from cache or pure DB | | `search` (LLM rerank, max/business) | 5-20 | | `enrich` (auto mode) | 30-150 | | `review` (AI code review on a diff) | 50-300 | | `recall` / `remember` | 0-5 | | `validate` (hallucination check) | 5-15 | | `recap` (session compression) | 20-80 | Embedding (Voyage) and reranking are **not** billed to your credit ledger — they're tracked separately in a hidden monthly quota and included in every tier. You won't see them on your statement. ## Tiers | Tier | Price | Credits / month | What you get | |---|---|---|---| | **Free** | $0 | 5,000 | CLI + MCP, 1 project, community routing (gpt-5.5) | | **Pro** | $19/mo | 50,000 | + ADE access, 10 projects, model preference (Grok / GPT / Gemini), Discord priority | | **Max** | $49/mo | 250,000 | + Higher quality (Grok 4.3 on quality tasks by default), 50 projects, multi-key embedding pool | | **Business** | $199/mo | 1,500,000 | + Self-host, SSO, audit log, dedicated support, SLA, unlimited projects | Credits don't roll over month-to-month. If you need more than your tier includes, you can buy a credit pack at $1 per 1,000 credits (one-time, never expires). ## Model choice affects cost Pro+ users can override the default model for quality tasks (rerank, review, memory refine). Cheaper models cost fewer credits per call: - `cx/gpt-5.5` (default Free/Pro) — baseline cost - `grok-4.3` (default Max/Business) — ~2-3× baseline, higher quality on long contexts - `deepseek-v4-flash` (fallback) — ~0.5× baseline, 3-4× faster than gpt-5.5 - `gemini-2.5-flash-lite` (fallback) — ~0.3× baseline, lowest quality Your dashboard shows the per-task model used so you can tune the trade-off. ## Cost-optimized mode If you'd rather burn fewer credits than chase the highest answer quality, toggle **Cost-Optimized LLM Mode** in account settings. This downgrades quality tasks from Grok to gpt-5.5 on Max / Business — typically cutting credit consumption by ~40-60% on heavy MCP-tool sessions. ## Reservation flow (technical detail) ACE uses **two-phase credit reservation**: 1. **Reserve** — at request start, the maximum possible cost is held against your balance. If your balance is too low, the request fails with `402 Insufficient credits` before the LLM is called. 2. **Commit / void** — when the LLM finishes, the actual cost is committed and the difference is voided back to your balance. If the LLM call fails (timeout, provider error), the full reservation is voided. You see both states in the credit ledger: `status=reserved` (held) and `status=committed` (settled). Reserved entries that don't commit within 60 seconds are auto-voided. ## Where to check your usage - **Dashboard** at `app.acecode.dev/billing` — current balance, this-month spend, top tasks by cost. - **API** — `GET https://api.acecode.dev/v1/billing/balance` returns your current balance. - **Webhook** — Business tier can subscribe to `credit.low` events to be paged when balance drops below a threshold. ## Free-tier limits Beyond credits, the Free tier has hard limits that prevent runaway storage: - 1 project - 50,000 indexed chunks total - 100 indexed files per project - ADE locked (Pro+) Pro / Max raise these proportionally. Business is unlimited (limited by your self-hosted infrastructure). ## Refunds Subscriptions are non-refundable for the current billing cycle but can be cancelled at any time — you keep access until the cycle ends. Credit packs purchased one-time are refundable within 30 days if untouched (≥ 95% of the pack still in balance). --- # ace index Source: https://acecode.dev/docs/cli/ > Index your codebase for semantic search. # `ace index` Parses and indexes your codebase into ACECode's semantic search engine. ## Usage ```bash ace index [options] ``` ## Options | Flag | Description | Default | |------|-------------|---------| | `-p, --project` | Project slug to index | Auto-detected from `.ace/config` | | `--force` | Force full re-index (ignore change detection) | `false` | | `--since ` | Only index files changed since this commit | — | | `--api-key ` | Override API key | `ACE_API_KEY` env var | | `--api-url ` | Override API URL | `https://api.acecode.dev` | ## Examples ```bash # Index current project (auto-detect from .ace/config) ace index # Index a specific project ace index -p my-backend # Force full re-index ace index --force # Only index files changed since last commit ace index --since HEAD~1 ``` ## How it works The `ace index` command: 1. Scans your project for source files 2. Parses each file using the TypeScript Compiler API (TS/JS) or tree-sitter (other languages) 3. Splits code into semantic chunks (functions, classes, blocks) 4. Sends chunks to the API for embedding and storage 5. Detects unchanged files via content hash — only re-indexes modified files ## Incremental indexing ACECode uses content hashes to avoid re-indexing unchanged files. On subsequent runs: ``` 📁 Scanning 847 files... ⚡ 823 files unchanged (skipped) ⚡ Indexing 24 changed files... ✅ Done in 3.2s ``` --- # Self-Host (Business tier) Source: https://acecode.dev/docs/deploy/self-host/ > Run ACECode on your own infrastructure. PostgreSQL + pgvector + Redis + Hono. Single VPS deployment. import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; # Self-Host Business-tier subscribers can run ACECode on their own infrastructure. Your code, your embeddings, and your LLM keys stay inside your perimeter — ACE talks to your chosen LLM providers directly, never to our cloud. ## What you provision A single Linux VPS or container can run the entire stack. Minimum specs: | Component | Spec | Notes | |---|---|---| | CPU | 4 vCPU | Indexing parallelism scales linearly | | RAM | 8 GB | Postgres + Redis + Node.js | | Disk | 50 GB SSD | Chunks + embeddings + KB; scales with indexed lines | | OS | Ubuntu 22.04 / 24.04, Debian 12, or Docker-capable host | | Production recommended: 6 vCPU / 12 GB RAM / 100 GB SSD. This matches our hosted instance and handles ~5M indexed chunks comfortably. ## Stack overview ``` ┌─────────────────────────────────────────┐ │ Caddy (reverse proxy) │ │ TLS termination, HTTP/2, automatic LE │ └────────────────────┬────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ @ace/api (Hono on Node 22+) │ │ MCP server + REST API + indexer │ └─────┬─────────────────────────┬─────────┘ ↓ ↓ ┌─────────────┐ ┌──────────────┐ │ PostgreSQL │ │ Redis 7 │ │ + pgvector │ │ │ │ (all data) │ │ (cache) │ └─────────────┘ └──────────────┘ ↑ ┌─────────────────────────────────────────┐ │ External LLM + Embedding providers │ │ Voyage (embed) + your choice of LLM │ └─────────────────────────────────────────┘ ``` ## Quick start (Docker Compose) 1. **Get the Docker Compose bundle** Business tier customers receive a private Compose bundle. The bundle ships: - `docker-compose.yml` — services: `api`, `postgres`, `redis`, `caddy` - `Caddyfile` — TLS-terminated reverse proxy - `.env.example` — required env vars - `init.sql` — pgvector extension + initial migrations 2. **Provide LLM keys** ACE doesn't ship LLM credentials. Add your own to `.env`: ```bash # Required: embedding provider VOYAGE_API_KEY=pa-... # At least one LLM provider (more = better fallback) XAI_API_KEY=xai-... GOOGLE_API_KEY=... OPENAI_API_KEY=sk-... # or any OpenAI-compatible endpoint NINEROUTER_BASE_URL=http://... # if using 9router gateway ``` 3. **Set your domain + license key** ```bash ACE_DOMAIN=ace.your-company.com ACE_LICENSE_KEY= ``` 4. **Start the stack** ```bash docker compose up -d docker compose exec api pnpm db:push # apply schema docker compose exec api pnpm seed:admin # create first admin user ``` 5. **Verify** ```bash curl https://ace.your-company.com/v1/health # → { "status": "ok", "version": "x.y.z" } ``` 6. **Connect the CLI** ```bash export ACE_API_URL=https://ace.your-company.com export ACE_API_KEY= ace init ace index ``` ## Self-host vs hosted differences | Feature | Hosted (api.acecode.dev) | Self-host (Business) | |---|---|---| | Latency from your region | Depends — US-east origin | Wherever you put it | | Code privacy | Hosted on our infra | Stays inside your perimeter | | LLM provider keys | We provide + pool | You provide + manage | | Indexed-chunk limit | Tier-capped | Bounded by your disk | | Upgrades | Automatic | `git pull && docker compose up -d` | | Backup | Automatic snapshots, off by default | Your responsibility | | SSO | Not yet | SAML 2.0 / OIDC (Business only) | | Audit log | Not surfaced | Postgres `admin_activity_log` table | | Support SLA | Best-effort | 24h response (Business) | ## Migrating from hosted to self-host If you started on hosted and want to move on-premises: 1. **Export** — `ace export --project=` produces a tarball with files + chunks + embeddings + memories. Embeddings are portable (same Voyage model on both sides). 2. **Restore** — on your self-hosted instance: `ace import ` re-creates the project with all data. 3. **Switch endpoint** — point your CLI / VS Code extension at the new host: `ACE_API_URL=https://ace.your-company.com`. Embeddings re-importing avoids re-billing Voyage tokens. Expect ~5 minutes per 100K chunks for the import step. ## Hardening checklist - [ ] Postgres on a private network, not bound to public IP - [ ] Redis bound to `127.0.0.1` only (it does not need network access) - [ ] Caddy auto-HTTPS, force HTTPS redirect - [ ] LLM provider keys in a secrets manager, not in `.env` on disk - [ ] Daily `pg_dump` to off-host storage - [ ] OS auto-updates enabled (`unattended-upgrades` on Debian/Ubuntu) - [ ] Firewall: only ports 80 + 443 open inbound ## Support Business-tier self-host comes with: - Private support channel (Slack Connect or Discord) - 24h response SLA on infra issues - Direct line to the founding team for architectural questions - Pre-release access to new MCP tools Email `support@acecode.dev` for self-host onboarding. --- # MCP Protocol Source: https://acecode.dev/docs/integrations/mcp/ > Use ACECode with Claude and any MCP-compatible AI assistant. import { Aside, Code } from '@astrojs/starlight/components'; # MCP Integration ACECode exposes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server, enabling any MCP-compatible AI assistant to query your indexed codebase directly. ## Setup Add ACECode to your MCP config: ```json title=".mcp.json" { "mcpServers": { "acecode": { "type": "http", "url": "https://api.acecode.dev/mcp", "headers": { "Authorization": "Bearer ace_xxxx..." } } } } ``` ## Available tools | Tool | Description | |------|-------------| | `search` | Semantic + keyword hybrid search | | `graph` | Dependency relationships, impact analysis, call chains | | `history` | Git commit search, evolution digests | | `meta` | Architecture overview, code health, memories | | `files` | List indexed files with filtering | | `docs` | Search library documentation KB | ## Usage with Claude Once configured, Claude can use ACECode tools in conversation: > "Find the authentication middleware in this codebase" Claude will call `mcp__acecode__search` with your query and return grounded results from your actual code. --- # Introduction Source: https://acecode.dev/docs/introduction/ > What is ACECode and why was it built? import { Aside, Card, CardGrid, Steps } from '@astrojs/starlight/components'; # What is ACECode? **ACECode** (Az Context Engine) is a self-hosted semantic code indexing and search platform. It gives AI assistants and developers instant access to your entire codebase through natural language queries. ## Why ACECode? Large codebases become hard to navigate. Developers spend hours looking for the right file, understanding how a function is called, or figuring out what changed and why. ACECode solves this by: - **Indexing everything** — files, chunks, symbols, relationships, git history - **Making it queryable** — natural language search powered by vector embeddings + BM25 - **Feeding AI context** — works as an MCP server so Claude, Cursor, and other AI tools get precise context ## How it works 1. **Index your codebase** — The CLI parses your code (TypeScript, Python, Go, Rust, and 15+ languages) and sends semantic chunks to the API. 2. **Vector embeddings** — Each chunk is embedded using Voyage AI's `voyage-4` model and stored in PostgreSQL with `pgvector`. 3. **Hybrid search** — Queries combine vector similarity (semantic) with BM25 full-text search, then rerank with AI for precision. 4. **Serve context** — Results are served via REST API or MCP protocol to any compatible client. ## Key features Query your codebase in plain English. "Find the authentication middleware" returns the right file instantly. Automatically detects patterns, conventions, and architectural decisions from your code. Understand dependencies, blast radius of changes, and call chains across your entire codebase. Native MCP server — plug into Claude, Cursor, or any AI assistant for grounded, accurate responses. ## Architecture ACECode runs as a self-hosted API on your infrastructure: ``` CLI (local) → REST API → PostgreSQL + pgvector ↑ ↓ MCP Server Voyage AI (embeddings) ↑ AI Assistant ``` Your code **never leaves your infrastructure** unless you explicitly connect to external AI services. --- # MCP Tools Overview Source: https://acecode.dev/docs/mcp-tools/overview/ > The 20+ MCP tools ACECode exposes — semantic search, code graph, git history, memories, and more. import { Aside, Card, CardGrid } from '@astrojs/starlight/components'; # MCP Tools Overview Once you've [connected ACECode as an MCP server](/docs/integrations/mcp/), your AI assistant gains access to the tools listed below. Each tool is purpose-built for a specific code-intelligence task — together they cover **search, code graph, git history, project metadata, and more**. ## Code discovery (4 grouped tools) These four tools cover ~80% of what you'll ask ACE to do. Each has multiple modes — pick the mode that matches your intent. **Modes:** `search`, `symbols`
Semantic + keyword hybrid search. Finds code by **meaning**, auto-bundles pattern matches and symbol maps for top results. Use this for "where is X" and "how does Y work". **Modes:** `relationships`, `impact`, `flow`
Dependency graph. "What depends on `AuthService`?" / "What breaks if I change this?" / "Trace the call chain from `POST /login`." **Modes:** `lineage`, `evolution`, `diff`
Git intelligence. Commit search, weekly digests, blast radius of a diff. Use this for "when did this change and why?" **Modes:** `architecture`, `health`, `memories`, `assemble`, `api`
Project metadata. Module map, code-quality findings, learned conventions, context bundles, API endpoints. ## Specialised tools | Tool | Purpose | |---|---| | `files` | List indexed files, filter by path or language | | `projects` | Register / list / get status / remove projects | | `index` | Queue a re-indexing job | | `review` | AI code review on a diff | | `validate` | Hallucination check — verify a symbol or import exists in the index | | `logic` | Business rules, state machines, call flows | | `docs` | Search the library-docs knowledge base (npm, PyPI, crates.io, Go) | | `enrich` | Prompt enrichment pipeline (used by the `/ace enrich` skill) | | `list-skills` | Discover available enrich modes | | `recall` | Semantic memory recall — search across past sessions | | `remember` | Save a memory the assistant should recall in future sessions | | `recap` | Compress a long session into anchor memories | | `my_skills` | Runtime access to your custom + generated skills | | `my_agents` | Runtime access to your custom agents | | `my_prompts` | Back-compat alias for skills with `tier=custom activation=manual` | ## Tool-selection cheat sheet ```text # Find code by meaning search { query: "how does auth work", project: "my-project" } # Symbol definitions search { query: "Repository", project: "my-project", mode: "symbols", symbolType: "class" } # Map dependencies before refactoring graph { query: "AuthService", project: "my-project", mode: "relationships" } # Blast radius — what breaks if I change this? graph { query: "AuthService", project: "my-project", mode: "impact", depth: 3 } # Trace a call chain from an entry point graph { query: "POST /login", project: "my-project", mode: "flow" } # Why does this file look the way it does? history { query: "src/auth.ts", project: "my-project", mode: "lineage" } # Recent activity digest history { query: "last week", project: "my-project", mode: "evolution" } # Architecture overview meta { project: "my-project", mode: "architecture" } # Project conventions and gotchas meta { query: "auth patterns", project: "my-project", mode: "memories" } ``` ## Multilingual queries ACECode's embeddings (Voyage `voyage-4-large`) and reranker (xAI `grok-4.3`) are both multilingual. You can query in **Vietnamese, Chinese, Japanese, or mixed languages** without pre-translating. The pipeline matches the query embedding directly against the (English) code index. ```text # These work natively: search { query: "tìm hàm xử lý đăng nhập" } search { query: "认证中间件在哪里" } ``` Pre-translate only if results look off for an unusually idiomatic phrase. ## Per-tool reference Coming in Phase 2: a dedicated page per tool with full parameter schema, return shape, latency budget, and credit cost. For now, the [API reference endpoint](https://api.acecode.dev/v1/mcp/tools) returns the live JSON Schema for every tool. --- # Quick Start Source: https://acecode.dev/docs/quick-start/ > Get ACECode running in 5 minutes. import { Steps, Aside, Code, Tabs, TabItem } from '@astrojs/starlight/components'; # Quick Start Get from zero to semantic search in 5 minutes. ## Prerequisites - Node.js 18+ - An ACECode account ([sign up free](https://app.acecode.dev/sign-up)) - A codebase to index ## Installation 1. **Install the CLI** ```bash npm install -g @ace/cli ``` 2. **Authenticate** Create an API key in your [account settings](https://app.acecode.dev/api-keys), then: ```bash export ACE_API_KEY=ace_xxxx... ``` Or add it to your shell profile for persistence. 3. **Initialize your project** Navigate to your project root and run: ```bash cd /path/to/your/project ace init ``` This detects your language/framework, registers the project, and creates a `.ace/` config directory. 4. **Index your codebase** ```bash ace index ``` For large codebases, indexing runs in batches. You'll see progress: ``` ✅ Registered project: my-project (id: y3p768RuGnaE) 📁 Scanning files... ⚡ Indexing 847 files... ✅ Done! 12,840 chunks · 3,210 symbols indexed in 42s ``` 5. **Search!** ```bash ace search "how does authentication work?" ``` ## Next steps - [Connect to VS Code](/docs/integrations/vscode) — get inline AI suggestions powered by your index - [Set up MCP](/docs/integrations/mcp) — use with Claude or any MCP-compatible AI - [CLI Reference](/docs/cli/index) — full command documentation ---