Context compaction for AI code assistants – Give your AI structured, token-efficient access to 17+ languages including Elixir, Python, TypeScript, JavaScript, Rust, and more. Quick Install · Security · Developers · AI Assistants · Docs The core problem: AI code assistants waste context on blind searches. Grep dumps entire files when you only need a function signature, leaving less room for actual
Add this skill
npx mdskills install wende/cicadaComprehensive MCP server delivering AST-level code intelligence across 17+ languages with semantic search and git attribution
1<div align="center">2<img src="https://github.com/user-attachments/assets/699c0a3f-dfae-4e14-81db-c8ba970d9a35">34# CICADA56### **C**ode **I**ntelligence: **C**ontextual **A**nalysis, **D**iscovery, and **A**ttribution78**Context compaction for AI code assistants** – Give your AI structured, token-efficient access to 17+ languages including Elixir, Python, TypeScript, JavaScript, Rust, and more.910> [**Up to 50% less waiting · Up to 70% less tokens · Up to 99% less explanations to do**](https://cicada-mcp.vercel.app/#benchmark-section)11> **Tighter context = Better Quality**1213[](https://www.python.org/downloads/)14[](https://opensource.org/licenses/MIT)15[](https://codecov.io/gh/wende/cicada)16[](https://modelcontextprotocol.io)1718[](https://elixir-lang.org/)19[](https://www.python.org/)20[](https://www.typescriptlang.org/)21[](https://www.javascript.com/)22[](https://www.rust-lang.org/)23[](#)2425[](https://cursor.com/en-US/install-mcp?name=cicada&config=eyJjb21tYW5kIjoidXZ4IGNpY2FkYS1tY3AgLiJ9)2627[Quick Install](#quick-install) · [Security](#privacy--security) · [Developers](#for-developers) · [AI Assistants](#for-ai-assistants) · [Docs](#documentation)2829</div>3031---3233## Why CICADA?3435**The core problem:** AI code assistants [waste context on blind searches](https://www.youtube.com/live/xmbSQz-PNMM?t=2402). Grep dumps entire files when you only need a function signature, leaving less room for actual reasoning.3637### The Context Compaction Approach3839Instead of raw text dumps, CICADA gives your AI **structured, pre-indexed knowledge**:4041| Traditional Search | CICADA |42|-------------------|--------|43| Grep dumps entire files | Returns only signatures + call sites |44| Misses aliased imports | Tracks all reference types |45| No semantic understanding | Keyword search finds `verify_credentials` when you ask for "authentication" |464748### What You Get4950- **AST-level indexing** – Module/function/class definitions with signatures, specs, docs51- **17+ language support** – Elixir, Python, TypeScript, JavaScript, Rust, Go, Java, Kotlin, Scala, C/C++, Ruby, C#, Visual Basic, Dart, PHP, Erlang (beta)52- **Complete call-site tracking** – Aliases, imports, dynamic references across all supported languages53- **Semantic search** – Find code by concept with keyword extraction or embeddings (Ollama integration)54- **Git + PR attribution** – Surface *why* code exists, not just what55- **Dependency analysis** – Bidirectional tracking (what calls this, what does this call)56- **Automatic language detection** – Works seamlessly across polyglot codebases5758---5960## Install6162```bash63# 1. Install uv (if needed)64# curl -LsSf https://astral.sh/uv/install.sh | sh65uv tool install cicada-mcp6667# In your repo68cicada claude # or: cicada cursor, cicada vs, cicada gemini, cicada codex, cicada opencode, cicada zed69```7071<div align="left">72<summary><strong>Try before installing permanently</strong></summary>73Runs CICADA on demand (worse indexing quality, but zero install).7475```bash76uvx cicada-mcp claude # or cursor, vs77```78or7980```81claude mcp add cicada uvx cicada-mcp82```83```84gemini mcp add cicada uvx cicada-mcp85```86```87codex mcp add cicada uvx cicada-mcp88```89```90kimi mcp add --transport stdio cicada -- cicada-mcp91```929394Uses your editor's built-in MCP management to install CICADA.9596</details>97</div>9899**Available commands after installation:**100- `cicada [claude|cursor|vs|gemini|codex|opencode|zed]` - One-command interactive setup per project101- `cicada-mcp` - MCP server (auto-started by editor)102- `cicada serve` - Start REST API server for HTTP access to all MCP tools103- `cicada status` - Show index status, PR index, link status, agent files, MCP configs104- `cicada stats [repo]` - Display usage statistics (tool calls, tokens, execution times)105- `cicada watch` - Watch for file changes and automatically reindex106- `cicada index` - Re-index code with custom options (`-f/--force`, `--keywords`, `--embeddings`, `--watch`)107- `cicada index-pr` - Index pull requests for PR attribution108- `cicada run [tool]` - Execute any of the 7 MCP tools directly from CLI109- `cicada agents install` - Install Claude Code agents to `./.claude/` directory110- `cicada link [parent_dir]` - Links current repository to an existing index111- `cicada clean` - Completely removes cicada integration from your folder as well as all settings112113Ask your assistant:114```115# Elixir116"Show me the functions in MyApp.User"117"Where is authenticate/2 called?"118119# Python120"Show me the AuthService class methods"121"Where is login() used in the codebase?"122123# Both languages124"Find code related to API authentication"125```126127---128129## Privacy & Security130131- **100% local:** parsing + indexing happen on your machine; no external access.132- **No telemetry:** CICADA doesn't collect usage or any telemetry.133- **Read-only tools:** MCP endpoints only read the index; they can't change your repo.134- **Optional GitHub access:** PR features rely on `gh` and your existing OAuth token.135- **Data layout:**136 ```137 ~/.cicada/projects/<repo_hash>/138 ├─ index.json # modules, functions, call sites, metadata139 ├─ config.yaml # indexing options + mode140 ├─ hashes.json # incremental indexing cache141 └─ pr_index.json # optional PR metadata + reviews142 ```143 Your repo only gains an editor config (`.mcp.json`, `.cursor/mcp.json`, `.vscode/settings.json`, `.gemini/settings.json`, `.codex/mcp.json`, or `.opencode.json`).144145---146147## For Developers148149> Wire CICADA into your editor once, and every assistant session inherits the context.150151### Install & Configure152153```bash154cd /path/to/project155cicada claude # or cicada cursor / cicada vs / cicada gemini / cicada codex / cicada opencode / cicada zed156```157158### Enable PR Attribution (optional)159160```bash161brew install gh # or apt install gh162gh auth login163cicada index-pr . # incremental164cicada index-pr . --clean # full rebuild165```166167Unlocks questions like "Which PR introduced line 42?" or "What did reviewers say about `billing.ex`?"168169### Automatic Re-indexing with Watch Mode170171Enable automatic reindexing when files change by starting the MCP server with the `--watch` flag:172173** .mcp.json**174```json175{176 "mcpServers": {177 "cicada": {178 "command": "cicada-mcp",179 "args": ["--watch"],180 "env": {181 "CICADA_CONFIG_DIR": "/home/user/.cicada/projects/<hash>"182 }183 }184 }185}186```187When watch mode is enabled:188- A separate process monitors `.ex`, `.exs` (Elixir) and `.py` (Python) files for changes189- Changes are automatically reindexed (incremental, fast)190- 2-second debounce prevents excessive reindexing during rapid edits191- The watch process stops automatically when the MCP server stops192- Excluded directories: `deps`, `_build`, `node_modules`, `.git`, `assets`, `priv`, `.venv`, `venv`193194### CLI Cheat Sheet195196**Note:** Language detection is automatic – CICADA detects Elixir (mix.exs) and Python (pyproject.toml) projects automatically.197198| Command | Purpose | Run When |199|---------|---------|---------|200| `cicada claude` | Configure MCP + incremental re-index | First setup, after local changes |201| `cicada status` | Check index health, link status, agent files | After setup, troubleshooting |202| `cicada stats` | View usage statistics and token metrics | Monthly reviews, optimization |203| `cicada watch` | Monitor files and auto-reindex on changes | During active development |204| `cicada index --keywords .` | Rebuild with keyword indexing | After large refactors or enabling keywords mode |205| `cicada index --embeddings .` | Rebuild with embeddings (semantic search) | When you want Ollama-powered semantic analysis |206| `cicada index-pr .` | Sync PR metadata/reviews | After new PRs merge |207208### Troubleshooting209210<details>211<summary><b>"Index file not found"</b></summary>212213Run the indexer first:214```bash215cicada index /path/to/project216```217218Ensure indexing completed successfully. Check for `~/.cicada/projects/<hash>/index.json`.219220</details>221222<details>223<summary><b>"Module not found"</b></summary>224225Use the exact module name as it appears in code (e.g., `MyApp.User`, not `User`).226227If module was recently added, re-index:228```bash229cicada index .230```231232</details>233234<details>235<summary><b>MCP Server Won't Connect</b></summary>236237**Troubleshooting checklist:**2382391. **Verify configuration file exists:**240 ```bash241 # For Claude Code242 ls -la .mcp.json243244 # For Cursor245 ls -la .cursor/mcp.json246247 # For VS Code248 ls -la .vscode/settings.json249 ```2502512. **Check paths are absolute:**252 ```bash253 cat .mcp.json254 # Should contain: /absolute/path/to/project255 # Not: ./project or ../project256 ```2572583. **Ensure index exists:**259 ```bash260 ls -la ~/.cicada/projects/261 # Should show directory for your project262 ```2632644. **Restart editor completely** (not just reload window)2652665. **Check editor MCP logs:**267 - Claude Code: --debug268 - Cursor: Settings → MCP → View Logs269 - VS Code: Output panel → MCP270271</details>272273<details>274<summary><b>PR Features Not Working</b></summary>275276**Setup GitHub CLI:**277```bash278# Install GitHub CLI279brew install gh # macOS280sudo apt install gh # Ubuntu281# or visit https://cli.github.com/282283# Authenticate284gh auth login285286# Index PRs287cicada index-pr288```289290**Common issues:**291- "No PR index found" → Run `cicada index-pr .`292- "Not a GitHub repository" → Ensure repo has GitHub remote293- Slow indexing → First-time indexing fetches all PRs; subsequent runs are incremental294- Rate limiting → GitHub API has rate limits; wait and retry if you hit limits295296**Force rebuild:**297```bash298cicada index-pr --clean299```300301</details>302303<details>304<summary><b>Keyword Search Not Working</b></summary>305306**Error:** "Keyword search not available"307308**Cause:** Index was built without keyword extraction.309310**Solution:**311```bash312# Re-index with keyword extraction313cicada index . # or --keywords314```315316**Verify:**317```bash318cat ~/.cicada/projects/<hash>/config.yaml319# Should show:320# indexing:321# mode: keywords322```323324</details>325326More detail: [PR Indexing](codebook/tasks/202511192143-PR_INDEXING.md), [Incremental Indexing](codebook/tasks/202512251907-INCREMENTAL_INDEXING.md).327328<details>329<summary><b>Python Indexing</b></summary>330331**Requirements:**332- Node.js (for scip-python indexer)333- Python project with pyproject.toml334335**First-time setup:**336CICADA automatically installs scip-python via npm on first index. This may take a minute.337338**Known limitations (Beta):**339- First indexing may be slower than Elixir (SCIP generation step)340- Large virtual environments (.venv) are automatically excluded341- Some dynamic Python patterns may not be captured342343**Performance tips:**344```bash345# Ensure .venv is excluded346echo "/.venv/" >> .gitignore347348# Use keywords mode for quickest indexing349cicada index --keywords .350```351352**Report issues:** [GitHub Issues](https://github.com/wende/cicada/issues) with "Python" label353354</details>355356---357358## For AI Assistants359360CICADA ships 7 focused MCP tools designed for efficient code exploration across Elixir, Python, and Erlang codebases.361362### 🧭 Which Tool Should You Use?363364| Need | Tool | Notes |365|------|------|-------|366| **Start exploring** | `query` | **🚀 START HERE** - Smart discovery with keywords/patterns + filters (scope, recent, path) |367| View a module's complete API | `search_module` | Functions, signatures, specs, docs. Use `what_calls_it`/`what_it_calls` for bidirectional analysis |368| Find where a function is used | `search_function` | Definition + all call sites. Supports wildcards (`*`) and OR (`\|`) patterns |369| Track git history | `git_history` | Unified tool: blame, commits, PRs, function evolution (replaces 4 legacy tools) |370| Drill down into results | `expand_result` | Auto-expands modules or functions from query results |371| Advanced index queries | `query_jq` | Custom jq queries for power users |372373**Want to see these tools in action?** Check out [Complete Workflow Examples](codebook/WORKFLOWS.md) with pro tips and real-world scenarios.374375### Core Tools376377**`query`** - Smart code discovery (your starting point)378- Automatically detects keywords vs patterns379- Filters: `scope` (public/private), `recent` (last 14 days), `filter_type` (modules/functions), `match_source` (docs/strings)380- Returns snippets with smart next-step suggestions381- Use `path_pattern` to filter by location382383**`search_module`** - Deep module analysis384- View complete API: functions, signatures, specs, docs385- For Python: Shows classes with method counts and signatures386- For Elixir: Shows functions with arity notation387- Bidirectional analysis:388 - `what_calls_it=true` → See who uses this module (impact analysis)389 - `what_it_calls=true` → See what this module depends on390- Supports wildcards (Elixir: `MyApp.*`, Python: `api.handlers.*`) and OR patterns (`MyApp.User|MyApp.Post`)391- Filter by visibility (public/private/all)392393**`search_function`** - Function usage tracking394- Find definitions and all call sites395- `what_calls_it=true` (default) → See all callers396- `what_it_calls=true` → See all dependencies397- Include code examples with `include_usage_examples=true`398- Filter by `usage_type`: source, tests, or all399400### Git History (Unified Tool)401402**`git_history`** - All git operations in one tool403- **Single line**: `git_history("file.ex", start_line=42)` → blame + PR404- **Line range**: `git_history("file.ex", start_line=40, end_line=60)` → grouped blame405- **Function tracking**: `git_history("file.ex", function_name="create_user")` → evolution406- **File history**: `git_history("file.ex")` → all PRs/commits407- Time filtering: `recent=true` (14d), `recent=false` (>14d), `recent=null` (all)408- Author filtering: `author="john"`409- Automatic PR index integration when available410411### Additional Tools412413**`expand_result`** - Drill down from query results414- Auto-detects module vs function415- Shows complete details with usage examples416- Configure what to include: code, dependencies, callers417- Convenient wrapper around search_module and search_function418419**`query_jq`** - Advanced index queries420- Direct jq queries against the index421- Schema discovery with `| schema`422- Compact (default) or pretty output423- Sample mode for large results424425Detailed parameters + output formats: [MCP_TOOLS_REFERENCE.md](MCP_TOOLS_REFERENCE.md).426427### Token-Friendly Responses428429All tools return structured Markdown/JSON snippets (signatures, call sites, PR metadata) instead of full files, keeping prompts lean.430431**New in v0.5.1:** All tools now use compact output by default to minimize token usage. Use `verbose=true` for detailed output with full docs and specs.432433---434435436---437438## Documentation439440- **[Codebook](codebook/README.md)** – Complete feature reference and user guides441- **[Workflows](codebook/WORKFLOWS.md)** – Real-world examples chaining tools together442- **[Installation](codebook/INSTALLATION.md)** – Step-by-step setup for all editors443- **[Contributing](CONTRIBUTING.md)** – Development guidelines and architecture444- [CHANGELOG.md](CHANGELOG.md) – Release notes445446**Deep Dives:**447- [Keyword Extraction Analysis](codebook/RandD/202511052055-KEYWORD_EXTRACTION_ANALYSIS.md) – Semantic search internals448- [PR Indexing](codebook/tasks/202511192143-PR_INDEXING.md) – GitHub integration details449- [MCP Tool Call Benchmarking](codebook/RandD/202511052055-MCP_TOOL_CALL_BENCHMARKING.md) – Token/time benchmarks450- [Tool Discoverability](codebook/RandD/202512242110-TOOL_DISCOVERABILITY_TASKS.md) – UX improvements research451452---453454## Roadmap455456### Current Status457458**Production Ready:**459- ✅ Elixir (tree-sitter)460- ✅ Python (SCIP)461- ✅ TypeScript (SCIP)462- ✅ JavaScript (SCIP)463- ✅ Rust (SCIP)464465466**Beta:**467- 🚧 Erlang (tree-sitter)468- 🚧 Go (SCIP)469- 🚧 Java/Kotlin/Scala (SCIP)470- 🚧 C/C++ (SCIP)471- 🚧 Ruby (SCIP)472- 🚧 C#/Visual Basic (SCIP)473- 🚧 Dart (SCIP)474- 🚧 PHP (SCIP)475476---477478## Comparison to Alternatives479480| Feature | CICADA | [Serena](https://github.com/oraios/serena) | [Codicil](https://github.com/E-xyza/codicil) (Elixir-only) |481|---------|--------|--------|---------|482| **Analysis Method** | SCIP (static index) | LSP (real-time server) | LLM summaries + embeddings |483| **Code Editing** | ❌ | ✅ | ❌ |484| **Git Context** | ✅ PR history, blame, evolution | ❌ | ❌ |485| **Resource Usage** | Low (read from disk) | High (persistent server processes) | Medium (API calls) |486| **Privacy** | 100% local | 100% local | Requires external LLM APIs |487| **Semantic Search** | Local Ollama or keywords | ❌ | OpenAI/Anthropic embeddings |488| **Call Graph** | Bidirectional with alias resolution | LSP-based | ❌ |489490**When to choose CICADA:** You want local-first operation with rich git context (PR attribution, blame, function evolution tracking) and efficient token usage.491492**When to choose Serena:** You need code editing capabilities through LSP and can accept higher resource usage.493494**When to choose Codicil:** You have an Elixir project and prefer LLM-powered semantic summaries (Elixir-only).495496---497498## Contributing499500```bash501git clone https://github.com/wende/cicada.git502cd cicada503uv sync504pytest505```506507Before submitting a PR:508- Run `black cicada tests`509- Ensure tests + coverage pass (`pytest --cov=cicada --cov-report=term-missing`)510- Update docs if behaviour changes511512We welcome issues/PRs for:513- New language grammars514- Tool output improvements515- Better onboarding docs and tutorials516517---518519## License520521MIT – see [LICENSE](LICENSE).522523<div align="center">524525**Stop wasting context on blind searches. Give your AI CICADA.**526527[Get Started](#quick-install) · [Report Issues](https://github.com/wende/cicada/issues)528529</div>530
Full transparency — inspect the skill content before installing.