context-distill

A Go tool thatdistills command output and retrieves code contextbefore it reaches a paid LLM. Available as aSkill(recommended), astandalone CLI, and anMCP server. Inspired by thedistillCLI and built with hexagonal architecture, dependency injection, and TDD.

context-distillexposes four operations accessible inthree ways:

All three modes share the same underlying use cases, validation rules, and output behavior. Only the invocation method differs.

- LLM provider configuration via YAML and environment variables.
- An interactive terminal UI for first-time setup (--config-ui).
- Support for Ollama and any OpenAI-compatible provider.

Skill mode works because modern coding agents (Codex, Claude Code, Cursor, Aider, OpenCode…) already know how to read project documentation and execute shell commands. ASKILL.mdfile teaches the agentwhento distill or retrieve code context andhowto call the CLI — no protocol integration needed.

- Triple interface— Skill file for zero-config agent adoption + CLI for direct shell use + MCP tools for protocol-native clients.
- Four core operations—distill_batch,distill_mcp_output,distill_watch, andsearch_code.
- Hexagonal architecture—distill/domain,distill/application,platform/.
- Dependency injectionviasarulabs/di.
- Config managementwithviper+.env.
- Provider-specific validationat config time.
- Interactive setup UI(--config-ui).
- Unit, integration, and optional live tests.

make install # installs to ~/.local/bin/context-distill

# Latest release curl -fsSL https://raw.githubusercontent.com/jcastilloa/context-distill/master/scripts/install.sh | sh # Specific version curl -fsSL https://raw.githubusercontent.com/jcastilloa/context-distill/master/scripts/install.sh | VERSION=vX.Y.Z sh

# Latest release iwr https://raw.githubusercontent.com/jcastilloa/context-distill/master/scripts/install.ps1 -UseBasicParsing | iex # Specific version $env:VERSION='vX.Y.Z'; iwr https://raw.githubusercontent.com/jcastilloa/context-distill/master/scripts/install.ps1 -UseBasicParsing | iex

echo "PASS: TestA, PASS: TestB, FAIL: TestC - expected 4 got 5" | context-distill distill_batch --question "Did tests pass? Return only PASS or FAIL. If FAIL, list failing test names."

context-distill distill_watch --question "What changed? Return one short sentence." --previous-cycle "services: api=OK, db=OK, cache=OK" --current-cycle "services: api=OK, db=FAIL, cache=OK"

context-distill distill_mcp_output \ --tool-name "list_items" \ --question "Return only item names, one per line." \ --output '[{"type":"text","text":"[{\"id\":\"a1\",\"name\":\"Alpha\"},{\"id\":\"b2\",\"name\":\"Beta\"}]"}]'

context-distill distill_mcp_output \ --server-command "/absolute/path/to/mcp-server" \ --server-arg "--transport" \ --server-arg "stdio" \ --tool-name "get_status" \ --tool-arguments '{"scope":"production"}' \ --question "Return only status and version as JSON."

context-distill search_code --query "provider_name" --mode text --question "Return only file:line, one per line."

# Pipe (preferred) echo "data" | context-distill distill_batch --question "..." # Explicit flag context-distill distill_batch --question "..." --input "data" # Explicit stdin marker echo "data" | context-distill distill_batch --question "..." --input - # MCP payload distillation context-distill distill_mcp_output --tool-name "list_items" --question "Return only item names." --output '<mcp payload>' # MCP call + distillation in one step context-distill distill_mcp_output --server-command "/absolute/path/to/mcp-server" --server-arg "--transport" --server-arg "stdio" --tool-name "get_status" --tool-arguments '{"scope":"production"}' --question "Return only status and version as JSON." # Code retrieval context-distill search_code --query "LoadDistillConfig" --mode symbol --question "Return likely definitions first as file:line, one per line."

mkdir -p .claude/skills/context-distill cp SKILL.md .claude/skills/context-distill/SKILL.md

for agent in .claude .codex .opencode .cursor; do mkdir -p ~/"$agent"/skills/context-distill cp SKILL.md ~/"$agent"/skills/context-distill/SKILL.md done

