Kontexto

A CLI tool to explore codebases efficiently. Designed for LLMs and coding agents as a smarter alternative to ls, grep, and find.

All output is JSON for easy parsing by LLMs and programmatic consumption.

🌍 Supported Languages

Language	Extensions	Entities Extracted
Python	.py	functions, classes, methods
JavaScript	.js, .jsx, .mjs	functions, classes, methods, arrow functions
TypeScript	.ts, .tsx	functions, classes, methods, interfaces, types
Go	.go	functions, methods, structs, interfaces
Rust	.rs	functions, structs, enums, traits, impl blocks, methods
Java	.java	classes, interfaces, enums, methods, constructors
C/C++	.c, .h, .cpp, .hpp, .cc	functions, structs, enums, classes, methods, typedefs
C#	.cs	classes, interfaces, structs, enums, methods, constructors, properties
PHP	.php	functions, classes, interfaces, traits, methods, enums
Ruby	.rb, .rake	classes, modules, methods, singleton methods

All parsers use tree-sitter for fast, accurate AST-based parsing.

📦 Installation

pip install kontexto

🚀 Quick Start

# 1. Index your project
cd /path/to/your/project
kontexto index

# 2. Explore the codebase
kontexto map                          # See project structure
kontexto expand src/api               # Expand a directory
kontexto search "authentication"      # Search for code
kontexto inspect src/api:UserController   # Inspect entity details
kontexto hierarchy BaseModel          # Find all subclasses
kontexto read src/api/users.py 10 50  # Read specific lines

📖 Commands

kontexto index [path]

Index a project and build the navigation graph. Automatically detects and parses all supported languages.

kontexto index                    # Index current directory
kontexto index /path/to/project   # Index specific project
kontexto index -i                 # Incremental update (faster)

Creates a .kontexto/index.db database with:

• File and directory structure
• Classes, methods, functions (and language-specific entities)
• Signatures and docstrings
• Call relationships
• Class inheritance (base classes)
• TF-IDF search index
• Language metadata for each entity

kontexto map [path]

Show a compact map of the project structure.

$ kontexto map

{
  "command": "map",
  "project": "myapp",
  "root": "/path/to/myapp",
  "stats": {"files": 20, "classes": 8, "functions": 45, "methods": 32},
  "children": [
    {"id": "src", "stats": {"files": 12, "classes": 8, "functions": 45}},
    {"id": "tests", "stats": {"files": 8, "classes": 0, "functions": 24}}
  ]
}

kontexto expand <path>

Expand a node to see its children.

$ kontexto expand src/api/users.py

{
  "command": "expand",
  "node": {
    "id": "src/api/users.py",
    "name": "users.py",
    "type": "file",
    "line_end": 95
  },
  "children": [
    {
      "id": "src/api/users.py:UserController",
      "name": "UserController",
      "type": "class",
      "line_start": 10,
      "line_end": 89,
      "signature": "class UserController",
      "docstring": "Handles user API endpoints",
      "base_classes": ["BaseController"]
    }
  ]
}

kontexto inspect <entity>

Show detailed info about an entity: signature, docstring, relationships.

$ kontexto inspect src/api/users.py:UserController.get_user

{
  "command": "inspect",
  "node": {
    "id": "src/api/users.py:UserController.get_user",
    "name": "get_user",
    "type": "method",
    "file_path": "src/api/users.py",
    "line_start": 15,
    "line_end": 25,
    "signature": "def get_user(self, user_id: int) -> User",
    "docstring": "Retrieve user by ID from database."
  },
  "calls": ["find_by_id"],
  "called_by": ["src/api/routes.py:user_routes"]
}

kontexto search <query>

Search for entities by keyword (names, docstrings, signatures).

$ kontexto search "authentication"

{
  "command": "search",
  "query": "authentication",
  "count": 3,
  "results": [
    {
      "node": {
        "id": "src/api/auth.py:require_auth",
        "name": "require_auth",
        "type": "function",
        "signature": "def require_auth(func: Callable) -> Callable"
      },
      "score": 0.8521
    }
  ]
}

Options:

• --limit, -l: Maximum number of results (default: 10)

kontexto hierarchy <base_class>

Find all classes that inherit from a given base class.

$ kontexto hierarchy BaseModel

{
  "command": "hierarchy",
  "base_class": "BaseModel",
  "count": 5,
  "subclasses": [
    {
      "id": "src/models/user.py:User",
      "name": "User",
      "type": "class",
      "base_classes": ["BaseModel"],
      "signature": "class User(BaseModel)"
    },
    {
      "id": "src/models/product.py:Product",
      "name": "Product",
      "type": "class",
      "base_classes": ["BaseModel"],
      "signature": "class Product(BaseModel)"
    }
  ]
}

kontexto read <file> [start] [end]

Read source code from a file. Outputs raw code (not JSON).

$ kontexto read src/api/users.py 15 20

    def get_user(self, user_id: int) -> User:
        """Retrieve user by ID from database."""
        user = self.user_service.find_by_id(user_id)
        if not user:
            raise NotFoundError(f"User {user_id} not found")
        return user

Use line ranges from expand or inspect to read specific functions.

🤖 Use with LLMs

Kontexto is designed for coding agents like Claude Code. Instead of using ls, grep, and find:

# Before: multiple commands, unstructured output
ls -la src/
grep -r "authenticate" src/
cat src/api/auth.py

# After: JSON output, easy to parse
kontexto map
kontexto search "authenticate"
kontexto expand src/api/auth.py

✨ Benefits for LLMs

Tool	Output	Structure	Relationships
ls	File names only	None	None
grep	Matching lines	None	None
find	File paths	None	None
kontexto	Structured JSON	Classes, functions, methods	Calls, called-by, inheritance

Features

• JSON output - All commands return structured JSON for easy parsing
• Class hierarchy - Track inheritance with base_classes field and hierarchy command
• Search caching - Repeated searches are cached for faster response
• Incremental indexing - Only changed files are re-indexed, with incremental search index updates

⚙️ How It Works

Kontexto uses tree-sitter to parse source files and builds a navigable graph:

Project Root
├── Directories
│   └── Files (.py, .js, .ts, .go, .rs, .java)
│       ├── Classes/Structs/Traits (with base_classes)
│       │   └── Methods
│       ├── Functions
│       ├── Interfaces
│       └── Enums

The graph is stored in SQLite with:

• TF-IDF search index for keyword search
• Call relationships tracking who calls what
• Class inheritance tracking base classes
• Language metadata for each entity
• Incremental updates for large codebases (both graph and search index)

Architecture

┌─────────────────┐
│  CLI Commands   │
└────────┬────────┘
         │
┌────────▼────────┐
│   CodeGraph     │
└────────┬────────┘
         │
┌────────▼────────┐
│ ParserRegistry  │
└────────┬────────┘
         │
    ┌────┴────┬────────┬────────┬────────┐
    ▼         ▼        ▼        ▼        ▼
┌───────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│Python │ │  JS  │ │  Go  │ │ Rust │ │ Java │
│Parser │ │Parser│ │Parser│ │Parser│ │Parser│
└───┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘
    │        │        │        │        │
    └────────┴────────┴────────┴────────┘
                      │
              ┌───────▼───────┐
              │  tree-sitter  │
              └───────────────┘

🛠️ Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check src/ tests/

📄 License

MIT