cicada

<div align="center"> <img src="https://github.com/user-attachments/assets/699c0a3f-dfae-4e14-81db-c8ba970d9a35">

CICADA

mcp-name: io.github.wende/cicada

Code Intelligence: Contextual Analysis, Discovery, and Attribution

Context compaction for AI code assistants – Give your AI structured, token-efficient access to 17+ languages including Elixir, Python, TypeScript, JavaScript, Rust, and more.

Up to 50% less waiting · Up to 70% less tokens · Up to 99% less explanations to do Tighter context = Better Quality

   

     


Quick Install · Security · Developers · AI Assistants · Docs

</div>

---

Why CICADA?

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 reasoning.

The Context Compaction Approach

Instead of raw text dumps, CICADA gives your AI structured, pre-indexed knowledge:

| Traditional Search | CICADA | |-------------------|--------| | Grep dumps entire files | Returns only signatures + call sites | | Misses aliased imports | Tracks all reference types | | No semantic understanding | Keyword search finds verify_credentials when you ask for "authentication" |

What You Get

• AST-level indexing – Module/function/class definitions with signatures, specs, docs
• 17+ language support – Elixir, Python, TypeScript, JavaScript, Rust, Go, Java, Kotlin, Scala, C/C++, Ruby, C#, Visual Basic, Dart, PHP, Erlang (beta)
• Complete call-site tracking – Aliases, imports, dynamic references across all supported languages
• Semantic search – Find code by concept with keyword extraction or embeddings (Ollama integration)
• Git + PR attribution – Surface why code exists, not just what
• Dependency analysis – Bidirectional tracking (what calls this, what does this call)
• Automatic language detection – Works seamlessly across polyglot codebases

---

Install

# 1. Install uv (if needed)
# curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install cicada-mcp

# In your repo
cicada claude   # or: cicada cursor, cicada vs, cicada gemini, cicada codex, cicada opencode, cicada zed

<div align="left"> <summary><strong>Try before installing permanently</strong></summary> Runs CICADA on demand (worse indexing quality, but zero install).

uvx cicada-mcp claude   # or cursor, vs

or

claude mcp add cicada uvx cicada-mcp

gemini mcp add cicada uvx cicada-mcp

codex mcp add cicada uvx cicada-mcp

kimi mcp add --transport stdio cicada -- cicada-mcp

Uses your editor's built-in MCP management to install CICADA.

</details> </div>

Available commands after installation:

• cicada [claude|cursor|vs|gemini|codex|opencode|zed] - One-command interactive setup per project
• cicada-mcp - MCP server (auto-started by editor)
• cicada serve - Start REST API server for HTTP access to all MCP tools
• cicada status - Show index status, PR index, link status, agent files, MCP configs
• cicada stats [repo] - Display usage statistics (tool calls, tokens, execution times)
• cicada watch - Watch for file changes and automatically reindex
• cicada index - Re-index code with custom options (-f/--force, --keywords, --embeddings, --watch)
• cicada index-pr - Index pull requests for PR attribution
• cicada run [tool] - Execute any of the 7 MCP tools directly from CLI
• cicada agents install - Install Claude Code agents to ./.claude/ directory
• cicada link [parent_dir] - Links current repository to an existing index
• cicada clean - Completely removes cicada integration from your folder as well as all settings

Ask your assistant: ```

Elixir

"Show me the functions in MyApp.User" "Where is authenticate/2 called?"

Python

"Show me the AuthService class methods" "Where is login() used in the codebase?"

Both languages

"Find code related to API authentication" ```

---

Privacy & Security

• 100% local: parsing + indexing happen on your machine; no external access.
• No telemetry: CICADA doesn't collect usage or any telemetry.
• Read-only tools: MCP endpoints only read the index; they can't change your repo.
• Optional GitHub access: PR features rely on gh and your existing OAuth token.
• Data layout:

  ~/.cicada/projects/<repo_hash>/
  ├─ index.json      # modules, functions, call sites, metadata
  ├─ config.yaml     # indexing options + mode
  ├─ hashes.json     # incremental indexing cache
  └─ pr_index.json   # optional PR metadata + reviews

Your repo only gains an editor config (.mcp.json, .cursor/mcp.json, .vscode/settings.json, .gemini/settings.json, .codex/mcp.json, or .opencode.json).

---

For Developers

Wire CICADA into your editor once, and every assistant session inherits the context.

Install & Configure

cd /path/to/project
cicada claude   # or cicada cursor / cicada vs / cicada gemini / cicada codex / cicada opencode / cicada zed

Enable PR Attribution (optional)

brew install gh    # or apt install gh
gh auth login
cicada index-pr .     # incremental
cicada index-pr . --clean   # full rebuild

Unlocks questions like "Which PR introduced line 42?" or "What did reviewers say about billing.ex?"

Automatic Re-indexing with Watch Mode

Enable automatic reindexing when files change by starting the MCP server with the --watch flag:

