Agentra LabsAgentra Labs DocsPublic Documentation
WebsiteGitHub

AgenticCodebase

Integration Guide

This guide covers how to integrate AgenticCodebase into various environments: MCP-compatible AI tools, CI/CD pipelines, custom Rust applications, and the broader Agentic ecosystem.

This guide covers how to integrate AgenticCodebase into various environments: MCP-compatible AI tools, CI/CD pipelines, custom Rust applications, and the broader Agentic ecosystem.

MCP Server Integration

The MCP server (agentic-codebase-mcp) exposes AgenticCodebase to any LLM client that supports the Model Context Protocol.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentic-codebase": {
      "command": "agentic-codebase-mcp",
      "args": []
    }
  }
}

Restart Claude Desktop. The LLM now has access to code analysis tools.

VS Code / Cursor

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "agentic-codebase": {
      "command": "agentic-codebase-mcp",
      "args": []
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "agentic-codebase": {
      "command": "agentic-codebase-mcp",
      "args": []
    }
  }
}

MCP Tools Reference

The MCP server exposes these tools:

ToolDescription
acb_compileCompile a source directory into a graph
acb_loadLoad a pre-compiled .acb file into memory
acb_unloadUnload a graph from memory
acb_infoGet graph metadata (units, edges, languages)
acb_queryRun any of the 24 query types
acb_getGet detailed info about a specific code unit

MCP Resources

Loaded graphs expose resources via acb:// URIs:

URI PatternDescription
acb://graphsList all loaded graphs
acb://graphs/{name}/infoGraph metadata
acb://graphs/{name}/unitsUnit listing
acb://graphs/{name}/units/{id}Specific unit details

Agentic Flow Examples

Once the MCP server is running, your AI agent has access to code analysis tools. Here are example prompts and the tool chains they trigger.

Compile and explore

Prompt your agent with:

Compile this repository and tell me what you find. What are the main entry points? Show me the most important functions by connectivity.

The agent calls acb_compile to build the graph, then uses symbol_lookup and list_units to explore.

Pre-refactor safety

I want to refactor the UserService class. Before I change anything, tell me: what calls it, what it depends on, and what tests cover it?

The agent runs symbol_lookup then impact_analysis to trace callers, dependencies, and test coverage. You get a risk assessment before writing any code.

Code review assistant

I changed the payment processing module. What else in the codebase might be affected? Are there hidden couplings I should worry about?

The agent uses impact analysis and coupling queries to find downstream effects and non-obvious dependencies.

Architecture overview

Give me a high-level overview of this codebase. What are the main modules, how do they relate, and where are the hotspots?

The agent combines list_units (filtered by module), deps, and hotspots queries to build a structural picture.

Key tools available to your agent

ToolWhat it does
acb_compileBuild a .acb graph from source code
symbol_lookupFind functions/classes/modules by name
impact_analysis"What breaks if I change this?"
list_unitsBrowse the code structure
graph_statsGet overview metrics

The graph persists in a .acb file across sessions. Your agent does not need to recompile every time.

CI/CD Integration

AgenticCodebase is designed for automated pipelines. All commands support --format json for machine-readable output.

Impact Analysis on Pull Requests

#!/bin/bash
# ci/impact-check.sh

# Compile the current state
acb compile ./src -o current.acb -f json -q

# Get changed files from git
changed_files=$(git diff --name-only origin/main...HEAD)

# For each changed file, find affected units and run impact analysis
acb -f json query current.acb symbol --name "$changed_function" | \
  jq -r '.results[].id' | \
  while read unit_id; do
    acb -f json query current.acb impact --unit-id "$unit_id"
  done

Stability Monitoring

#!/bin/bash
# ci/stability-check.sh

acb compile ./src -o project.acb -q
prophecy=$(acb -f json query project.acb prophecy --limit 5)

# Check if any high-risk predictions
high_risk=$(echo "$prophecy" | jq '[.results[] | select(.risk_score >= 0.7)] | length')
if [ "$high_risk" -gt 0 ]; then
  echo "WARNING: $high_risk high-risk predictions detected"
  echo "$prophecy" | jq '.results[] | select(.risk_score >= 0.7)'
  exit 1
fi

Coupling Gate

#!/bin/bash
# ci/coupling-check.sh

acb compile ./src -o project.acb -q
coupling=$(acb -f json query project.acb coupling)

# Fail if any coupling strength exceeds threshold
violations=$(echo "$coupling" | jq '[.results[] | select(.strength >= 0.9)] | length')
if [ "$violations" -gt 0 ]; then
  echo "ERROR: $violations coupling violations (strength >= 0.9)"
  exit 1
fi

Rust Library Integration

Use AgenticCodebase as a dependency in your Rust project:

[dependencies]
agentic-codebase = "0.1"

Basic workflow

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, SymbolLookupParams, MatchMode};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Parse
    let parser = Parser::new();
    let result = parser.parse_directory("./src", &ParseOptions::default())?;
    println!("Parsed {} files, {} units", result.stats.files_parsed, result.units.len());

    // 2. Analyze
    let analyzer = SemanticAnalyzer::new();
    let graph = analyzer.analyze(result.units, &AnalyzeOptions::default())?;
    println!("Graph: {} units, {} edges", graph.unit_count(), graph.edge_count());

    // 3. Write
    let writer = AcbWriter::with_default_dimension();
    writer.write_to_file(&graph, "project.acb")?;

    // 4. Read back and query
    let graph = AcbReader::read_from_file("project.acb")?;
    let engine = QueryEngine::new();

    let params = SymbolLookupParams {
        name: "main".to_string(),
        mode: MatchMode::Contains,
        limit: 10,
        ..Default::default()
    };
    let results = engine.symbol_lookup(&graph, params)?;
    for unit in results {
        println!("  {} ({}) at {}:{}",
            unit.qualified_name, unit.unit_type,
            unit.file_path.display(), unit.span.start_line);
    }

    Ok(())
}

Custom query pipelines

use agentic_codebase::engine::query::{ImpactParams, ProphecyParams};

// Impact analysis for a specific unit
let impact = engine.impact_analysis(&graph, ImpactParams {
    unit_id: 42,
    max_depth: 5,
    edge_types: vec![],
})?;

println!("Risk: {:.2}, {} units impacted", impact.overall_risk, impact.impacted.len());

// Code prophecy across the entire graph
let prophecy = engine.prophecy(&graph, ProphecyParams {
    top_k: 10,
    min_risk: 0.3,
})?;

for pred in &prophecy.predictions {
    println!("  Unit {}: risk={:.2} - {}", pred.unit_id, pred.risk_score, pred.reason);
}

Agentic Ecosystem Integration

AgenticCodebase works alongside AgenticMemory and AgenticVision. Run all three MCP servers for an agent with full cognitive, visual, and code capabilities:

{
  "mcpServers": {
    "memory": {
      "command": "agentic-memory-mcp",
      "args": ["serve"]
    },
    "vision": {
      "command": "agentic-vision-mcp",
      "args": ["serve"]
    },
    "codebase": {
      "command": "agentic-codebase-mcp",
      "args": []
    }
  }
}

Cross-system workflows

An agent with all three systems can:

  1. Remember decisions (AgenticMemory) -- "We chose PostgreSQL for the backend."
  2. See UI changes (AgenticVision) -- "The login page layout changed since yesterday."
  3. Understand code structure (AgenticCodebase) -- "The AuthService depends on DatabasePool and is tested by test_auth_flow."

The MCP protocol enables the LLM to seamlessly combine tools from all three servers in a single conversation.

Next Steps