CTX — Portable Project Context Engine & Agent Harness

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.

Related MCP server: Codex MCP Server

✨ Core Features

🏗️ 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:

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:

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:

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:

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:

# 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:

# 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:

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:

ctx mcp

📊 Comparison: CTX vs. Traditional Approaches

🗺️ Project Roadmap & Ongoing Development

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

🟢 Phase 0: Foundation (Completed)

• Project root detection & directory hierarchy traversal

• Idempotent .ctx/config.toml schema and configuration lifecycle

• Rich diagnostic status reporter (ctx status)

🟢 Phase 1: Agent Harness & Protocol Integration (Completed)

• Stdio-based JSON-RPC 2.0 Model Context Protocol (MCP) server

• Safe, idempotent AGENTS.md block injector

• Automated OpenCode integration (opencode.json configuration manager)

• Read-only bounded ctx_context tool for AI agents

🟢 Phase 2: Polyglot Project Intelligence (Completed)

• Persistent embedded SQLite index (.ctx/index/index.db)

• Tree-sitter AST extractors for Python, JavaScript, TypeScript, Go, Rust, and Java

• SHA-256 fingerprint-based incremental indexing

• Exact symbol lookup (ctx symbols), import tracing (ctx imports), and dependency graph (ctx deps)

• 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.

# 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 file for details.