diff --git a/COMPARISON.md b/COMPARISON.md index ffc3f77..4a7f29d 100644 --- a/COMPARISON.md +++ b/COMPARISON.md @@ -1,4 +1,4 @@ -# AI Codebase Context Tools — Comparison +# AI Codebase Context Tools - Comparison > How do you give AI agents codebase context? Here's every approach compared. > @@ -6,7 +6,7 @@ ## The Problem -AI coding agents (Claude Code, Cursor, Copilot, Aider) need to understand your codebase before they can help. Without context, they waste thousands of tokens exploring — reading files, grepping, globbing — just to figure out your project structure. +AI coding agents (Claude Code, Cursor, Copilot, Aider) need to understand your codebase before they can help. Without context, they waste thousands of tokens exploring - reading files, grepping, globbing - just to figure out your project structure. Different tools solve this differently. Some dump everything. Some build knowledge graphs. Some generate compressed maps. Here's how they compare. @@ -34,7 +34,7 @@ Different tools solve this differently. Some dump everything. Some build knowled Concatenate all source files into one big prompt. Simple, works everywhere, but: - Burns 50k-500k tokens on medium repos - Often exceeds context windows entirely -- No structural intelligence — agent still has to parse everything +- No structural intelligence - agent still has to parse everything - Repomix's `--compress` mode uses tree-sitter to reduce output, but remains per-file (no cross-file dependency analysis) Best for: Small repos (<5k lines), one-shot conversations, pasting into ChatGPT. @@ -46,7 +46,7 @@ Build a queryable graph of your codebase, served over MCP: - Rich structural data (call graphs, blast radius, community detection) - Requires running a server process - Each query costs tokens (tool call overhead) -- No committable artifact — the knowledge lives in the server +- No committable artifact - the knowledge lives in the server Best for: Large codebases, long interactive sessions, teams with infra capacity. @@ -54,7 +54,7 @@ Best for: Large codebases, long interactive sessions, teams with infra capacity. Parses code with tree-sitter, builds a module-level dependency graph, outputs a compact navigation map: - **~250 tokens** for the compact map (vs 50k-500k for dumpers) -- Static artifact — commit `stacklit.json` to your repo +- Static artifact - commit `stacklit.json` to your repo - Self-contained HTML visualization - Auto-configures Claude Code, Cursor, Aider via `stacklit setup` - Git hook keeps the index fresh @@ -124,7 +124,7 @@ Repomix counts estimated from file sizes. Stacklit counts measured directly. ## Install ```bash -# npm (easiest — downloads the right binary automatically) +# npm (easiest - downloads the right binary automatically) npm i -g stacklit # From source diff --git a/README.md b/README.md index 6241428..325cc2d 100644 --- a/README.md +++ b/README.md @@ -151,13 +151,13 @@ modules:
Configure manually instead -**Claude Code** — add to `CLAUDE.md`: +**Claude Code** - add to `CLAUDE.md`: ``` Read stacklit.json before exploring files. Use modules to locate code, hints for conventions. ``` -**Claude Desktop / Cursor (MCP)** — add to MCP config: +**Claude Desktop / Cursor (MCP)** - add to MCP config: ```json { @@ -172,7 +172,7 @@ Read stacklit.json before exploring files. Use modules to locate code, hints for MCP server exposes 7 tools: `get_overview`, `get_module`, `find_module`, `list_modules`, `get_dependencies`, `get_hot_files`, `get_hints`. -**Any other agent** — `stacklit.json` is a plain JSON file. Any tool that reads files can use it. +**Any other agent** - `stacklit.json` is a plain JSON file. Any tool that reads files can use it.
@@ -292,19 +292,6 @@ html = "stacklit.html" [Full comparison with 7 tools →](https://github.com/glincker/stacklit/discussions/13) -## Compared to alternatives - -| | Stacklit | Repomix | Aider repo-map | Codebase Memory MCP | -|---|---|---|---|---| -| Output | ~4k token index | 500k+ token dump | Ephemeral text | SQLite DB | -| Committed to repo | Yes | Too large | No | No | -| Dependency graph | Yes | No | Yes | Yes | -| Visual output | HTML (4 views) | No | No | No | -| MCP server | Yes (7 tools) | No | No | Yes | -| Monorepo aware | Yes | No | No | No | -| Languages | 11 (tree-sitter) | N/A | Many | 66 | -| Runtime needed | No | No | Yes (Python) | Yes (C server) | - ## Monorepo support Auto-detects: pnpm, npm, yarn workspaces, Go workspaces, Turborepo, Nx, Lerna, Cargo workspaces, and convention directories (`apps/`, `packages/`, `services/`).