# Installation Guide
## Quick Install (one-liner)
```bash
Downloads pre-built `acb` + `agentic-codebase-mcp` binaries, installs to `~/.local/bin/`, and merges MCP server config into Claude Desktop and Claude Code. Requires `curl` and `jq`.
### Install by environment
```bash
# Desktop MCP clients (auto-merge Claude configs)
# Terminal-only (no desktop config writes)
# Remote/server host (no desktop config writes)
### Server auth and artifact sync
Cloud/server runtime cannot read files from your laptop directly.
```bash
export AGENTIC_TOKEN="$(openssl rand -hex 32)"
```
All MCP clients must send `Authorization: Bearer <same-token>`.
If `.acb/.amem/.avis` artifacts were created elsewhere, sync them to the server first.
---
Three ways to install AgenticCodebase, depending on your use case.
---
## 1. CLI Tool (recommended for most users)
The `acb` binary compiles codebases into `.acb` graph files and queries them. Requires **Rust 1.70+**.
```bash
cargo install agentic-codebase
```
### Verify
```bash
acb --help
acb --version
```
### Compile a repository
```bash
acb compile ./my-project -o project.acb
acb info project.acb
acb query project.acb symbol --name "UserService"
```
### Available commands
| `acb compile` | Compile a source directory into an `.acb` graph file |
| `acb info` | Display summary information about an `.acb` file |
| `acb query` | Run queries against a compiled graph (9 query types) |
| `acb get` | Get detailed information about a specific code unit |
### Query types
| `symbol` | `sym`, `s` | Find code units by name |
| `deps` | `dep`, `d` | Forward dependencies of a unit |
| `rdeps` | `rdep`, `r` | Reverse dependencies (who depends on this unit) |
| `impact` | `imp`, `i` | Impact analysis with risk scoring |
| `calls` | `call`, `c` | Call graph exploration |
| `similar` | `sim` | Find structurally similar code units |
| `prophecy` | `predict`, `p` | Predict which units are likely to break |
| `stability` | `stab` | Stability score for a specific unit |
| `coupling` | `couple` | Detect tightly coupled unit pairs |
All commands support `--format json` output for programmatic consumption.
---
## 2. MCP Server (for Claude Desktop, VS Code, Cursor, Windsurf)
The MCP server exposes compiled graphs as tools, resources, and prompts to any MCP-compatible LLM client.
```bash
cargo install agentic-codebase
```
This installs both the `acb` CLI and the `agentic-codebase-mcp` MCP server binary.
### Configure Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"agentic-codebase": {
"command": "agentic-codebase-mcp",
"args": []
}
}
}
```
### Configure VS Code / Cursor
Add to `.vscode/settings.json`:
```json
{
"mcp.servers": {
"agentic-codebase": {
"command": "agentic-codebase-mcp",
"args": []
}
}
}
```
### Configure Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"agentic-codebase": {
"command": "agentic-codebase-mcp",
"args": []
}
}
}
```
### Verify
Once connected, the LLM gains access to tools like `acb_compile`, `acb_query`, `acb_info`, and `acb_get`. Test by asking the LLM:
> "Compile the current project and tell me about its architecture."
The LLM should call `acb_compile` to build the graph and `acb_query` to explore it.
---
## 3. Core Library (for Rust projects)
Use AgenticCodebase as a library in your own Rust project. Requires **Rust 1.70+**.
Add to your `Cargo.toml`:
```toml
[dependencies]
agentic-codebase = "0.1"
```
### Example
```rust
use agentic_codebase::parse::parser::{Parser, ParseOptions};
use agentic_codebase::semantic::analyzer::{SemanticAnalyzer, AnalyzeOptions};
use agentic_codebase::format::{AcbWriter, AcbReader};
use agentic_codebase::engine::query::QueryEngine;
// Parse source files
let parser = Parser::new();
let result = parser.parse_directory("./my-project", &ParseOptions::default())?;
// Build the semantic graph
let analyzer = SemanticAnalyzer::new();
let graph = analyzer.analyze(result.units, &AnalyzeOptions::default())?;
// Write to disk
let writer = AcbWriter::with_default_dimension();
writer.write_to_file(&graph, "project.acb")?;
// Read back and query
let graph = AcbReader::read_from_file("project.acb")?;
let engine = QueryEngine::new();
// ... run queries
```
---
## 4. Combined with AgenticMemory and AgenticVision
AgenticCodebase is part of the Agentic ecosystem. Run all three MCP servers for full cognitive + visual + code understanding:
```json
{
"mcpServers": {
"memory": {
"command": "agentic-memory-mcp",
"args": ["serve"]
},
"vision": {
"command": "agentic-vision-mcp",
"args": ["serve"]
},
"codebase": {
"command": "agentic-codebase-mcp",
"args": []
}
}
}
```
An agent can associate what it *knows* (memory), what it *sees* (vision), and what it *understands about code* (codebase) in a unified workflow.
---
## Build from Source
```bash
git clone https://github.com/agentralabs/codebase.git
cd agentic-codebase
# Build both binaries (acb + agentic-codebase-mcp)
cargo build --release
# Install CLI
cargo install --path .
# Or copy binaries directly
cp target/release/acb /usr/local/bin/
cp target/release/agentic-codebase-mcp /usr/local/bin/
```
### Run tests
```bash
# All tests (432 tests)
cargo test
# Unit tests only
cargo test --lib
# Integration tests only
cargo test --tests
# Benchmarks
cargo bench
```
---
## Package Registry Links
| **agentic-codebase** (core crate) | [crates.io](https://crates.io/crates/agentic-codebase) | `cargo install agentic-codebase` |
| **acb CLI binary** | Bundled in `agentic-codebase` crate | `cargo install agentic-codebase` |
| **agentic-codebase-mcp MCP binary** | Bundled in `agentic-codebase` crate | `cargo install agentic-codebase` |
| **One-line installer** | GitHub release artifacts | `curl -fsSL https://agentralabs.tech/install/codebase \| bash` |
---
## Requirements
| Rust | 1.70+ (for building from source or `cargo install`) |
| OS | macOS, Linux |
| C compiler | Required for tree-sitter grammars (Xcode CLT on macOS) |
---
## Troubleshooting
### `acb: command not found` after `cargo install`
Make sure `~/.cargo/bin` is in your PATH:
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
Add this line to your `~/.zshrc` or `~/.bashrc` to make it permanent.
### Build fails with tree-sitter errors
The tree-sitter grammars require a C compiler. On macOS, ensure Xcode Command Line Tools are installed:
```bash
xcode-select --install
```
### macOS: "can't be opened because Apple cannot check it for malicious software"
```bash
xattr -d com.apple.quarantine $(which acb)
xattr -d com.apple.quarantine $(which agentic-codebase-mcp)
```
### MCP server doesn't respond
Check that the binary is accessible:
```bash
which agentic-codebase-mcp
```
The server communicates via stdin/stdout (MCP stdio transport). If running manually, send a JSON-RPC initialize request to verify:
```bash