CICADA

CICADA

[!WARNING]

⚠️ Disclaimer — Today's AI agents operate completely differently from when this project was conceived. In current benchmarks, using a code intelligence tool yields little to no advantage for frontier models. CICADA is discontinued, and I'd advise against using it or any other "code intelligence" tool.

---

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

---

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:

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

Try before installing permanently 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.

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

{

"mcpServers": { "cicada": { "command": "cicada-mcp", "args": ["--watch"], "env": { "CICADA_CONFIG_DIR": "/home/user/.cicada/projects/ " } } } }

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.

Troubleshooting

"Index file not found"

Run the indexer first:

cicada index /path/to/project

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

"Module not found"

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

If module was recently added, re-index:

cicada index .

MCP Server Won't Connect

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

PR Features Not Working

Setup GitHub CLI:

# 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:

cicada index-pr --clean

Keyword Search Not Working

Error: "Keyword search not available"

Cause: Index was built without keyword extraction.

Solution:

# Re-index with keyword extraction

cicada index . # or --keywords

Verify:

cat ~/.cicada/projects/<hash>/config.yaml

Should show:

indexing:

mode: keywords

More detail: PR Indexing, Incremental Indexing.

Python Indexing

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

---

For AI Assistants

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