| name | compas |
| description | Codebase semantic search and symbol graph navigation. Use BEFORE opening any file you are not 100% certain about. Triggers on uncertainty: 'I need to find', 'where is', 'which file', 'I'm not sure where', 'let me check', 'I think it's in', 'probably in', 'looks like'. Enforces: query compas first, open only what compas confirms. |
MANDATORY RULE
For ANY task where you do not already know the exact file path and line number, your FIRST action MUST be search_codebase.
NEVER use list_dir, read_file, or regex search for initial exploration.
NEVER browse the directory tree to get oriented before searching.
NEVER assume you know where code lives because of file names or folder structure.
ALWAYS Pass the repo Parameter
This is the most common failure mode. ALWAYS include repo in every search_codebase and get_symbol_graph call.
The MCP server cannot reliably auto-detect which repo you are in because some editors spawn MCP from internal directories, not the workspace root.
If you forget repo, you get:
Error: missing 'repo' parameter and could not auto-detect from cwd.
Tool: search_codebase
Parameters:
- query (required): Natural language. Describe what you want, not regex.
Good: "user authentication with password hashing"
Bad: "class.*Auth" — compas is semantic, not regex
Bad: "getUserById" — use
get_symbol_graph for exact symbols
- repo (required): ALWAYS pass this.
- limit (optional): Default 10. Use 15-20 for exploration.
- language (optional): Filter by language, e.g. "dart".
After receiving results:
- Read the top 3-5 previews
- Pick the most relevant symbol by score and name
- Open ONLY that file
- Do NOT open files that did not appear in results
Tool: get_symbol_graph
Use AFTER finding a relevant symbol to trace its call chain.
Parameters:
- symbol (required): Symbol name, e.g. "AuthService.authenticate"
- file (optional): File path to disambiguate
- repo (required): ALWAYS pass this
Two-Step Workflow
Step 1 — Search:
search_codebase({ query: "how does X work", repo: "...", limit: 15 })
Step 2 — Deepen (optional):
get_symbol_graph({ symbol: "X", repo: "..." })
Step 3 — Read:
Open the most relevant file confirmed by both tools.
Pitfalls
| Pitfall | Fix |
|---|
| Forgetting repo parameter | ALWAYS pass repo in every call |
| Opening files based on assumptions | ALWAYS search compas first |
| Using exact symbol names in search_codebase | Use natural language; use get_symbol_graph for exact symbols |
| Skipping the graph | After finding a symbol, check get_symbol_graph for "how does it work?" |
Generated by compas init. Update or remove this file as needed.
