dominian 1.0.9

Code intelligence for AI agents — scan codebases, query dependency graphs, detect cycles, find hotspots, analyze impact, and assess refactoring safety.

Dominian

Code Intelligence for AI Agents

Dominian scans your codebase, builds a dependency graph in SQLite, and exposes that graph through a CLI and an MCP (Model Context Protocol) server — purpose-built for LLM agents to query code structure, dependencies, impact, and refactoring safety without reading every file.

---

Why Dominian?

When an AI agent needs to understand a codebase, it currently has two bad options:

1. Read every file — burns through token budgets, hits context windows, and still misses cross-file relationships.
2. Use grep/search — finds text matches but cannot tell you who depends on this function or what breaks if I change this class.

Dominian gives agents a third option: query a structured graph. One dominian deps reverse MyClass call tells an agent exactly who uses MyClass, without reading 200 files to find out.

What It Does

• Scans source files in 7 languages (Python, JavaScript, TypeScript, Java, Go, Rust, C/C++)
• Extracts code entities: functions, classes, methods, modules, variables, imports
• Resolves dependency edges: imports, calls, uses, defines, inherits, implements
• Stores everything in a local SQLite graph database (WAL mode, fully indexed)
• Exposes the graph via CLI commands and MCP tools with three output formats:
  • minimal — ultra-compact, ~85% token reduction vs verbose (default, designed for agents)
  • agent — human-readable with structure and context
  • json — machine-parseable for programmatic use

---

Quick Start

Installation

# Core package (CLI + graph database)
pip install dominian

# With MCP server support
pip install dominian[mcp]

# With community detection (networkx + python-louvain)
pip install dominian[communities]

# Everything
pip install dominian[all]

Initialize and Scan

# Initialize the project database
dominian init

# Scan the current directory
dominian scan . --no-watch

# Check what was found
dominian info

Query the Graph

# Search for a function or class
dominian search "handle_request"

# Get details about a specific entity
dominian node get handle_request

# What does this function depend on?
dominian deps direct handle_request

# What depends on this function? (reverse deps)
dominian deps reverse handle_request

# Impact analysis — what breaks if I change this?
dominian arch impact handle_request

# Is this safe to refactor?
dominian refactor safe handle_request

# Find circular dependencies
dominian graph cycles

# Find complexity hotspots
dominian graph hotspots

# Detect code communities (requires python-louvain)
dominian arch communities

# List functions in a file
dominian file functions src/server.py

MCP Server (for AI Agents)

# Start MCP server with stdio transport (default)
dominian-mcp

# Or with SSE transport for remote access
dominian-mcp --transport sse --port 8080

Then configure your MCP client (Claude Desktop, Cursor, etc.):

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

---

Output Formats

Dominian's output is designed with token efficiency as a first-class concern. The minimal format (default) uses a compact locator syntax and achieves ~85% token reduction compared to verbose output while retaining 100% of the information.

Example: Node Lookup

Minimal format (default):

📍 src/server.py:handle_request:42-89 fn c:12 q:78.3 deps:5 used_by:3

Agent format (--format agent):

NODE: handle_request
============================================================

Type: function
File: src/server.py
Lines: 42-89
Quality: 78.3
Complexity: 12
Signature: def handle_request(req: Request, db: Database) -> Response
Docstring: Process incoming HTTP request and route to appropriate handler

JSON format (--format json):

{
  "type": "agentgraph_result",
  "data": {
    "node": {
      "name": "handle_request",
      "type": "function",
      "file": "src/server.py",
      "line_start": 42,
      "line_end": 89,
      "complexity": 12,
      "quality": 78.3
    }
  }
}

Locator Syntax

The minimal format uses a universal locator pattern:

folder/file:name:line(type)

Component	Meaning	Example
folder/file	Relative file path (last two segments)	src/server.py
name	Entity name	handle_request
line	Start line number	42
(type)	Abbreviated type: fn, cls, mod, var, imp	(fn)

Full example: src/server.py:handle_request:42(fn)

---

CLI Reference

Dominian follows a strict dominian <group> <action> [target] [options] structure.

Project Lifecycle

