Worker-Flash Code Explorer Skill

Overview

This skill provides efficient access to worker-flash's codebase structure through MCP (Model Context Protocol). Instead of reading entire files, Claude Code can query a SQLite index to quickly find symbols, their signatures, locations, and documentation.

Benefits

• •85% token reduction - Query database (~2K tokens) instead of reading files (~10K tokens)
• •15x faster - Queries return in <10ms vs 30+ seconds for file reads
• •Better navigation - Quickly discover classes, functions, and their relationships
• •Always in sync - Index updates automatically when you run make index

How It Works

The skill uses two components:

1. •

   SQLite Index (.code-intel/flash.db)

   • •Automatically generated by make index
   • •Contains ~94 symbols from worker-flash source
   • •Updated incrementally (fast rebuilds)
2. •

   MCP Server (scripts/mcp_code_intel_server.py)

   • •Auto-starts when Claude Code loads
   • •Provides 6 query tools
   • •Uses stdio transport for communication

Recommended Workflow

Step 1: Query First

When exploring the codebase, always start with database queries:

"Find the RemoteExecutor class"
→ Uses find_symbol("RemoteExecutor")
→ Returns signature, file, line number in <10ms
→ Uses ~500 tokens

Step 2: Read Selectively

Only read file content when you need implementation details:

"Show me the RemoteExecutor implementation"
→ From query: "src/remote_executor.py:11"
→ Read file: src/remote_executor.py (only the parts you need)
→ Uses ~1K tokens for actual implementation

Step 3: Cross-Reference

Use the index to understand relationships:

"What decorators does this codebase use?"
→ Uses find_by_decorator("property")
→ Shows all properties at a glance
→ Helps understand patterns

Available Queries

All queries are automatically available to Claude Code:

find_symbol(name)

Find classes, functions, or methods by name

Example: "Find the DependencyInstaller class"

→ Returns: name, kind, signature, location, docstring
→ Shows where in codebase it's defined
→ Includes full type signature

list_classes()

Browse all classes in the codebase

Example: "What classes are in this project?"

→ Returns: all classes grouped by file
→ Shows line numbers
→ Good for understanding architecture

get_class_interface(class_name)

See class API surface without reading implementation

Example: "Show me the FunctionExecutor interface"

→ Returns: all methods with signatures and decorators
→ Includes docstrings but not implementations
→ Perfect for understanding how to use a class
→ Shows decorators (@property, @staticmethod, etc.)

list_file_symbols(file_path)

Explore file structure quickly

Example: "What's in the handler.py file?"

→ Returns: all symbols in file by line number
→ Groups classes, functions, methods
→ Shows structure without reading code

find_by_decorator(decorator)

Find symbols with specific decorators

Example: "What functions use @remote?"

→ Returns: all symbols with matching decorator
→ Useful for understanding patterns
→ Shows decorator combinations

parse_test_output(output)

Parse pytest output to extract failures and coverage

Example: "Analyze the test results from make test-unit"

→ Takes: raw pytest output text
→ Returns: structured summary of passed/failed/errors/coverage
→ Replaces: tail/grep/cat on test output files
→ Benefit: 99% token reduction (200 tokens vs 20,000+)

Best Practices

DO ✅

• •Query the database first to understand structure
• •Use file locations from queries to navigate to specific implementations
• •Ask about class interfaces before reading implementations
• •Use decorator searches to find patterns
• •Use parse_test_output after running pytest commands instead of grepping output files
• •Re-run make index after making significant code changes

DON'T ❌

• •Read entire files when you only need signatures
• •Ask "What's in this file?" without using list_file_symbols
• •Read src/remote_executor.py to find the RemoteExecutor class (use find_symbol first)
• •Assume file structure - always query first
• •Use tail/grep/cat on test output when parse_test_output is available
• •Manually parse test counts or coverage percentages
• •Forget to update index when code changes significantly

Integration with Claude Code

The skill is automatically registered in .mcp.json:

{
  "mcpServers": {
    "worker-flash-code-intel": {
      "command": "uv",
      "args": ["run", "python", "scripts/mcp_code_intel_server.py"]
    }
  }
}

