{
  "markdown": "# AgentsBestFriend (abf)\n\nGive your AI coding agents superpowers — a local [MCP](https://modelcontextprotocol.io/) server for fast, token-efficient code navigation, search & analysis.\n\nWorks with **VS Code Copilot**, **Cursor**, **Claude Code/Desktop**, **Codex**, **Cline**, **Zed**, **Gemini CLI**, **Goose**, **OpenCode**, and any other MCP-compatible agent.\n\n---\n\n## Why?\n\nAI coding agents waste tokens re-reading files and searching blindly. ABF gives them purpose-built tools that return exactly what they need — in compact, structured responses that preserve context.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `abf_search` | Code search — exact (ripgrep), keyword-ranked, or semantic (embedding-based) |\n| `abf_search_multi` | Run multiple search queries (exact/keyword/semantic) in one call with weighted score merging |\n| `abf_symbols` | Functions, classes, exports in a file (AST-based for TS/JS, regex for Python) |\n| `abf_chunk` | Smart file chunk by symbol name, chunk index, or file overview |\n| `abf_project_overview` | Tech stack, folder structure, key dependencies at a glance |\n| `abf_dependencies` | Import graph — who imports what |\n| `abf_impact` | Find all usages of a symbol across the project |\n| `abf_impact_typed` | AST-aware (ts-morph) impact analysis with classified references (definition/call/import/type_ref/jsx) and confidence levels |\n| `abf_blast_radius` | BFS over reverse-import graph for a file with risk scoring (low/medium/high) |\n| `abf_related_tests` | Heuristically rank test files most likely to cover a file or symbol |\n| `abf_preview_changes` | Read-only preview: diff + symbol/import deltas + risk flags + external usage probe (no writes) |\n| `abf_refactor_plan` | Read-only ordered edit plan for rename/move/extract/split with collision detection |\n| `abf_apply_edit` | **Write tool** — atomic file write with sha256 hash check (disabled unless `ABF_ENABLE_WRITES=1`) |\n| `abf_diagnostics` | TypeScript diagnostics (errors/warnings) for one file or all tracked TS/JS files |\n| `abf_definition` | Goto-definition via the TypeScript language service — file, line range, and source preview |\n| `abf_hover` | Type signature + JSDoc for an identifier (IDE-style hover) |\n| `abf_call_graph` | Transitive callers/callees of a function or method (TS/JS, ts-morph) |\n| `abf_git` | Git log, blame, diff (recent/staged/unstaged) |\n| `abf_file_summary` | Full-text search across LLM-generated file summaries (FTS5, OR/AND mode) |\n| `abf_conventions` | Detected naming, structure, and formatting conventions |\n| `abf_index` | Index status, rebuild, incremental update, or trigger re-summarization |\n| `abf_ping` | Health check — returns version and project root |\n\n## Install\n\n```bash\nnpm install -g agentsbestfriend\n```\n\n### Prerequisites\n\n- **Node.js** ≥ 20\n- **ripgrep** — `brew install ripgrep` (macOS) / `apt install ripgrep` (Linux)\n- **git**\n- **Ollama** (optional) — for summaries & semantic search: [ollama.com](https://ollama.com)\n\n## Quick Start\n\n```bash\nabf init\n```\n\n`abf init` walks you through everything:\n\n1. **Indexes your project** — discovers and indexes all files via `git ls-files`\n2. **Generates LLM summaries & embeddings** (if Ollama is running) — with live `(12/80)` progress\n3. **Adds `.abf/` to `.gitignore`** — prompts before writing\n4. **Installs ABF as an MCP server** for your agents — you pick which agents (Cursor, VS Code, Claude Code, etc.) and whether to use `npx agentsbestfriend start` (always latest) or `abf start` (local install)\n\n### Manual Agent Setup\n\nIf you prefer to configure manually, add ABF as a stdio MCP server. Using `npx` is recommended — it always runs the latest published version without requiring a global install:\n\n**VS Code / GitHub Copilot** (`.vscode/mcp.json`):\n```json\n{\n  \"servers\": {\n    \"abf\": {\n      \"command\": \"npx\",\n      \"args\": [\"agentsbestfriend\", \"start\"]\n    }\n  }\n}\n```\n\n**Cursor** (`.cursor/mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"abf\": {\n      \"command\": \"npx\",\n      \"args\": [\"agentsbestfriend\", \"start\"]\n    }\n  }\n}\n```\n\n**Claude Desktop** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"abf\": {\n      \"command\": \"npx\",\n      \"args\": [\"agentsbestfriend\", \"start\"]\n    }\n  }\n}\n```\n\n> Set `ABF_PROJECT_ROOT` in the `env` block if the agent does not pass its working directory automatically.\n\n## CLI Commands\n\n```\nabf start             Start MCP server in stdio mode (used by agents)\nabf init [path]       Index project, set up .gitignore entry, install MCP for agents\nabf skill [path]      Install or update the ABF workflow skill for your coding agents\nabf index [path]      Re-index a project (incremental by default)\nabf status [path]     Show index stats\nabf config            Interactive configuration editor\nabf doctor            Health checks (Node, ripgrep, git, Ollama)\nabf portal            Interactive TUI dashboard\n```\n\n## How It Works\n\nABF maintains a lightweight SQLite index (`.abf/index.db`) inside each project root. The index is built once and updated incrementally — only changed files are re-processed. A file watcher keeps it current as you edit.\n\n| Table | Contents |\n|---|---|\n| `files` | Paths, hashes, languages, line counts, LLM summaries |\n| `symbols` | Functions, classes, interfaces, types (AST-extracted) |\n| `imports` | Dependency edges between files |\n| `embeddings` | Float32 vectors for semantic search (chunked for large files) |\n| `file_chunks` | Smart chunks aligned to symbol boundaries |\n| `files_fts` | FTS5 full-text index over summaries |\n\n## Optional: LLM Enrichment\n\nWith [Ollama](https://ollama.com) running locally, ABF generates file summaries and embeddings:\n\n```bash\nollama pull qwen2.5-coder:1.5b    # file summaries\nollama pull nomic-embed-text       # embeddings / semantic search\n```\n\nBoth `abf init` and `abf portal → Re-index` show live progress:\n\n```\n◆  Generating LLM summaries... (14/80)\n◆  Generating embeddings... (28/80)\n```\n\nLarge files are automatically split into chunks for embedding — no context-length errors.\n\nWithout Ollama, all tools still work normally. Semantic search falls back to keyword mode.\n\n## Configuration\n\nGlobal config at `~/.abf/config.json`. Edit interactively with `abf config` or via `abf portal`.\n\n```json\n{\n  \"llm\": {\n    \"provider\": \"ollama\",\n    \"ollama\": {\n      \"baseUrl\": \"http://localhost:11434\",\n      \"summaryModel\": \"qwen2.5-coder:1.5b\",\n      \"embeddingModel\": \"nomic-embed-text\"\n    }\n  },\n  \"indexing\": {\n    \"autoWatch\": true,\n    \"respectGitignore\": true,\n    \"maxFileSizeKb\": 512,\n    \"excludedPatterns\": [\"*.min.js\", \"*.min.css\", \"*.map\", \"*.lock\"]\n  },\n  \"search\": {\n    \"defaultMaxResults\": 20\n  }\n}\n```\n\n## Architecture\n\n```\nAgentsBestFriend/\n├── packages/\n│   ├── core/     Shared logic — DB, config, search, analysis, indexer, LLM\n│   ├── server/   MCP server (11 tools)\n│   └── cli/      Commander.js CLI + TUI portal\n├── turbo.json\n└── package.json\n```\n\nBuilt with Turborepo + pnpm workspaces. Core modules:\n\n| Module | Purpose |\n|---|---|\n| `@abf/core/db` | Drizzle ORM + SQLite (WAL, FTS5) |\n| `@abf/core/config` | Zod-validated config |\n| `@abf/core/search` | ripgrep, keyword scorer, semantic (cosine similarity) |\n| `@abf/core/analysis` | ts-morph AST, conventions detector, project overview |\n| `@abf/core/indexer` | git ls-files discovery, incremental pipeline, file watcher |\n| `@abf/core/llm` | Ollama client, summary & chunked embedding pipelines |\n| `@abf/core/git` | Git CLI wrapper |\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Watch mode\npnpm dev\n\n# Type-check\npnpm type-check\n```\n\n## Links\n\n- **GitHub**: [github.com/TheRealFloatDev/AgentsBestFriend](https://github.com/TheRealFloatDev/AgentsBestFriend)\n- **npm**: [npmjs.com/package/agentsbestfriend](https://npmjs.com/package/agentsbestfriend)\n- **Issues**: [github.com/TheRealFloatDev/AgentsBestFriend/issues](https://github.com/TheRealFloatDev/AgentsBestFriend/issues)\n- **MCP Spec**: [modelcontextprotocol.io](https://modelcontextprotocol.io)\n\n## License\n\nMIT\n",
  "bytes": 8035,
  "sha": "747440954560451ebe3634371ffcf2895259e3515e7d5f5538a0946ec1dcf050",
  "repo_slug": "therealfloatdev/agentsbestfriend",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_therealfloatdev_agentsbestfrie_0d1df85d/readme"
}