.mcp.json ``json { "mcpServers": { "cicada": { "command": "cicada-mcp", "args": ["--watch"], "env": { "CICADA_CONFIG_DIR": "/home/user/.cicada/projects/<hash>" } } } } `` When watch mode is enabled:

• A separate process monitors .ex, .exs (Elixir) and .py (Python) files for changes
• Changes are automatically reindexed (incremental, fast)
• 2-second debounce prevents excessive reindexing during rapid edits
• The watch process stops automatically when the MCP server stops
• Excluded directories: deps, _build, node_modules, .git, assets, priv, .venv, venv

CLI Cheat Sheet

Note: Language detection is automatic – CICADA detects Elixir (mix.exs) and Python (pyproject.toml) projects automatically.

| Command | Purpose | Run When | |---------|---------|---------| | cicada claude | Configure MCP + incremental re-index | First setup, after local changes | | cicada status | Check index health, link status, agent files | After setup, troubleshooting | | cicada stats | View usage statistics and token metrics | Monthly reviews, optimization | | cicada watch | Monitor files and auto-reindex on changes | During active development | | cicada index --keywords . | Rebuild with keyword indexing | After large refactors or enabling keywords mode | | cicada index --embeddings . | Rebuild with embeddings (semantic search) | When you want Ollama-powered semantic analysis | | cicada index-pr . | Sync PR metadata/reviews | After new PRs merge |

Troubleshooting

<details> <summary><b>"Index file not found"</b></summary>

Run the indexer first: ``bash cicada index /path/to/project ``

Ensure indexing completed successfully. Check for ~/.cicada/projects/<hash>/index.json.

</details>

<details> <summary><b>"Module not found"</b></summary>

Use the exact module name as it appears in code (e.g., MyApp.User, not User).

If module was recently added, re-index: ``bash cicada index . ``

</details>

<details> <summary><b>MCP Server Won't Connect</b></summary>

Troubleshooting checklist:

1. Verify configuration file exists:

   # For Claude Code
   ls -la .mcp.json

   # For Cursor
   ls -la .cursor/mcp.json

   # For VS Code
   ls -la .vscode/settings.json

1. Check paths are absolute:

   cat .mcp.json
   # Should contain: /absolute/path/to/project
   # Not: ./project or ../project

1. Ensure index exists:

   ls -la ~/.cicada/projects/
   # Should show directory for your project

1. Restart editor completely (not just reload window)

1. Check editor MCP logs:

• Claude Code: --debug
• Cursor: Settings → MCP → View Logs
• VS Code: Output panel → MCP

</details>

<details> <summary><b>PR Features Not Working</b></summary>

Setup GitHub CLI: ```bash

Install GitHub CLI

brew install gh # macOS sudo apt install gh # Ubuntu

or visit https://cli.github.com/

Authenticate

gh auth login

Index PRs

cicada index-pr ```

Common issues:

• "No PR index found" → Run cicada index-pr .
• "Not a GitHub repository" → Ensure repo has GitHub remote
• Slow indexing → First-time indexing fetches all PRs; subsequent runs are incremental
• Rate limiting → GitHub API has rate limits; wait and retry if you hit limits

Force rebuild: ``bash cicada index-pr --clean ``

</details>

<details> <summary><b>Keyword Search Not Working</b></summary>

Error: "Keyword search not available"

Cause: Index was built without keyword extraction.

Solution: ```bash

Re-index with keyword extraction

cicada index . # or --keywords ```

Verify: ```bash cat ~/.cicada/projects/<hash>/config.yaml

Should show:

indexing:

mode: keywords

</details>

More detail: [PR Indexing](codebook/tasks/202511192143-PR_INDEXING.md), [Incremental Indexing](codebook/tasks/202512251907-INCREMENTAL_INDEXING.md).

<details>
<summary><b>Python Indexing</b></summary>

**Requirements:**
- Node.js (for scip-python indexer)
- Python project with pyproject.toml

**First-time setup:**
CICADA automatically installs scip-python via npm on first index. This may take a minute.

**Known limitations (Beta):**
- First indexing may be slower than Elixir (SCIP generation step)
- Large virtual environments (.venv) are automatically excluded
- Some dynamic Python patterns may not be captured

**Performance tips:**

Ensure .venv is excluded

echo "/.venv/" >> .gitignore

Use keywords mode for quickest indexing

cicada index --keywords . ```

Report issues: GitHub Issues with "Python" label

</details>

---

For AI Assistants

CICADA ships 7 focused MCP tools designed for efficient code exploration across Elixir, Python, and Erlang codebases.

🧭 Which Tool Should You Use?

| Need | Tool | Notes | |------|------|-------| | Start exploring | query | 🚀 START HERE - Smart discovery with keywords/patterns + filters (scope, recent, path) | | View a module's complete API | search_module | Functions, signatures, specs, docs. Use what_calls_it/what_it_calls for bidirectional analysis | | Find where a function is used | search_function | Definition + all call sites. Supports wildcards (*) and OR (\|) patterns | | Track git history | git_history | Unified tool: blame, commits, PRs, function evolution (replaces 4 legacy tools) | | Drill down into results | expand_result | Auto-expands modules or functions from query results | | Advanced index queries | query_jq | Custom jq queries for power users |