When you start Claude Code in the worker-flash directory:

1. •It reads .mcp.json
2. •Automatically starts the MCP server
3. •Makes all query tools available
4. •You can reference them in any request

Maintenance

Updating the Index

After making code changes, regenerate the index:

make index

Output:

🔍 Starting code intelligence indexing...
✅ Indexed 94 symbols in 0.15s
📊 Database: .code-intel/flash.db (250 KB)

Index Size

• •Database size: ~250 KB (very small, included in repo is optional)
• •Build time: <1 second
• •Query time: <10ms per query

Troubleshooting

Database not found

Error: Database not found at .code-intel/flash.db
Solution: Run `make index` to generate it

Stale results

Problem: Changes don't appear in queries
Solution: Run `make index` to rebuild the index

Example Exploration Session

Scenario: Understanding RemoteExecutor Architecture

Step 1: Find the class

"Find RemoteExecutor"
→ Query: find_symbol("RemoteExecutor")
→ Result: src/remote_executor.py:11
→ Tokens: 500

Step 2: Understand its interface

"Show RemoteExecutor interface"
→ Query: get_class_interface("RemoteExecutor")
→ Result: List of all methods and their signatures
→ Tokens: 1K
→ Now you understand the public API

Step 3: Find related classes

"Find FunctionExecutor"
→ Query: find_symbol("FunctionExecutor")
→ Result: src/function_executor.py:12
→ Tokens: 500
→ See how RemoteExecutor uses FunctionExecutor

Step 4: Read only what you need

"Show me how RemoteExecutor instantiates FunctionExecutor"
→ Read: src/remote_executor.py lines 80-120 (specific lines)
→ Tokens: 2K
→ Total exploration: ~4K tokens vs ~15K for reading files

Scenario: Analyzing Test Results

Step 1: Run tests

make test-unit
→ Output: 474 tests run with some failures
→ Challenge: 20K+ tokens of output

Step 2: Parse output

"Parse these test results"
→ Tool: parse_test_output(output)
→ Result: Structured summary of failures and coverage
→ Tokens: 200 (99% reduction)
→ See exactly which tests failed and why

Technical Details

Database Schema

CREATE TABLE symbols (
    id INTEGER PRIMARY KEY,
    file_path TEXT NOT NULL,           -- Relative path from project root
    symbol_name TEXT NOT NULL,          -- Class/function/method name
    kind TEXT NOT NULL,                 -- 'class', 'function', 'method'
    signature TEXT,                     -- Full signature with type hints
    docstring TEXT,                     -- Extracted docstring
    start_line INTEGER NOT NULL,        -- Line number in file
    end_line INTEGER,                   -- End line number
    parent_symbol TEXT,                 -- Parent class for methods
    decorator_json TEXT,                -- JSON array of decorators
    type_hints TEXT,                    -- JSON object of type hints
    created_at INTEGER
);

Indexing Process

1. •AST parser reads all src/**/*.py files
2. •Extracts classes, functions, methods, decorators, type hints
3. •Stores metadata in SQLite
4. •Creates indexes for fast lookups
5. •Reports statistics

Query Performance

• •Symbol name search: <5ms (indexed)
• •Class list: <10ms (filtered query)
• •File symbols: <5ms (indexed on file_path)
• •Decorator search: <10ms (JSON search)

Performance Comparison

Token Usage Example: Understanding FunctionExecutor

Traditional approach (file reading):

1. Read src/function_executor.py: ~8K tokens
2. Read docstrings and understand: ~2K tokens
Total: ~10K tokens
Time: 30+ seconds

Query-first approach:

1. Query find_symbol("FunctionExecutor"): ~500 tokens
2. Query get_class_interface("FunctionExecutor"): ~1K tokens
3. Read implementation only if needed: ~2K tokens
Total: ~3.5K tokens (65% reduction)
Time: <2 seconds

Questions?

If the index doesn't have what you need, you can always:

1. •Run make index to refresh
2. •Use traditional file reading as fallback
3. •Report missing symbol types (MCP server can be extended)

Generated by: worker-flash code intelligence integration Last updated: 2026-01-28