Metadata-Version: 2.4
Name: scopekit
Version: 0.1.0
Summary: Stop paying for AI to read your entire codebase. Scope the folders before the session starts.
Project-URL: Homepage, https://github.com/john24alex/scopekit
Project-URL: Repository, https://github.com/john24alex/scopekit
Project-URL: Bug Tracker, https://github.com/john24alex/scopekit/issues
License: MIT License
        
        Copyright (c) 2025 ScopeKit Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,claude,cli,debugging,developer-tools,tokens,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: questionary>=2.0.0
Description-Content-Type: text/markdown

# ScopeKit

🌐 **[scopekit.dev → john24alex.github.io/scopekit](https://john24alex.github.io/scopekit)**

**Stop paying for AI to read your entire codebase. Show it exactly where the bug is.**

Most token-saving tools (Graphify, etc.) build knowledge graphs with LLM API calls and vector databases. ScopeKit takes the opposite approach — **zero tokens, zero APIs, zero complexity.** Just a folder tree built from the filesystem and a focused prompt.

The insight: you already know roughly where the bug is. ScopeKit makes that knowledge explicit so the AI doesn't waste credits exploring irrelevant parts of your project.

---

## The problem

When debugging, AI assistants read the *entire* project to understand context — even if the bug is in one small feature. On large projects (1000+ files) this burns through credits in under an hour.

## The fix

```bash
scopekit
```

An interactive TUI shows your project tree. Select 2–3 folders in under 10 seconds. A scoped prompt is copied to your clipboard — paste it before describing the bug.

```
Only look at these folders:
  • lib/features/routines/player/
  • lib/core/services/

If you find references to code OUTSIDE this scope that are relevant
to the bug, let me know before expanding.

Do not read files outside the selected scope without asking me first.
```

Claude (or Cursor, or Copilot) reads only what matters. The bug gets fixed faster. Your credits last longer.

---

## Install

```bash
pip install scopekit
# or
uv tool install scopekit
```

## Usage

```bash
# Run in your project root
scopekit

# Specify a path
scopekit /path/to/project

# List saved presets
scopekit --list-presets

# Show version
scopekit --version
```

## How it works

```
 ┌────────────────────────────────────────┐
 │  🎯 ScopeKit  my-app · Flutter/Dart   │
 │                                        │
 │  Where is the bug?                     │
 │  > 🔍  Select specific folders         │
 │    ⚡  Load a saved preset             │
 │    📁  Entire project                  │
 └────────────────────────────────────────┘
```

1. **Select specific folders** — checkbox tree, indent shows depth
2. **Load a saved preset** — named scopes your team committed to the repo
3. **Entire project** — top-level folders only, still reduces noise

After selection the prompt is generated and copied to clipboard. Paste it into Claude Code, Cursor, or any AI assistant before describing the bug.

---

## Features

**Auto-detects project type** — Flutter, Node.js, Python, Rust, Go

**Presets** — save common debug scopes by name, stored as plain JSON in `.scope/presets/`. Commit them so the whole team benefits.

```bash
# First time: select folders → "Save as preset?" → name it "auth-flow"
# Next time:
scopekit   # choose "Load a saved preset" → "auth-flow"
```

**.scopeignore** — list folders to always exclude (one per line):

```
tmp
fixtures
legacy
generated
```

**No API keys. No LLM calls. No tokens consumed — ever.** Works with any AI assistant, any language.

---

## Philosophy

ScopeKit is intentionally minimal. The only dependency is `questionary` for the TUI. The filesystem is the data source. The developer is the intelligence. The AI is the tool — and tools work better when you give them clear constraints.

---

## Roadmap

- `/scope` slash command for Claude Code
- Auto-suggest scope from `git diff --name-only` (scope to recently changed files)
- VS Code extension
- Browser UI for teams

---

## License

MIT