Want to see these tools in action? Check out Complete Workflow Examples with pro tips and real-world scenarios.

Core Tools

query - Smart code discovery (your starting point)

• Automatically detects keywords vs patterns
• Filters: scope (public/private), recent (last 14 days), filter_type (modules/functions), match_source (docs/strings)
• Returns snippets with smart next-step suggestions
• Use path_pattern to filter by location

search_module - Deep module analysis

• View complete API: functions, signatures, specs, docs
• For Python: Shows classes with method counts and signatures
• For Elixir: Shows functions with arity notation
• Bidirectional analysis:
• what_calls_it=true → See who uses this module (impact analysis)
• what_it_calls=true → See what this module depends on
• Supports wildcards (Elixir: MyApp., Python: api.handlers.) and OR patterns (MyApp.User|MyApp.Post)
• Filter by visibility (public/private/all)

search_function - Function usage tracking

• Find definitions and all call sites
• what_calls_it=true (default) → See all callers
• what_it_calls=true → See all dependencies
• Include code examples with include_usage_examples=true
• Filter by usage_type: source, tests, or all

Git History (Unified Tool)

git_history - All git operations in one tool

• Single line: git_history("file.ex", start_line=42) → blame + PR
• Line range: git_history("file.ex", start_line=40, end_line=60) → grouped blame
• Function tracking: git_history("file.ex", function_name="create_user") → evolution
• File history: git_history("file.ex") → all PRs/commits
• Time filtering: recent=true (14d), recent=false (>14d), recent=null (all)
• Author filtering: author="john"
• Automatic PR index integration when available

Additional Tools

expand_result - Drill down from query results

• Auto-detects module vs function
• Shows complete details with usage examples
• Configure what to include: code, dependencies, callers
• Convenient wrapper around search_module and search_function

query_jq - Advanced index queries

• Direct jq queries against the index
• Schema discovery with | schema
• Compact (default) or pretty output
• Sample mode for large results

Detailed parameters + output formats: MCP_TOOLS_REFERENCE.md.

Token-Friendly Responses

All tools return structured Markdown/JSON snippets (signatures, call sites, PR metadata) instead of full files, keeping prompts lean.

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.

---

---

Documentation

• Codebook – Complete feature reference and user guides
• Workflows – Real-world examples chaining tools together
• Installation – Step-by-step setup for all editors
• Contributing – Development guidelines and architecture
• CHANGELOG.md – Release notes

Deep Dives:

• Keyword Extraction Analysis – Semantic search internals
• PR Indexing – GitHub integration details
• MCP Tool Call Benchmarking – Token/time benchmarks
• Tool Discoverability – UX improvements research

---

Roadmap

Current Status

Production Ready:

• ✅ Elixir (tree-sitter)
• ✅ Python (SCIP)
• ✅ TypeScript (SCIP)
• ✅ JavaScript (SCIP)
• ✅ Rust (SCIP)

Beta:

• 🚧 Erlang (tree-sitter)
• 🚧 Go (SCIP)
• 🚧 Java/Kotlin/Scala (SCIP)
• 🚧 C/C++ (SCIP)
• 🚧 Ruby (SCIP)
• 🚧 C#/Visual Basic (SCIP)
• 🚧 Dart (SCIP)
• 🚧 PHP (SCIP)

---

Comparison to Alternatives

| Feature | CICADA | Serena | Codicil (Elixir-only) | |---------|--------|--------|---------| | Analysis Method | SCIP (static index) | LSP (real-time server) | LLM summaries + embeddings | | Code Editing | ❌ | ✅ | ❌ | | Git Context | ✅ PR history, blame, evolution | ❌ | ❌ | | Resource Usage | Low (read from disk) | High (persistent server processes) | Medium (API calls) | | Privacy | 100% local | 100% local | Requires external LLM APIs | | Semantic Search | Local Ollama or keywords | ❌ | OpenAI/Anthropic embeddings | | Call Graph | Bidirectional with alias resolution | LSP-based | ❌ |

When to choose CICADA: You want local-first operation with rich git context (PR attribution, blame, function evolution tracking) and efficient token usage.

When to choose Serena: You need code editing capabilities through LSP and can accept higher resource usage.

When to choose Codicil: You have an Elixir project and prefer LLM-powered semantic summaries (Elixir-only).

---

Contributing

git clone https://github.com/wende/cicada.git
cd cicada
uv sync
pytest

Before submitting a PR:

• Run black cicada tests
• Ensure tests + coverage pass (pytest --cov=cicada --cov-report=term-missing)
• Update docs if behaviour changes

We welcome issues/PRs for:

• New language grammars
• Tool output improvements
• Better onboarding docs and tutorials

---

License

MIT – see LICENSE.

<div align="center">

Stop wasting context on blind searches. Give your AI CICADA.

Get Started · Report Issues

</div>