Metadata-Version: 2.4
Name: smartctx
Version: 0.2.0
Summary: Smart context manager for AI coding assistants — saves millions of tokens by building a local memory of your project
Author-email: Abdullah Butt <asohailbutt34@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://www.npmjs.com/package/smartctx
Project-URL: Repository, https://github.com/Abdullahbutt-143/smartctx
Keywords: claude,claude-code,context,ai,tokens,codex,cursor,copilot,developer-tools,smartctx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: anthropic>=0.30.0
Requires-Dist: click>=8.0.0
Requires-Dist: pathspec>=0.11.0
Requires-Dist: python-dotenv>=1.0.0

# smartctx 🧠

> Save millions of tokens per day by giving AI coding assistants smart, curated context instead of your whole codebase.

## The Problem

Every time you start a Claude Code / Cursor / Copilot session, it reads your **entire project** — hundreds of files, thousands of lines. That's hundreds of thousands of tokens, every single session.

## The Solution

**smartctx** builds a local memory of your project once, then gives AI tools only the files relevant to your current task.

```
Without smartctx:  Claude reads 500 files = ~800,000 tokens per session 😬
With smartctx:     Claude reads 8 files   = ~12,000 tokens per session  ✅

Savings: ~98% token reduction
```

## Install

```bash
# npm
npm install -g smartctx

# pip
pip install smartctx

# Homebrew (macOS/Linux)
brew tap Abdullahbutt-143/smartctx
brew install smartctx

# Scoop (Windows)
scoop bucket add smartctx https://github.com/Abdullahbutt-143/scoop-smartctx
scoop install smartctx
```

## Quick Start

```bash
# 1. Set your API key (one time, saved globally)
smartctx config --api-key sk-ant-xxxxx

# 2. Initialize your project (one-time scan)
cd your-project
smartctx init

# 3. Before each AI session, query for your task
smartctx query "add authentication middleware"
# → generates CLAUDE.md with only the relevant files

# 4. Start Claude Code — it reads the lean CLAUDE.md
claude
```

## Commands

| Command | Description |
|---------|-------------|
| `smartctx init` | First-time setup — scans and summarizes all files |
| `smartctx sync` | Refresh changed files only (run daily/weekly) |
| `smartctx query "task"` | Generate lean context file for your task |
| `smartctx status` | Show index stats |
| `smartctx config` | View/set configuration |

## Multi-AI Support

```bash
smartctx query "add auth" --for claude    # → CLAUDE.md
smartctx query "add auth" --for cursor    # → .cursorrules
smartctx query "add auth" --for copilot  # → .github/copilot-instructions.md
smartctx query "add auth" --for codex    # → AGENTS.md
```

## How It Works

1. **`init`** — Scans your project, calls Claude Haiku (cheapest model) once per file to generate a summary. Saves everything to `.smartctx/index.json` locally.

2. **`sync`** — Detects changed files (by modification time) and only re-summarizes those. Free for unchanged files.

3. **`query`** — Runs a **local** keyword search (zero API cost) over your summaries. Finds the top 10 most relevant files. Generates a lean context file.

4. **AI Session** — Your AI tool reads a 5-15k token context file instead of your 500k+ codebase.

## Cost

- **Init**: ~$0.0004 per file (Claude Haiku pricing) — a 100-file project costs ~$0.04 total
- **Sync**: Only pays for changed files — usually free
- **Query**: $0.00 — runs locally
- **Daily use**: $0.00

## Works With

- ✅ Node.js / TypeScript projects
- ✅ Python projects
- ✅ Go, Rust, Java, any language
- ✅ Any file-based project

## Configuration

```bash
smartctx config --api-key sk-ant-xxxxx    # Set API key
smartctx config --target cursor           # Default output format
smartctx config --schedule weekly         # Reminder schedule
```

## .gitignore

Add `.smartctx/` to your `.gitignore` (it's project-specific local data):

```
.smartctx/
CLAUDE.md
```

## License

MIT
