agentifind

Agentifind

Codebase intelligence for AI agents. Extracts code structure so AI coding assistants can navigate your codebase effectively.

Overview

Agentifind analyzes your repository and outputs structured data that AI agents can use for navigation:

• Module structure: imports, exports, classes, functions
• Call graph: what functions call what
• Import graph: module dependencies
• Validation: linting and type check results

Quick Start

cd /path/to/your/repo
npx agentifind sync

This creates .claude/codebase.json - a structured extraction of your codebase.

Installation

Via npx (recommended)

npx agentifind sync

Global install

npm install -g agentifind
agentifind sync

Commands

sync

Extract code structure from your repository:

agentifind sync [options] [path]

Options:

Option	Description
--skip-validate	Skip linting/type checks (faster)
--if-stale	Only sync if source files changed
--verbose, -v	Show extraction progress and method
--languages <list>	Comma-separated languages to analyze
--ci	Exit non-zero on validation failures

Example:

agentifind sync --verbose --skip-validate

status

Check if the codebase index is up to date:

agentifind status [path]

Output

.claude/
├── codebase.json         # Structured code data
└── .agentifind-checksum  # Staleness detection

codebase.json structure

{
  "generated": "2026-01-25T12:00:00.000Z",
  "commit": "abc1234",
  "stats": {
    "files": 100,
    "modules": 20,
    "functions": 500,
    "classes": 50
  },
  "modules": {
    "src/index.ts": {
      "imports": ["./utils", "express"],
      "exports": ["app", "start"],
      "classes": {},
      "functions": {
        "start": { "calls": ["configure", "listen"], "line": 10 }
      }
    }
  },
  "call_graph": {
    "start": ["configure", "listen"]
  },
  "import_graph": {
    "src/index.ts": ["./utils", "express"]
  },
  "validation": {
    "linting": { "status": "pass", "tool": "eslint", "issues": [] },
    "formatting": { "status": "pass", "tool": "prettier", "issues": [] },
    "types": { "status": "pass", "tool": "tsc", "issues": [] }
  }
}

Supported Languages

Language	Extraction	Validation
Python	LSP (pyright) or tree-sitter	ruff, mypy
TypeScript	LSP (tsserver) or tree-sitter	eslint, tsc
JavaScript	tree-sitter	eslint

Extraction Methods

LSP (Language Server Protocol) - Used first if available:

• More accurate cross-file reference resolution
• Requires language server installed:
  • Python: npm install -g pyright
  • TypeScript: bundled with typescript
• Takes 5-15 minutes on large codebases

Tree-sitter - Fast fallback:

• AST-based parsing, ~30 seconds
• Heuristic-based cross-file resolution
• Always available, no extra dependencies

Usage with AI Agents

After running agentifind sync, use the /agentifind skill to synthesize a human-readable CODEBASE.md guide from the extracted data.

The skill:

• Reads .claude/codebase.json
• Identifies key components and architecture
• Writes .claude/CODEBASE.md for agent reference

Requirements

• Node.js >= 18
• Git repository (initialized with git init)
• macOS or Linux (Windows via WSL)

License

MIT