Metadata-Version: 2.4
Name: berkelium
Version: 0.1.1
Summary: Berkelium CLI — TUI for code graph management.
Project-URL: documentation, https://github.com/BerkeliumLabs/berkelium-cli#readme
Project-URL: homepage, https://berkelium.dev
Project-URL: issues, https://github.com/BerkeliumLabs/berkelium-cli/issues
Project-URL: repository, https://github.com/BerkeliumLabs/berkelium-cli
Author-email: Buddhi Kavindra <info@buddhilive.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: fastmcp>=3.1.1
Requires-Dist: graphqlite>=0.4.0
Requires-Dist: textual-pyfiglet>=1.0.0
Requires-Dist: textual[syntax]>=8.2.0
Requires-Dist: tree-sitter-language-pack>=1.3.3
Requires-Dist: tree-sitter>=0.25.2
Description-Content-Type: text/markdown

# Berkelium CLI
<p align="center">
<a href="https://pypi.org/project/berkelium/">
    <img src="https://img.shields.io/pypi/v/berkelium?style=flat-square&logo=pypi" alt="PyPI Version">
  </a>
  <a href="https://pypi.org/project/berkelium/">
    <img src="https://img.shields.io/pypi/dm/berkelium?style=flat-square" alt="PyPI Downloads">
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/github/license/BerkeliumLabs/berkelium-cli?style=flat-square" alt="License">
  </a>
  <img src="https://img.shields.io/badge/MCP-Compatible-green?style=flat-square" alt="MCP Compatible">
</p>

Berkelium CLI is a **Code Graph Management** tool and **Model Context Protocol (MCP)** server. It uses `tree-sitter` to parse your codebase into a structured graph stored in SQLite, enabling high-fidelity impact analysis and surgical context retrieval for AI assistants.

## Quick Start

### Installation

```bash
# Install
pip install berkelium

# Run the TUI
berkelium-cli
```

### Development Setup
```bash
git clone https://github.com/BerkeliumLabs/berkelium-cli
cd berkelium-cli
uv sync
```

## TUI Features
The Berkelium TUI (`berkelium-cli`) provides a terminal interface for:
- **Build/Update Graph**: Index supported languages (Python, JS/TS, Go, Java, Rust, C/C++).
- **Incremental Sync**: Uses git-diff to update the graph in milliseconds.
- **Exploration**: Visualize symbols and relationships directly in your terminal.

## MCP Server (for AI Assistants)
Connect Berkelium to Claude, Cursor, or any MCP-compatible client to give your AI "graph-vision" over your code.

### Configuration (Claude)
Add this to your `settings.json`:
```json
{
  "mcpServers": {
    "berkelium": {
      "command": "berkelium-mcp",
    }
  }
}
```

### Available Tools
- `query_search_codebase`: Executes read-only Cypher queries directly against the code graph for advanced structural search.

### Available Prompts
- `review_my_pr`: A guided workflow that syncs the graph, identifies changes via git, and suggests targeted tests based on impact analysis.

## Usage Examples (AI-Assisted Development)
Berkelium is most powerful when used through an AI assistant (like Claude or Cursor). Here are some real-world scenarios where it excels:

### 1. Architectural Exploration
**Prompt:** *"I want to add a new database provider. Show me all classes that inherit from `BaseProvider` to see the existing pattern."*
* **AI Action:** Uses `query_search_codebase` with a Cypher query like:
  ```cypher
  MATCH (child)-[:INHERITS]->(parent) WHERE parent.name = 'BaseProvider' RETURN child.name AS name, child.file_rel_path AS file
  ```

### 2. Tracing Complex Call Chains
**Prompt:** *"Trace the execution flow starting from `IncrementalSync.sync()`. What internal methods does it reach?"*
* **AI Action:** Uses `query_search_codebase` to traverse the `[:CALLS]` edges.

### 3. Identifying Dead Code
**Prompt:** *"Are there any functions in the `utils/` directory that are never called by any other part of the project?"*
* **AI Action:** Uses `query_search_codebase` to find nodes with zero incoming `[:CALLS]` edges.

## Architecture
- **Extractor (`extractor.py`)**: Language-agnostic extraction using `tree-sitter`.
- **Store (`store.py`)**: Persistence layer using `GraphQLite` on SQLite.
- **Sync (`sync.py`)**: Git-based incremental synchronization logic.
- **Retriever (`retriever.py`)**: Graph traversal algorithms for impact and context.

## License
MIT License - see [LICENSE](LICENSE).
