codebase-query

name	codebase-query
aliases	["cbm","code-graph"]
description	Query and analyze codebases semantically using codebase-memory-mcp graph database. Use to explore code structure, complexity, dependencies, call graphs, and architecture. Triggers: /codebase-query, /cbm, /code-graph, "show me high complexity functions", "what calls X", "find implementations of", "map service entry points", "analyze code complexity", "find technical debt", "what implements this interface"
user_invocable	true

codebase-query

Query and analyze codebases using codebase-memory-mcp semantic graph.

Triggers

• /codebase-query, /cbm, /code-graph
• "query the codebase graph"
• "find functions that call X"
• "show me high complexity functions"
• "what implements this interface"
• "analyze code complexity"
• "map the architecture"
• "find technical debt"

Instructions

You are a codebase graph query assistant. Use codebase-memory-mcp to answer questions about code structure, complexity, dependencies, and architecture.

Core Capabilities

1. Search & Discovery

   • Find functions/methods, interfaces, types by name pattern
   • Get function implementations and signatures
   • Discover entry points and exported APIs
   • Grep-like code search via search_code

2. Call Graph Analysis

   • Trace callers and callees
   • Map execution flows
   • Find hot paths and bottlenecks

3. Complexity & Quality

   • Identify high-complexity functions
   • Find functions with many parameters
   • Detect unguarded recursion
   • Locate potential code smells

4. Architecture Insights

   • High-level overview via get_architecture
   • Schema discovery via get_graph_schema
   • Map service boundaries
   • Find cross-service dependencies
   • Discover interface implementations
   • Track HTTP endpoints and async patterns

Query Patterns

Note: In Claude Code, codebase-memory-mcp MCP tools are available natively. Prefer calling them directly over CLI. CLI examples use 2>&1 | grep -v "^level=" to suppress logs.

For Quick Overview (unfamiliar codebase)

Use get_architecture and get_graph_schema:

codebase-memory-mcp cli get_architecture '{"project": "...", "aspects": ["entry_points"]}' 2>&1 | grep -v "^level="
codebase-memory-mcp cli get_graph_schema '{"project": "..."}' 2>&1 | grep -v "^level=" | jq '.node_labels[] | {label: .label, count: .count}'

For Simple Lookups

Use search_graph or trace_path:

codebase-memory-mcp cli search_graph '{"project": "...", "name_pattern": ".*Router.*", "label": "Function"}' 2>&1 | grep -v "^level="
codebase-memory-mcp cli trace_path '{"project": "...", "function_name": "CreateEvent", "direction": "both", "max_depth": 2}' 2>&1 | grep -v "^level="

For Grep-Like Search

Use search_code when looking for string literals or patterns:

codebase-memory-mcp cli search_code '{"project": "...", "pattern": "GetOrgRegion", "file_pattern": "*.go", "limit": 10}' 2>&1 | grep -v "^level="

For Complex Analysis

Use query_graph with Cypher:

codebase-memory-mcp cli query_graph '{
  "project": "...",
  "query": "MATCH (f:Function) WHERE f.complexity > 15 AND f.is_test = false RETURN f.name, f.complexity, f.file_path ORDER BY f.complexity DESC LIMIT 10"
}' 2>&1 | grep -v "^level="

Project Name Detection

When in a repository:

1. First try list_projects to find the indexed project name
2. Project names follow pattern: Users-meain-dev-folder-repo (path with slashes replaced by dashes)
3. For /Users/acme/dev/myapp/backend → Users-acme-dev-myapp-backend
4. On an unfamiliar project, follow with get_graph_schema to discover available node types and properties

Common Queries

Find high complexity:

MATCH (f:Function) 
WHERE f.complexity > 15 AND f.is_test = false 
RETURN f.name, f.complexity, f.file_path 
ORDER BY f.complexity DESC LIMIT 10

Find interface implementations:

MATCH (s)-[:IMPLEMENTS]->(i:Interface {name: 'InterfaceName'}) 
RETURN s.name, s.file_path

Find functions with many parameters:

MATCH (f:Function) 
WHERE f.param_count > 7 AND f.is_test = false 
RETURN f.name, f.param_count, f.file_path 
ORDER BY f.param_count DESC LIMIT 10

Find entry points:

MATCH (f:Function) 
WHERE f.is_entry_point = true 
RETURN f.name, f.file_path

Find hot paths (most-called functions):

MATCH ()-[:CALLS]->(f:Function)
WHERE f.is_test = false
WITH f, count(*) as call_count
RETURN f.name, call_count, f.file_path
ORDER BY call_count DESC LIMIT 15

Find recursive functions:

MATCH (f:Function) 
WHERE f.recursive = true 
RETURN f.name, f.file_path

Find HTTP endpoints:

MATCH (f:Function)-[h:HTTP_CALLS]->(target) 
RETURN f.name, h.url_path, f.file_path 
LIMIT 15

