Metadata-Version: 2.5
Name: scopix
Version: 0.1.0
Summary: Local-first, dependency-aware code context selection engine for AI coding agents.
Project-URL: Homepage, https://github.com/zahidhasann88/scopix
Project-URL: Repository, https://github.com/zahidhasann88/scopix
Project-URL: Documentation, https://github.com/zahidhasann88/scopix/blob/main/docs/reference.md
Project-URL: Issues, https://github.com/zahidhasann88/scopix/issues
Project-URL: Changelog, https://github.com/zahidhasann88/scopix/blob/main/CHANGELOG.md
Author: Zahid Hasan
License-Expression: MIT
License-File: LICENSE
Keywords: ai,code-context,llm,retrieval,token-budget,tree-sitter
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.6
Requires-Dist: tree-sitter-c-sharp>=0.23
Requires-Dist: tree-sitter-go>=0.23
Requires-Dist: tree-sitter-java>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-php>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-rust>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.23
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mcp>=2.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: tiktoken>=0.6; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: numpy>=1.26; extra == 'embeddings'
Requires-Dist: sentence-transformers>=2.6; extra == 'embeddings'
Provides-Extra: mcp
Requires-Dist: mcp>=2.0; extra == 'mcp'
Provides-Extra: tokens
Requires-Dist: tiktoken>=0.6; extra == 'tokens'
Description-Content-Type: text/markdown

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