cased-kit

The kit toolkit is designed for codebase mapping, symbol extraction, code search, and LLM-powered developer workflows. It uses tree-sitter for multi-language support and provides a "mid-level API" for building custom tools like code review bots, semantic search, and documentation generators.

Key value propositions include:

• Unifying Code Access: A consistent Repository object for interacting with files, symbols, and search across different languages.
• Deep Code Understanding: Accurate, language-specific parsing via tree-sitter for structural analysis.
• Bridging Code and LLMs: Specialized tools for effective code chunking and context retrieval for LLMs.

A symbol is a dictionary representing a code element. It contains the following properties:

• name: The identifier of the symbol (e.g., function name).
• type: The category of the symbol (e.g., function, class, method, variable, constant).
• file: The file path where the symbol is located.
• start_line: The 1-indexed starting line number.
• end_line: The 1-indexed ending line number (inclusive).
• code: The raw source code of the symbol.
• language: The programming language of the symbol.

{
    "name": "authenticate_user",
    "type": "function",
    "file": "src/auth.py",
    "start_line": 42,
    "end_line": 58,
    "code": "def authenticate_user(...):\n    ...",
    "language": "python"
}

All Kit client libraries (including the existing TypeScript client and planned Go, Rust, and Ruby clients) follow a consistent architectural pattern:

• Shell out to CLI: Clients wrap the Kit CLI rather than reimplementing functionality. This ensures the client remains a lightweight interface to the core logic.
• Type safety: Clients provide strong typing for all commands and options.
• Async/Promise-based: Clients use language-appropriate async patterns (e.g., Promises in TypeScript).
• Error handling: Clients parse and wrap CLI errors into language-specific error types.
• Zero Python dependencies: To use a client, you only need the Kit CLI installed; you do not need to install any Python packages in your project environment.

The incremental analysis cache includes built-in memory management and specific requirements for concurrency:

Memory Management

• LRU eviction: Uses a Least Recently Used strategy to prevent unlimited memory growth.
• Configurable cache size: The default limit is 10,000 files.
• Automatic cleanup: Stale entries are cleaned up automatically.

Thread Safety

The cache is designed for single-threaded use. If you are working in a multi-threaded environment, you must create a separate Repository instance for each thread to avoid concurrency issues.

# Create separate instances per thread
def worker_thread():
    repo = Repository("/path/to/repo")  # New instance
    symbols = repo.extract_symbols_incremental()

Kit uses an incremental analysis system to speed up symbol extraction by caching file metadata and symbol data. This data is stored locally within the repository's .kit directory.

Key files in the cache include:

• .kit/incremental_cache/analysis_metadata.json: Stores file metadata such as mtime (modification time), file size, and hashes to detect changes.
• .kit/incremental_cache/symbols_cache.json: Stores the actual cached symbol data.

The DependencyAnalyzer class and its derivatives analyze dependencies between components in a codebase. They help detect circular dependencies, export dependency graphs, and generate LLM-friendly context about architecture.

Because DependencyAnalyzer is an abstract base class, you should not instantiate it directly. Instead, use the Repository.get_dependency_analyzer(language) factory method to obtain the correct implementation for your target language (e.g., 'python' or 'terraform').

from kit import Repository

repo = Repository("/path/to/your/codebase")
analyzer = repo.get_dependency_analyzer('python')  # or 'terraform'

Kit supports multiple LLM providers for AI-powered features like code summarization, PR reviews, and commit message generation.

Native Providers

Kit has built-in support for:

• OpenAI (GPT-4, GPT-5, o-series)
• Anthropic (Claude Opus, Sonnet, Haiku)
• Google (Gemini Pro, Flash)
• Ollama (Local models, no API key required)

OpenAI-Compatible Providers

You can use OpenAIConfig with a custom base_url to access services like OpenRouter, Grok (X.AI), Groq, Together AI, or local servers (vLLM, text-generation-webui).

Note: Core repository analysis features (symbol extraction, file trees, search, dependency analysis) do not require an LLM and work without any API keys.

Kit provides four primary search and discovery methods depending on your goal:

1. Text Search (Regex): Best for finding exact strings, patterns, security tokens (e.g., API_KEY), or TODOs. It is extremely fast and requires no setup.
2. Symbol Search (Tree-sitter): Best for finding code by name (functions, classes, methods) and analyzing code structure. It is very fast and uses cached language-aware extraction.
3. Semantic Search (Embeddings): Best for finding code by meaning when you don't know exact keywords (e.g., "How is authentication handled?"). Requires an embedding model and index building.
4. Docstring Search (LLM + Embeddings): Best for understanding high-level intent or purpose (e.g., "retry logic with backoff"). It uses LLM-generated summaries and is the slowest method, requiring an LLM API key and indexing.

The kit-cli plugin functions as a Claude Skill. This means you do not need to explicitly invoke kit commands. Instead, Claude autonomously decides when to use kit's tools based on the context of your natural language requests.

For example:

• If you ask "How does authentication work?", Claude may use kit symbols, kit search, and kit usages.
• If you ask "Find all usages of the UserModel class", Claude will run kit usages UserModel.
• If you ask "Show me the file structure of src/", Claude will run kit file-tree --subpath src.