Command	Description
dominian init [--db-path PATH]	Initialize project and create database
dominian scan [PATH] [--db-path PATH] [--no-watch]	Scan codebase and populate database
dominian info [--db-path PATH]	Show project status and statistics

Search & Lookup

Command	Description
dominian search QUERY [--format FMT]	Search for code entities by name
dominian node get ENTITY [--format FMT]	Get details of a specific entity
dominian node show ENTITY [--format FMT]	Alias for node get

Dependency Analysis

Command	Description
dominian deps direct ENTITY [--format FMT]	Show direct dependencies
dominian deps reverse ENTITY [--format FMT]	Show reverse dependencies (who uses this)

Architecture Analysis

Command	Description
dominian arch impact ENTITY [--format FMT]	Analyze blast radius of a change
dominian arch communities [--format FMT]	Detect code communities (Louvain)
dominian arch cross-community [--format FMT]	Find cross-community boundary edges

Graph Analysis

Command	Description
dominian graph stats [--format FMT]	Graph statistics
dominian graph hotspots [--limit N] [--format FMT]	Complexity hotspots
dominian graph cycles [--format FMT]	Circular dependency detection

Refactoring Support

Command	Description
dominian refactor safe ENTITY [--format FMT]	Check refactoring safety
dominian refactor impact ENTITY [--format FMT]	Show refactoring impact (alias for arch impact)

File Analysis

Command	Description
dominian file functions FILE [--format FMT]	List functions in a file
dominian file classes FILE [--format FMT]	List classes in a file

Global Options

Option	Description
--version	Show version
--format FORMAT	Output format: minimal (default), agent, json
--db-path PATH	Custom database path (default: .dominian/agentgraph.db)

Environment Variables

Variable	Default	Description
DOMINIAN_DB	.dominian/agentgraph.db	Database path
DOMINIAN_ROOT	Current working directory	Project root path

---

MCP Tools

The MCP server exposes all CLI functionality as tools with minimal-format output. See docs/AGENT_GUIDE.md for detailed agent integration instructions.

Tool	Description
dominian_init	Initialize project
dominian_scan	Scan codebase
dominian_search	Search entities
dominian_node_get	Get entity details
dominian_deps_direct	Direct dependencies
dominian_deps_reverse	Reverse dependencies
dominian_arch_impact	Impact analysis
dominian_arch_communities	Community detection
dominian_arch_cross_community	Cross-community edges
dominian_graph_stats	Graph statistics
dominian_graph_hotspots	Complexity hotspots
dominian_graph_cycles	Circular dependencies
dominian_refactor_safe	Refactoring safety check
dominian_refactor_impact	Refactoring impact
dominian_file_functions	Functions in a file
dominian_file_classes	Classes in a file
dominian_info	Project status
dominian_nodes_by_type	Entities by type
dominian_nodes_by_quality	Entities by quality score
dominian_god_nodes	Highly connected nodes
dominian_orphans	Unconnected nodes
dominian_surprising_connections	Cross-directory coupling

MCP Resources

Resource	Description
dominian://status	Current project status
dominian://schema	Database schema information

MCP Prompts

Prompt	Description
code_review(entity)	Generate a code review for a specific entity
architecture_review()	Full architecture review workflow
refactor_plan(entity)	Generate a refactoring plan

---

Language Support

Language	Extensions	Parser	Import Resolution
Python	.py, .pyw, .pyi	tree-sitter + regex fallback	Yes (relative + absolute)
JavaScript	.js, .jsx, .mjs, .cjs	tree-sitter + regex fallback	Yes (relative)
TypeScript	.ts, .tsx	tree-sitter + regex fallback	Yes (relative)
Java	.java	tree-sitter + regex fallback	Yes (package-based)
Go	.go	tree-sitter + regex fallback	Yes (relative)
Rust	.rs	tree-sitter + regex fallback	Yes (crate-relative)
C/C++	.c, .h, .cpp, .hpp, .cc, .hh, .cxx, .hxx	tree-sitter + regex fallback	Yes (relative includes)

Tree-sitter is used when available; regex-based extraction serves as the universal fallback when tree-sitter grammars are not installed.

---

Database Schema

Dominian stores everything in a single SQLite database with WAL mode for concurrent read/write performance.

