CoreBall

Semantic context compiler for LLM coding agents.
Zero dependencies. Deterministic. Token-efficient.
Compile your codebase into the smallest useful context for any task.

---

Stop wasting tokens on irrelevant code. CoreBall analyzes your repository, ranks every file by relevance to a specific task, and emits a compact context package that fits your LLM's context window — no RAG, no embeddings, no bloat.

While other tools re-read your entire codebase on every query, CoreBall pre-compiles a semantic map once and reuses it. The result: 60-90% fewer tokens, deterministic output, and explainable selection.

Quick Start

pip install coreball

Compile context for a task:

coreball pack . --task "explain how authentication works" --max-tokens 2048

Inspect the full semantic index:

coreball inspect . --format markdown

Pipe into your LLM workflow:

coreball pack . --task "find the CLI entry point" --max-tokens 1200 --format json --output context.json

Python API

from coreball import inspect_repository, pack_repository

# Build semantic model (reuse across tasks)
model = inspect_repository(".")

# Compile task-specific context
package = pack_repository(
    ".",
    task="explain how the CLI builds a context package",
    max_tokens=2048,
)

print(f"Selected {len(package.items)} files, ~{package.estimated_tokens} tokens")

Why CoreBall

	Whole-file prompting	RAG / embeddings	CoreBall
Token cost	Sends everything	Chunks loosely	Task-ranked, budget-capped
Determinism	N/A	No (embedding drift)	Yes — same input, same output
Relationships	None	Weak	Symbol + import graph
Explainability	None	Black box	Every selection traced
Dependencies	None	Heavy	Zero (pure stdlib)
Setup	None	Vector DB + embeddings	pip install coreball

How It Works

repository ──> scanner ──> parsers ──> semantic model ──> task scorer ──> graph expansion ──> context packager
                  │              │              │                │                │
                  │              │              │                │                └── relevance boost through
                  │              │              │                └── lexical + symbol + doc scoring
                  │              │              └── files, symbols, imports, call names
                  │              └── Python AST, JS/TS regex, Markdown
                  └── skip .git, node_modules, __pycache__, etc.

1. Scan — discover source files, skip build/dependency directories
2. Parse — extract symbols, imports, and calls (Python AST, JS/TS regex)
3. Rank — score every file against the task using lexical, symbol, and doc matches
4. Expand — boost files that import or call top-ranked files
5. Pack — fit the best excerpts within the token budget
6. Render — output structured Markdown or JSON

Features

• Zero dependencies — pure Python standard library. Nothing to install.
• Deterministic — same input always produces the same output
• Language-aware — Python (AST parsing), JavaScript/TypeScript, Markdown, config files
• Task-scoped — scores and selects only what matters for your question
• Token-budget control — fits exactly within your LLM's context window
• Dual output — Markdown for humans, JSON for pipelines
• Explainable — every file includes a reason for inclusion
• Graph-based expansion — imports and call relationships boost relevance

Use Cases

• LLM context optimization — feed your coding agent only what it needs
• Code review context — compile relevant files for a diff or PR
• Documentation generation — extract the core modules for any subsystem
• Onboarding — generate a compact map of a new codebase
• CI/CD pipelines — automate context selection for AI-assisted workflows

Comparison with Similar Tools

CoreBall occupies a unique niche: pure Python, zero dependencies, deterministic context compilation.

Tool	Language	Approach	Dependencies	MCP
CoreBall	Python	Semantic compiler	Zero	Planned
codegraph	TypeScript/Rust	Knowledge graph	Heavy	Yes
understand-Anything	TypeScript	Multi-agent graph	LLM + heavy	Yes
graphsift	Python	BM25 + AST graph	Heavy	Yes
context-router	Python	Ranked context packs	Heavy	Yes

CoreBall trades runtime sophistication for simplicity and determinism. No databases, no embeddings, no LLM calls — just a clean semantic compiler you can audit, test, and extend.

Limitations

• Token counts are estimates, not tokenizer-specific
• Python support is strongest; JS/TS uses conservative regex extraction
• Relationship inference is intentionally shallow in v0.1
• No language server or build system integration yet
• No MCP server yet (planned)

Development

python -m pip install -e ".[dev]"
ruff format --check .
ruff check .
mypy src/coreball
pytest
python -m build

Contributing

Contributions of all sizes are welcome! See CONTRIBUTING.md for details.

High-impact areas:

• Add language parsers (Go, Rust, Java, C#, PHP)
• Implement MCP server for Claude Code / Cursor / Codex integration
• Improve the relationship graph and ranking algorithm
• Add tree-sitter parsing for more precise AST extraction
• Write benchmarks against real-world repositories
• Documentation and examples

License

CoreBall is released under the MIT License.