Scopix

Scopix picks the code an AI model needs for a task. Give it a task and a token budget, and it returns the most useful files, functions and line ranges, with a reason for each one. It runs on your machine with no account or cloud service. Local AI is optional and experimental.

Install

Scopix needs Python 3.11 or later.

pip install scopix

Quick start

cd your-repo
scopix init
scopix select "fix the authentication refresh logic" --budget 6000
scopix export "fix the authentication refresh logic" --budget 6000 --output context.md

init creates .scopix/ and indexes the repository. select prints the context, and export saves it. Each result looks like this:

### 1. `src/payments/retry-policy.ts` (lines 1-61, ~469 tokens)
**Why:** imported by tests/payment-retry.test.ts (distance 1); defines
`RetryPolicy.shouldRetryResult` which matches the task; matches task terms
`retry`, `payment`, `attempt`

Use with coding agents

Scopix can run as an MCP server, so agents such as Claude Code can ask it for context. See the setup guide for other clients.

pip install "scopix[mcp]"
claude mcp add scopix -- scopix serve --path /path/to/repo

Python API

from scopix import Scopix

with Scopix(".") as engine:
    engine.initialize()
    engine.index()  # only changed files are parsed after the first run
    result = engine.select("add retry handling", token_budget=4000)
    for item in result.items:
        print(item.path, item.start_line, item.end_line, item.tokens)
    print(result.to_markdown())  # or to_json(), to_text(), to_xml()

How well it works

On 45 unseen commits from 9 projects, Scopix found 39% of the changed files in 2,000 tokens, while grep needed 16,000 tokens to reach 38%. It still misses about 4 in 10 at 8,000 tokens. See the benchmark.

Commands

Run scopix COMMAND --help for options, or see the reference.

Languages

Scopix parses TypeScript, JavaScript, Python, Go, Java, Rust, PHP and C#. It indexes other text files with less detail.

Privacy

By default, Scopix sends nothing over the network and never runs your code. It skips files that match secret patterns such as .env and *.pem. Some optional features use the network.

License

MIT. See LICENSE.