Nodes Table

Column	Type	Description
id	TEXT PK	{file}::{name}
name	TEXT	Entity name
type	TEXT	function, method, class, module, variable, import, dependency
file	TEXT	Source file path
language	TEXT	Source language
line_start	INTEGER	Start line
line_end	INTEGER	End line
complexity	INTEGER	Cyclomatic complexity score
quality	REAL	Quality score (0-100, default 100)
signature	TEXT	Function/method signature
docstring	TEXT	Documentation string
metadata	TEXT (JSON)	Additional metadata
confidence	TEXT	EXTRACTED or INFERRED
provenance	TEXT	regex_parser or tree_sitter
community	INTEGER	Community ID (after detection)

Edges Table

Column	Type	Description
id	TEXT PK	{from_id}--{relationship}--{to_id}
from_node	TEXT	Source node ID
to_node	TEXT	Target node ID
relationship	TEXT	imports, depends_on, uses, calls, defines, inherits, implements
weight	REAL	Edge weight (1.0-9.0)
confidence	REAL	Extraction confidence
provenance	TEXT	Parser that created this edge

---

How Dominian Helps Agents

Token Efficiency

Dominian's minimal format was designed from the ground up to maximize information density per token. Instead of returning multi-line verbose output, a dependency query returns a single compact line:

📥 handle_request→ src/db.py:get_conn:15(fn) imports | src/utils.py:validate:8(fn) calls

This single line tells the agent: handle_request depends on get_conn (import relationship, in src/db.py at line 15, it's a function) and validate (call relationship, in src/utils.py at line 8, also a function). The agent gets file, name, line, type, and relationship in one token-efficient string.

Impact Analysis

Before an agent modifies code, it can check the blast radius:

dominian arch impact process_payment
# Output: ⚠️ HIGH 7:order_service,invoice_gen,payment_validator,refund_handler,...

This immediately tells the agent: changing process_payment has HIGH risk and affects 7 other entities. The agent can then make informed decisions about whether to proceed, add tests, or request human review.

Refactoring Safety

dominian refactor safe utility_function
# Output: ✅ SAFE utility_function

Zero dependents. The agent can modify this freely without risk of breaking anything.

Architecture Understanding

Community detection groups code into logical modules. Cross-community edges reveal hidden coupling. An agent can use this to understand the codebase's modular structure without reading every file.

---

Architecture

                    ┌─────────────┐
                    │   CLI       │  main_new.py
                    │ (argparse)  │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │   MCP       │  server.py
                    │  Server     │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──────┐ ┌──▼───┐ ┌──────▼──────┐
       │  Formatter   │ │Engine│ │  Database   │
       │  formatter.py│ │engine│ │  database.py│
       └─────────────┘ │.py   │ └─────────────┘
                       └──┬───┘
                          │
                  ┌───────▼───────┐
                  │  Adaptive     │  adaptive_scanner.py
                  │  Scanner      │
                  └───────┬───────┘
                          │
              ┌───────────┼───────────┐
              │           │           │
     ┌────────▼──┐ ┌──────▼──────┐ ┌─▼──────────────┐
     │ Parser    │ │ Import      │ │ Tree-sitter    │
     │ Registry  │ │ Resolver    │ │ Parser + Config│
     │ __init__.py│ │import_resolv│ │ tree_sitter_*.py│
     └───────────┘ └─────────────┘ └────────────────┘

See docs/ARCHITECTURE.md for detailed design decisions.

---

Development

# Clone
git clone https://github.com/yourusername/dominian.git
cd dominian

# Install in development mode
pip install -e ".[all]"

# Run CLI
python -m dominian init
python -m dominian scan . --no-watch

# Run MCP server
python -m dominian.server

See CONTRIBUTING.md for contribution guidelines.

---

Documentation

Document	Description
README.md	This file — overview and quick start
CONTRIBUTING.md	How to contribute
CHANGELOG.md	Version history
docs/ARCHITECTURE.md	System architecture and design
docs/API_REFERENCE.md	Full API and tool reference
docs/AGENT_GUIDE.md	Guide for AI agent integration
docs/TOKEN_USAGE.md	Token usage analysis and optimization

---

License

MIT