ADR-065: Codanna Code Intelligence Integration

Status

Accepted - January 11, 2026

MoE Council Verdict: INTEGRATE (Conditional) Consensus Score: 80/100 Confidence: 81%

Context

Problem Statement

CODITECT users need advanced code intelligence capabilities for:

1. Semantic Code Search - Natural language queries against code ("find authentication handlers")
2. Impact Analysis - Understanding change ripple effects before refactoring
3. Call Graph Navigation - Tracing function calls and callers
4. AI-Powered Discovery - Claude Code integration via MCP protocol

Current limitations:

• component-indexer.py indexes markdown components, not source code
• No call graph or relationship tracking
• No semantic/embedding-based code search
• No MCP tools for code intelligence

Candidate Solution

Codanna v0.9.10 - A Rust-based code intelligence tool providing:

• Semantic code search via Tantivy + fastembed
• Symbol discovery with sub-10ms lookups (memory-mapped caches)
• Call graph analysis - get_calls, find_callers, analyze_impact
• Document RAG - Index markdown/text for semantic search
• MCP Protocol - Native Claude Code integration
• 13 Languages - Rust, Python, JavaScript, TypeScript, Java, Kotlin, Go, PHP, C, C++, C#, Swift, GDScript

MoE Council Evaluation

A 6-agent Constitutional Court panel evaluated codanna:

Specialist	Score	Verdict
Research Agent	78/100	POSITIVE WITH CAVEATS
Senior Architect	72/100	PARTIAL ALIGNMENT
Rust QA Specialist	87/100	READY
Security Specialist	LOW-MEDIUM	CONDITIONAL APPROVAL
Codebase Analyzer	Complete	9 MCP tools identified
Council Orchestrator	80/100	INTEGRATE (Conditional)

Full Analysis: internal/analysis/codanna-integration/CODANNA-INTEGRATION-ANALYSIS.md

Decision

Integrate codanna into coditect-core as an optional code intelligence module using a phased approach:

Integration Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         CODITECT + CODANNA INTEGRATION                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                      Claude Code (AI Assistant)                       │   │
│  └───────────────────────────────┬──────────────────────────────────────┘   │
│                                  │ MCP Protocol                              │
│                                  ▼                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         MCP Server (stdio)                            │   │
│  │  codanna serve --watch                                                │   │
│  └───────────────────────────────┬──────────────────────────────────────┘   │
│                                  │                                           │
│         ┌────────────────────────┼────────────────────────┐                 │
│         ▼                        ▼                        ▼                 │
│  ┌─────────────┐         ┌─────────────┐         ┌─────────────┐           │
│  │ find_symbol │         │  get_calls  │         │ semantic_   │           │
│  │ find_callers│         │analyze_impact│        │   search    │           │
│  │search_symbols│        │             │         │             │           │
│  └──────┬──────┘         └──────┬──────┘         └──────┬──────┘           │
│         │                       │                       │                   │
│         └───────────────────────┼───────────────────────┘                   │
│                                 ▼                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                          IndexFacade                                  │   │
│  │  ├── DocumentIndex (Tantivy)     ← Full-text search                  │   │
│  │  ├── SemanticSearch (fastembed)  ← Vector embeddings                 │   │
│  │  └── Pipeline (tree-sitter)      ← Symbol extraction                 │   │
│  └───────────────────────────────┬──────────────────────────────────────┘   │
│                                  │                                           │
│                                  ▼                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    .coditect/.codanna/index/                          │   │
│  │  ├── tantivy/        ← Inverted index (symbols, files)               │   │
│  │  ├── semantic/       ← Vector store (embeddings)                     │   │
│  │  └── metadata.json   ← Index state                                   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Storage Separation

Codanna and CODITECT use separate storage systems for orthogonal purposes:

System	Storage	Purpose
CODITECT	SQLite (context.db)	Session messages, task tracking, customer data (ADR-089)
CODITECT	SQLite (platform.db)	Component metadata, capabilities, triggers (ADR-089)
Codanna	Tantivy + Vectors	Source code symbols, relationships, embeddings

No migration or unification required - systems complement each other.

MCP Tools Available

Tool	Purpose	Example
find_symbol	Exact name lookup	find_symbol(name: "UserService")
get_calls	Function calls made	get_calls(symbol_id: 42)
find_callers	Reverse call graph	find_callers(name: "authenticate")
analyze_impact	Dependency graph	analyze_impact(name: "login", depth: 3)
search_symbols	Fuzzy search	search_symbols(query: "auth", kind: "function")
semantic_search	Natural language	semantic_search(query: "error handling")
semantic_search_with_context	Semantic + relationships	Full context retrieval
get_index_info	Index statistics	Symbol count, file count
search_documents	RAG search	Query documentation collections

Customer-Facing Commands

Command	Purpose
/code-search <query>	Semantic code search
/impact <symbol>	Show affected code
/callers <function>	Find all callers
/calls <function>	Show what function calls
/code-index	Index/reindex project

Configuration

File: .coditect/config/codanna.json

{
  "codanna": {
    "enabled": true,
    "auto_index": true,
    "include_paths": ["src/", "lib/", "scripts/"],
    "exclude_paths": ["node_modules/", "dist/", ".git/"],
    "languages": ["rust", "python", "typescript", "javascript"],
    "semantic_search": {
      "enabled": true,
      "embedding_model": "AllMiniLML6V2",
      "threshold": 0.6
    },
    "mcp_server": {
      "mode": "stdio",
      "auto_start": true
    },
    "index_location": ".coditect/.codanna/"
  }
}

