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

```console
pip install scopix
```

## Quick start

```console
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:

```markdown
### 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](https://github.com/zahidhasann88/scopix/blob/main/docs/reference.md#mcp-server) for other clients.

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

## Python API

```python
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](https://github.com/zahidhasann88/scopix/blob/main/docs/benchmark.md).

## Commands

| Command | What it does |
| --- | --- |
| `scopix init` | Create `.scopix/` and build the index |
| `scopix index` | Update the index |
| `scopix select "task"` | Print context for a task |
| `scopix explain "task"` | Show why each item was chosen |
| `scopix export "task"` | Write context as Markdown, JSON, text or XML |
| `scopix stats` | Show index statistics |
| `scopix graph` | Show the dependency graph |
| `scopix watch` | Re-index when files change |
| `scopix serve` | Run an MCP server for coding agents |
| `scopix bench` | Compare results with simple baselines |
| `scopix feedback` | Mark a file as helpful or not |
| `scopix profile` | Manage selection profiles |
| `scopix model` | Set up an optional local AI model |
| `scopix config` | Show or change settings |

Run `scopix COMMAND --help` for options, or see the [reference](https://github.com/zahidhasann88/scopix/blob/main/docs/reference.md).

## 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](https://github.com/zahidhasann88/scopix/blob/main/docs/reference.md#privacy-and-network-use).

## License

MIT. See [LICENSE](https://github.com/zahidhasann88/scopix/blob/main/LICENSE).