# 1. Pipe (preferred) echo "data" | context-distill distill_batch --question "..." # 2. Explicit flag context-distill distill_batch --question "..." --input "data" # 3. Explicit stdin marker echo "data" | context-distill distill_batch --question "..." --input -

go test ./... 2>&1 | context-distill distill_batch --question "Did all tests pass? Return only PASS or FAIL."

context-distill distill_mcp_output \ --tool-name "list_items" \ --question "Return only item names, one per line." \ --output '<mcp payload>'

context-distill distill_mcp_output \ --server-command "/absolute/path/to/mcp-server" \ --server-arg "--transport" \ --server-arg "stdio" \ --tool-name "get_status" \ --tool-arguments '{"scope":"production"}' \ --question "Return only status and version as JSON."

context-distill distill_watch \ --question "Return only newly failing services, one per line." \ --previous-cycle "$(cat /tmp/health.prev)" \ --current-cycle "$(cat /tmp/health.curr)"

context-distill search_code \ --query "distill_watch" \ --mode symbol \ --question "Return definitions first, then usages, as file:line."

context-distill --transport stdio # or without building: go run ./cmd/server --transport stdio

{ "mcpServers": { "context-distill": { "command": "/absolute/path/to/context-distill", "args": ["--transport", "stdio"] } } }

[mcp_servers.context-distill] command = "/absolute/path/to/context-distill" args = ["--transport", "stdio"] startup_timeout_sec = 20.0

[mcp_servers.context-distill] command = "/home/<your-user>/.local/bin/context-distill" args = ["--transport", "stdio"] startup_timeout_sec = 20.0

codex mcp add context-distill -- /absolute/path/to/context-distill --transport stdio

codex mcp list codex mcp get context-distill

Restart your Codex session so it picks up the new server.
- Location→Current projectorGlobal.
- Name→context-distill.
- Type→local.
- Command→/absolute/path/to/context-distill --transport stdio.

If the server is not connected yet, restart your OpenCode session.

OpenCode — manual config (opencode.json)

{ "$schema": "https://opencode.ai/config.json", "mcp": { "context-distill": { "type": "local", "command": ["/absolute/path/to/context-distill", "--transport", "stdio"], "enabled": true } } }

- Always use anabsolutebinary path.
- Always usestdiotransport.
- If the server does not appear, runcodex mcp list --jsonto inspect the resolved config.

The MCP tools expose the same capabilities as the CLI commands (distillation + code retrieval), but are consumed by MCP-compatible clients over thestdiotransport.

Returns a short, focused answer toquestion.

Returns a short summary of relevant changes, or a no-change message when nothing meaningful differs.

Returns compact output controlled byquestion, after local repository retrieval.

- This section documents MCP tool payload fields (snake_case), not shell flags.
- CLI equivalents are--query,--mode,--question,--scope,--max-results,--context-lines.

Terminal UI (recommended for first-time setup)

context-distill --config-ui # or without building: go run ./cmd/server --config-ui

- Providers that require an API key block save until one is entered.
- OpenAI-compatible providers require abase_url.
- Provider aliases are normalized automatically (e.g.OpenAI Compatible→openai-compatible,dmr→docker-model-runner).

Persisted config path:~/.config/context-distill/config.yaml

Save preserves existing YAML sections (service,openai, etc.) and updates only the relevantdistillfields.

You can also edit the config file directly.
- ~/.config/<service>/config.yaml
- ./config.yaml

service: transport: stdio openai: provider_name: openai api_key: sk-xxxx base_url: https://api.openai.com/v1 model: gpt-4o-mini timeout: 30s max_retries: 3 supports_system_role: true supports_json_mode: true distill: provider_name: ollama base_url: http://127.0.0.1:11434 model: qwen3.5:2b timeout: 90s max_retries: 0 thinking: false

Note:service.versionis injected at build time from binary metadata and does not need to be set manually.

The quality of distillation/search output depends on thequestioncontract — whether invoked via Skill, CLI, or MCP. Be explicit aboutwhatyou want andin what format.