agentifind

agentifind

AI-powered developer tools that help AI agents understand and work with your codebase.

Overview

Agentifind provides two capabilities:

• Codebase Indexing - Analyze your repository to extract symbols, conventions, boundaries, and test mappings. Expose this data via MCP (Model Context Protocol) so AI coding agents can query your codebase intelligently.

• Pre-commit Setup - Automatically configure pre-commit hooks tailored to your project's tech stack using AI analysis.

Quick Start

You don't need to clone this repository. Just run via npx in your project:

# Index your codebase for AI agents
cd /path/to/your/repo
npx agentifind init

# Or set up pre-commit hooks
export ANTHROPIC_API_KEY="sk-ant-..."  # or OPENAI_API_KEY
npx agentifind configure-precommit

Installation Options

Option 1: npx (no installation)

npx agentifind init                    # Index codebase for AI agents
npx agentifind configure-precommit     # Set up pre-commit hooks

Option 2: Global install

npm install -g agentifind

# Then use without npx
agentifind init
agentifind configure-precommit

Codebase Indexing (init)

Index your codebase so AI coding agents can understand its structure, conventions, and boundaries.

npx agentifind init

Output:

[1/4] Analyzing repository structure...
[2/4] Inferring coding conventions...
[3/4] Detecting module boundaries...
[4/4] Configuring MCP server...
✓ Created .mcp.json with agentifind server

Restart Claude Code to load the MCP server

What it creates

.agent/ folder (code index):

.agent/
├── index.json          # Symbols, references, imports
├── conventions.md      # Inferred coding conventions
├── boundaries.md       # Public API vs internal
├── test-map.json       # Test to source mappings
└── entrypoints.json    # Main functions, CLI commands, handlers

.mcp.json (auto-configured for Claude Code):

{
  "mcpServers": {
    "agentifind": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "agentifind", "serve"]
    }
  }
}

MCP Tools

The MCP server exposes 6 tools that AI agents can use:

Tool	Purpose
get_conventions	Get coding conventions for a topic
find_callers	Find all callers of a function
get_tests_for	Find tests for a file/function
trace_path	Trace call path between symbols
get_boundaries	Check if code is public/internal
related_files	Find related files

Options

agentifind init [OPTIONS] [REPO_PATH]

Options:
  --languages <list>    Comma-separated languages to analyze (default: auto-detect)
  --skip-conventions    Skip LLM-based convention inference (faster, no API key needed)
  --verbose, -v         Show detailed progress
  --help, -h            Show help

Convention inference (optional)

Set an API key to enable LLM-based convention inference:

export ANTHROPIC_API_KEY="sk-ant-..."  # or OPENAI_API_KEY
npx agentifind init

Without an API key, convention inference is skipped but all other features work.

Supported Languages

• Python - Functions, classes, imports, decorators
• Go - Functions, methods, interfaces, packages

Pre-commit Setup (configure-precommit)

Automatically configure pre-commit hooks for your repository using AI analysis.

export ANTHROPIC_API_KEY="sk-ant-..."  # or OPENAI_API_KEY
npx agentifind configure-precommit

Supported stacks

Category	Tools
Python	ruff, ruff-format, mypy, bandit
JavaScript/TypeScript	eslint, prettier
Go	golangci-lint, go-fmt, go-imports
Java	pretty-format-java
Shell	shellcheck
Terraform	terraform_fmt, tflint, checkov
Docker	hadolint
YAML	yamllint, check-yaml
JSON	check-json
Security	gitleaks, detect-private-key
General	trailing-whitespace, end-of-file-fixer, check-merge-conflict, no-commit-to-branch

Options

agentifind configure-precommit [OPTIONS] [REPO_PATH]

Options:
  --dry-run           Generate config without installing hooks
  --skip-autoupdate   Skip running pre-commit autoupdate
  --debug             Enable debug output
  --help, -h          Show this help message

How it works

┌─────────────────────────────────────────────────────────────────┐
│  Phase 1: SENSOR                                                │
│  └── Scan repo structure, detect languages/frameworks           │
│                                                                 │
│  Phase 2: AUDITOR (LLM)                                         │
│  └── AI analyzes repo, generates optimal pre-commit config      │
│                                                                 │
│  Phase 3: BUILDER                                               │
│  ├── Write .pre-commit-config.yaml                              │
│  ├── Run pre-commit autoupdate (get latest versions)            │
│  └── Install git hooks                                          │
│                                                                 │
│  Phase 4: VERIFICATION & SELF-HEALING                           │
│  ├── Run pre-commit on all files                                │
│  └── If config errors → AI debugger fixes → retry (max 3x)      │
│                                                                 │
│  Phase 5: SUMMARY                                               │
│  └── Report installed hooks and any code issues found           │
└─────────────────────────────────────────────────────────────────┘

CLI Reference

agentifind <command> [options]

Commands:
  init                 Index your codebase for AI agents (creates .agent/)
  configure-precommit  Auto-configure pre-commit hooks using AI analysis
  serve                Start the MCP server for AI agent integration
  query                Query the index directly from command line
  help                 Show help

Global Options:
  -h, --help          Show help message
  -v, --version       Show version

Query examples

agentifind query get_conventions --topic=error_handling
agentifind query find_callers --symbol=main
agentifind query get_tests_for --target=src/index.ts
agentifind query trace_path --from=main --to=handleRequest
agentifind query get_boundaries --target=lib/
agentifind query related_files --file=src/parser.ts

Requirements

• macOS or Linux (Windows via WSL)
• Node.js >= 14
• Git repository (initialized with git init)
• API key (optional for init, required for configure-precommit)

Claude Desktop Integration

For Claude Desktop (not Claude Code), add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentifind": {
      "command": "npx",
      "args": ["-y", "agentifind", "serve"],
      "cwd": "/path/to/your/repo"
    }
  }
}

Contributing

git clone https://github.com/avivkaplan/agentifind.git
cd agentifind

npm install
npm run build
./tests/run_tests.sh

License

MIT