# CTX — Portable Project Context Engine & Agent Harness

<p align="center">
  <img src="https://img.shields.io/badge/version-0.2.0--beta-blue.svg?style=flat-square" alt="Version">
  <img src="https://img.shields.io/badge/python-3.11%20%7C%203.12-blue?style=flat-square&logo=python" alt="Python Version">
  <img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/protocol-Model%20Context%20Protocol%20(MCP)-orange?style=flat-square" alt="MCP">
  <img src="https://img.shields.io/badge/parser-Tree--sitter-red?style=flat-square" alt="Tree-sitter">
  <img src="https://img.shields.io/badge/storage-SQLite%20(Embedded)-lightgrey?style=flat-square" alt="Storage">
  <img src="https://img.shields.io/badge/status-active%20development-brightgreen?style=flat-square" alt="Status">
</p>

> **CTX** is a lightweight, agent-agnostic project context engine and deterministic coding harness. It equips AI coding agents (such as OpenCode, Claude Desktop, and custom MCP clients) with structured repository intelligence, abstract syntax tree (AST) symbol indexing, and bounded context without requiring external LLM calls or cloud dependencies.

---

## 📌 Overview & Problem Statement

Modern AI coding agents struggle on non-trivial codebases due to two recurring bottlenecks:
1. **Context Window Saturation & Inefficiency**: Dumping raw files or relying purely on fuzzy vector embeddings wastes tokens, degrades reasoning quality, and introduces hallucinated API boundaries.
2. **Lack of Deterministic Engineering Structure**: LLMs lack an instant, exact mental model of project architecture, AST symbol definitions, and internal import graphs.

```
                    ┌──────────────────────────────────────────────┐
                    │               AI Coding Agent                │
                    │        (OpenCode, Claude, Cursor, etc.)      │
                    └──────────────────────┬───────────────────────┘
                                           │ MCP (JSON-RPC 2.0)
                                           ▼
                    ┌──────────────────────────────────────────────┐
                    │                  CTX Engine                  │
                    │  ┌────────────────────┬───────────────────┐  │
                    │  │   Tree-sitter AST  │  SQLite Relational│  │
                    │  │   Symbol Indexer   │  Dependency Graph │  │
                    │  ├────────────────────┼───────────────────┤  │
                    │  │ Bounded Context Gen│ Harness Injector  │  │
                    │  └────────────────────┴───────────────────┘  │
                    └──────────────────────┬───────────────────────┘
                                           │ Read-Only / Non-Destructive
                                           ▼
                    ┌──────────────────────────────────────────────┐
                    │              Target Codebase                 │
                    └──────────────────────────────────────────────┘
```

**CTX solves this by acting as a deterministic intelligence layer:**
- **Zero Cloud / Zero LLM Overhead**: Runs 100% locally and offline. No API keys, zero inference cost, and zero external network calls.
- **Tree-sitter Powered**: Exact AST extraction of functions, methods, classes, interfaces, types, and constants across multiple languages.
- **Fast Incremental Indexing**: SHA-256 fingerprinting ensures sub-second re-indexing of only modified source files.
- **Standards-Compliant MCP Server**: Exposes structured repository intelligence directly to LLM agents via standard Model Context Protocol (MCP) over stdio.

---

## ✨ Core Features

| Feature | Description |
| :--- | :--- |
| 🌳 **Polyglot AST Symbol Engine** | Multi-language parsing powered by `tree-sitter` for Python, TypeScript, JavaScript, Go, Rust, and Java. |
| ⚡ **Incremental Relational Index** | Embedded SQLite index with SHA-256 file fingerprinting for instant, cached symbol and dependency lookups. |
| 🔗 **Import & Dependency Graph** | Tracks file-level inbound and outbound import relationships with internal project target resolution. |
| 🛡️ **Non-Destructive Harness Setup** | Idempotent initialization that configures `AGENTS.md` and MCP client configurations without modifying user code. |
| 📦 **Bounded Context Generation** | Delivers token-optimized, compact repository digests to agents without bloating prompt budgets. |
| 💻 **Intuitive CLI & Rich Terminal UI** | Clean, diagnostic-friendly terminal interface built with Typer and Rich. |

---

## 🏗️ System Architecture

CTX is engineered around modular service layers and strict separation of concerns:

```
src/ctx/
├── cli.py                     # Typer CLI entrypoint & formatted Rich UI
├── config/
│   └── manager.py             # TOML configuration lifecycle & schema validation
├── harness/
│   ├── agents.py              # Non-destructive AGENTS.md block manager
│   ├── mcp.py                 # JSON-RPC 2.0 stdio Model Context Protocol server
│   ├── opencode.py            # OpenCode JSON configuration integration
│   └── setup.py               # Orchestrator for agent harness provisioning
├── intelligence/
│   ├── imports.py             # Import specifier extractors & path resolvers
│   ├── index.py               # SQLite schema, query engine & transaction manager
│   ├── languages.py           # Language detection & Tree-sitter grammar registry
│   ├── summary.py             # Token-bounded context summary generators
│   └── symbols.py             # AST visitors for functions, classes, and types
├── project/
│   ├── initializer.py         # Idempotent .ctx/ scaffolding
│   └── root.py                # Repository root resolution & marker traversal
├── scanner/
│   └── detector.py            # Heuristic detection for frameworks, tests & tools
└── status/
    └── reporter.py            # Comprehensive system health and index metrics
```