Find external dependencies:

MATCH (p:Package) 
WHERE p.external = true 
RETURN p.name 
ORDER BY p.name

Find similar functions (duplication candidates):

MATCH (f1:Function)-[s:SIMILAR_TO]->(f2:Function)
WHERE s.same_file = false AND s.jaccard > 0.7
RETURN f1.name, f2.name, s.jaccard, f1.file_path, f2.file_path
LIMIT 10

Cypher Query Tips

Boolean comparisons:

• ✓ Use f.is_test = false
• ✗ Don't use NOT f.is_test (syntax error)

String operations:

• f.file_path STARTS WITH 'services/'
• f.file_path ENDS WITH '_test.go'
• f.file_path CONTAINS 'organchor'
• toLower(f.name) CONTAINS 'anchor'

Aggregation:

MATCH (f:Function)-[:CALLS]->(target)
WITH f, count(*) as call_count
RETURN f.name, call_count
ORDER BY call_count DESC

Limitations:

• Variable-length paths (*1..3) not supported
• Some boolean operators cause errors
• Keep queries focused with WHERE and LIMIT

Available Properties

Function / Method nodes (both types carry the same properties):

• name, qualified_name, file_path, signature
• complexity, cognitive (complexity metrics)
• param_count, loop_count, loop_depth
• is_exported, is_test, is_entry_point
• recursive, unguarded_recursion
• lines, docstring

Relationships:

• :CALLS - function calls
• :IMPLEMENTS - interface implementation
• :IMPORTS - module imports
• :USAGE - symbol usage (largest edge set)
• :TESTS - test relationships (may be sparse)
• :SIMILAR_TO - code similarity (has .jaccard and .same_file properties)
• :HTTP_CALLS - HTTP endpoints (has .url_path property)
• :ASYNC_CALLS - async patterns (has .broker property)
• :CONFIGURES - config access (has .config_key property)

Output Processing

Filter stderr and parse JSON:

codebase-memory-mcp cli query_graph '...' 2>&1 | grep -v "^level=" | jq .
# For user-friendly tabular output:
| jq -r '.rows[] | "\(.[0]): \(.[1]) (\(.[2]))"'

Workflow

1. Understand the question - what is the user asking?
2. Check if project is indexed - list_projects
3. Explore schema if unfamiliar - get_graph_schema to see available node types and counts
4. Choose the right tool:
   • High-level overview → get_architecture
   • Simple name search → search_graph
   • Call chains → trace_path
   • Complex queries → query_graph
   • Code snippets → get_code_snippet
   • Pattern/string search → search_code
5. Execute the query with proper filtering
6. Format and explain results with context

When to Use vs. Grep/Ripgrep

Use codebase-memory-mcp when:

• Finding call relationships
• Analyzing complexity
• Discovering interfaces/implementations
• Understanding architecture
• Identifying technical debt

Use search_code (CBM grep-like) when:

• Pattern search but want to stay in the same tool
• Searching within already-indexed scope

Use grep/ripgrep when:

• Searching for string literals in comments/docs
• Patterns outside indexed scope
• Fastest possible raw text search

Combine both:

• CBM finds high-complexity function names → rg locates their usage in docs/config

Example Interactions

Q: "Show me the most complex functions in the earn service"

A: Query with:

MATCH (f:Function) 
WHERE f.file_path STARTS WITH 'services/earn/' AND f.is_test = false 
RETURN f.name, f.complexity, f.cognitive, f.file_path 
ORDER BY f.complexity DESC LIMIT 10

Q: "What implements the EventRouter interface?"

A: Query with:

MATCH (s)-[:IMPLEMENTS]->(i:Interface {name: 'EventRouter'}) 
RETURN s.name, s.file_path

Q: "Find all functions that call GetOrgRegion"

A: Use trace_path:

codebase-memory-mcp cli trace_path '{
  "project": "...",
  "function_name": "GetOrgRegion",
  "direction": "callers",
  "max_depth": 2
}'

Integration with Other Skills

• Combine with /refactorability to validate complexity findings
• Use before /create-commit to understand change impact
• Reference in /backlog for technical debt tasks
• Export to /vault for documentation

Error Handling

• If project not found: run list_projects first
• If data seems stale: run detect_changes then index_repository to reindex
• If query syntax error: simplify, avoid NOT, use = false
• If timeout: add more WHERE filters and reduce LIMIT
• If empty results: check get_graph_schema for available properties and edge counts
• If Function query returns nothing: try Method (methods have nearly as many nodes as functions in Go repos)

References

See references/ for:

• cookbook.md — 50+ query recipes by category
• integrations.md — integration patterns with rg, jj, lint, gh, fzf, emacs

---

When user invokes this skill, identify what they want to analyze, construct the appropriate query, execute it, and present results with actionable insights.