MCP Configuration

File: ~/.claude/mcp.json (or project-level)

{
  "mcpServers": {
    "codanna": {
      "command": "codanna",
      "args": ["serve", "--watch"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Implementation Phases

Phase 1: MCP Client Wrapper (Week 1-2)

Scope: Basic integration via stdio MCP

Deliverables:

• Create /code-search command
• Create /code-index command
• Add codanna.json configuration schema
• MCP server auto-configuration in ~/.claude/mcp.json
• Integration with CODITECT-CORE-INITIAL-SETUP.py

Risk Mitigations:

• R1: Fork repository to github.com/coditect-ai/codanna ✅ DONE
• R2: Use stdio mode only (disable HTTP)
• R3: Add cargo audit to CI pipeline

Phase 2: Configuration Integration (Week 3-4)

Scope: Seamless configuration and indexing

Deliverables:

• Create /impact, /callers, /calls commands
• Build codanna-* skills
• Auto-generate .codanna/settings.toml from CODITECT config
• Incremental indexing hooks (on file save)

Phase 3: Agent Integration (Week 5-8)

Scope: Enhanced agent workflows

Deliverables:

• Create code-refactoring-agent leveraging impact analysis
• Integrate with senior-architect for code review
• Add semantic search to /which agent discovery
• Cross-reference with component index

Phase 4: Binary Distribution (Deferred)

Scope: Pre-compiled binaries for customers

Decision: Defer until Phase 1-3 prove value

Options:

• npm package: @coditect/codanna
• Homebrew: brew install coditect/tap/codanna
• Pre-bundled: ~/.coditect/bin/codanna

Risk Mitigation

Critical Risks Addressed

Risk	Severity	Mitigation
Single maintainer	HIGH	Fork to CODITECT org, monthly upstream sync
HTTP dummy OAuth	HIGH	stdio mode only (no network exposure)
Path traversal	MEDIUM	Add canonicalization before production
API instability	MEDIUM	Pin versions, test upgrades in staging

Security Requirements

1. stdio mode only - No HTTP/HTTPS server in production
2. Path restrictions - Index only within workspace boundaries
3. Secret exclusions - Default .codannaignore template:

   *.env*
   *.key
   *.pem
   credentials.*
   secrets.*

4. Dependency auditing - cargo audit in CI pipeline

Consequences

Positive

1. Semantic Code Search - Natural language queries against code
2. Impact Analysis - Safe refactoring with dependency visibility
3. MCP Integration - Industry-standard protocol for AI assistants
4. Performance - Sub-10ms symbol lookups, 75K+ symbols/sec parsing
5. Multi-Language - 13 languages supported out of box
6. Customer Value - Zero-config code intelligence for all projects

Negative

1. Dependency Weight - 608 crates, ~15-20MB binary
2. Single Maintainer - Requires fork and monitoring strategy
3. Index Storage - Additional disk usage (~50-200MB per project)
4. Learning Curve - New commands and workflows to document

Neutral

1. Separate Storage - Tantivy for code, SQLite for context (no conflict)
2. Optional Feature - Can be disabled if not needed
3. Phased Rollout - Value proven incrementally

Alternatives Considered

Option A: Build In-House (Rejected)

Effort: 6-12 months Reason: Codanna provides 90% of needed functionality; building from scratch not justified

Option B: Sourcegraph (Rejected)

Effort: Enterprise licensing, heavy infrastructure Reason: Over-engineered for CODITECT use case; requires separate deployment

Option C: rust-analyzer Integration (Rejected)

Effort: Rust-only, no MCP protocol Reason: Single language; codanna supports 13 languages with MCP

Option D: tree-sitter-graph (Rejected)

Effort: Build tool, not search engine Reason: Requires building search layer on top; codanna is complete solution

Related Documents

• Analysis: internal/analysis/codanna-integration/CODANNA-INTEGRATION-ANALYSIS.md
• Submodule: codanna/ (added 2026-01-11)
• MoE Council: 6-agent Constitutional Court evaluation
• ADR-060: MoE Verification Layer (evaluation methodology)

Appendix

A. Submodule Location

coditect-core/
└── codanna/           ← Git submodule (v0.9.10)
    ├── src/           ← Rust source (238 files, 106K LOC)
    ├── docs/          ← Documentation
    ├── tests/         ← Test suite (680 tests)
    ├── Cargo.toml     ← Dependencies
    └── README.md      ← Usage guide

B. Performance Benchmarks

Metric	Value	Source
Symbol lookup	<10ms	Memory-mapped Tantivy
Parsing speed	75K+ symbols/sec	Tree-sitter parallel parsing
Semantic search	<300ms	fastembed AllMiniLML6V2
Index size	~50MB per 100K symbols	Tantivy + vectors

C. Council Audit Trail

Artifact Hash: sha256:codanna-analysis-2026-01-11
Stage 1 Hashes:
  research-agent:     a01b640
  senior-architect:   abb9df8
  rust-qa-specialist: a15f3fb
  security-specialist: aa4b40c
  codebase-analyzer:  a0ead8b
Stage 2 Hash: ab2de22
Chairman Hash: a4f7c9e2b1d8f3a6e5c4b7d9f2e8a1c3b6d5f4e7a9c2b8d1f5e3a7c4b9d6f2e8
Council Date: 2026-01-11

---

Author: MoE Council Orchestrator Reviewers: research-agent, senior-architect, rust-qa-specialist, security-specialist, codebase-analyzer Approved By: Council Chairman (81% confidence)