---

## 🚀 Quick Start

### Prerequisites
- Python **3.11+**
- Git

### Installation

Clone the repository and install in editable mode:

```bash
git clone https://github.com/your-username/ctx.git
cd ctx
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

Verify the installation:

```bash
ctx --help
```

---

## 🛠️ Usage & Workflow

### 1. Initialize CTX in a Repository
Run `ctx init` at the root of any software project. It safely creates `.ctx/config.toml` without touching existing files:

```bash
cd /path/to/target-project
ctx init
```

### 2. Configure Agent Harness (OpenCode / MCP)
Automatically configure your agent environment, register the MCP server, and set up project instructions:

```bash
ctx setup
```
This idempotently:
- Injects a managed context block into `AGENTS.md`.
- Registers the local `ctx mcp` server in `opencode.json`.
- Updates `.ctx/config.toml` harness state.

### 3. Build & Query the Project Index

Build or incrementally refresh the AST symbol database:

```bash
# Build / update the index (cached by SHA-256 fingerprint)
ctx index

# Rebuild the index from scratch
ctx index --reset
```

Query symbols, dependencies, and file relationships instantly:

```bash
# Find functions, classes, or types by name
ctx symbols OrderService --kind class

# Inspect outbound and inbound dependencies of a module
ctx deps src/services/order.py

# Query import references for a specific file
ctx imports src/api/routes.py
```

### 4. Inspect Project Health & Status
Get a consolidated overview of project structure, index coverage, and agent configuration:

```bash
ctx status
```

### 5. Run the MCP Server
When invoked by an MCP client (such as OpenCode or Claude Desktop), CTX runs an interactive stdio server exposing the `ctx_context` tool:

```bash
ctx mcp
```

---

## 📊 Comparison: CTX vs. Traditional Approaches

| Dimension | Raw LLM Context | Vector Embeddings (RAG) | CTX Engine |
| :--- | :--- | :--- | :--- |
| **Accuracy** | Prone to truncation | Approximate / Fuzzy | **100% Deterministic (AST)** |
| **Token Consumption** | Extremely High | Moderate to High | **Minimal / Bounded** |
| **Execution Cost** | Costly API usage | Embedding API costs | **$0.00 (Zero external calls)** |
| **Offline Support** | ❌ No | ❌ Rare (Needs local models) | **✅ 100% Offline** |
| **Update Latency** | Full re-scan | Slow re-vectorization | **Sub-second (SHA-256 diff)** |
| **Protocol Support** | Ad-hoc prompts | Custom vector integrations | **Standard MCP (JSON-RPC)** |

---

## 🗺️ Project Roadmap & Ongoing Development

CTX is under active development. Below is the current evolution roadmap:

### 🟢 Phase 0: Foundation *(Completed)*
- [x] Project root detection & directory hierarchy traversal
- [x] Idempotent `.ctx/config.toml` schema and configuration lifecycle
- [x] Rich diagnostic status reporter (`ctx status`)

### 🟢 Phase 1: Agent Harness & Protocol Integration *(Completed)*
- [x] Stdio-based JSON-RPC 2.0 Model Context Protocol (MCP) server
- [x] Safe, idempotent `AGENTS.md` block injector
- [x] Automated OpenCode integration (`opencode.json` configuration manager)
- [x] Read-only bounded `ctx_context` tool for AI agents

### 🟢 Phase 2: Polyglot Project Intelligence *(Completed)*
- [x] Persistent embedded SQLite index (`.ctx/index/index.db`)
- [x] Tree-sitter AST extractors for Python, JavaScript, TypeScript, Go, Rust, and Java
- [x] SHA-256 fingerprint-based incremental indexing
- [x] Exact symbol lookup (`ctx symbols`), import tracing (`ctx imports`), and dependency graph (`ctx deps`)
- [x] Configurable index exclusion filters (`[index] ignore`)

### 🟡 Phase 3: Active Execution & Verification Harness *(In Progress)*
- [ ] Test discovery and targeted test runner harness (`ctx test`)
- [ ] Automated regression check hooks before agent commit
- [ ] Git diff & change-impact analysis engine

### ⚪ Phase 4: Long-Term Memory & Multi-Repo Intelligence *(Planned)*
- [ ] Architectural Decision Record (ADR) synchronization
- [ ] Task execution memory & persistent agent scratchpad (`.ctx/memory/`)
- [ ] Multi-workspace and monorepo cross-indexing

---

## 🧪 Testing & Code Quality

CTX maintains a comprehensive automated test suite with temporary directory isolation, ensuring no tests modify workspace files.

```bash
# Run full test suite
pytest

# Run tests with coverage reporting
pytest --cov=src/ctx --cov-report=term-missing

# Lint and check style
ruff check src/ tests/
```

---

## 📁 Repository Strategy & Cleanliness

- **Committed Files**: `.ctx/config.toml`, documentation, and core project settings.
- **Ignored / Disposable Artifacts**: `.ctx/index/index.db`, caches, and temporary scan output. The SQLite index is treated as disposable cache and can be safely regenerated at any time with `ctx index --reset`.

---

## 📜 License

This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

---

<p align="center">
  <sub>Engineered for deterministic AI agent execution. Built with Python, Tree-sitter, and the Model Context Protocol.</sub>
</p>