claude-smart-usage/README.md

# Claude Task Chunker (`ctc`)

Break large coding tasks into self-contained chunks for efficient Claude Code sessions. Stop running out of usage mid-task.

## The Problem

You ask Claude Code to make a big change — add auth, refactor a module, fix errors across a 10,000-line codebase — and it runs out of usage halfway through. You're left with half-finished work and no easy way to pick up where you left off.

## The Solution

Two things working together:

1. **`ctc scan`** — Runs linters, tests, and pattern matching on your codebase *without using any AI tokens*. Finds the errors so Claude doesn't have to read 10,000 lines to find them itself.
2. **`ctc plan`** — Breaks big tasks into self-contained chunks with ready-to-paste prompts for Claude Code.
3. **`ctc init`** — Drops a `CLAUDE.md` into your repo that teaches Claude Code to be usage-efficient automatically.

## Install

```bash
# Clone this repo, then:
pip install -e .
```

## Quick Start: The Workflow

### Step 1: Set up your project (one time)

```bash
cd /path/to/your/big-project
ctc init
```

This creates a `CLAUDE.md` in your project that teaches Claude Code to work efficiently — chunk its own work, commit often, and not waste tokens exploring.

### Step 2: Find errors fast (no AI needed)

```bash
ctc scan
# or with a specific focus:
ctc scan "authentication is broken"
```

This runs your project's linters, tests, and type checkers automatically. It detects what kind of project you have (Python, Node, Rust, Go) and runs the right tools. The output goes to `.claude-chunks/scan_results.md`.

### Step 3: Open Claude Code and paste the results

Open Claude Code connected to your repo as normal. Then:

```
Fix the errors in .claude-chunks/scan_results.md
```

Claude reads the pre-scanned results and goes straight to fixing — no wasted tokens reading 10,000 lines to find the bugs.

### Step 4: For big tasks, plan chunks first

```bash
ctc plan "Add OAuth2 authentication with login, logout, and RBAC"
```

This creates numbered prompt files in `.claude-chunks/prompts/`. Each one is a self-contained session:

```bash
ctc next       # see the next chunk's prompt
ctc next -c    # copy it to clipboard
```

Open Claude Code, paste the prompt, let it work, then:

```bash
ctc done 1     # mark chunk 1 complete
ctc next       # get chunk 2
```

## Your Actual Workflow

Here's what this looks like day-to-day:

```
You:     cd my-big-project
You:     ctc scan                          # 10 seconds, finds 3 errors
You:     [open Claude Code]
You:     "Fix the errors in .claude-chunks/scan_results.md"
Claude:  [reads the file, fixes the 3 errors, done in one session]
```

For big features:

```
You:     ctc plan "migrate database from MySQL to Postgres" -s phase
You:     ctc next -c                       # copies chunk 1 prompt
You:     [open Claude Code, paste]
Claude:  [does chunk 1: research & plan, commits]
You:     ctc done 1
You:     ctc next -c                       # copies chunk 2 prompt
You:     [paste into Claude Code — same session or new one]
Claude:  [does chunk 2: core implementation, commits]
You:     ctc done 2
         ... and so on
```

## Commands

| Command | What it does |
|---------|-------------|
| `ctc init` | Add CLAUDE.md to your project (teaches Claude to be efficient) |
| `ctc scan` | Find errors with linters/tests (no AI tokens used) |
| `ctc scan "description"` | Same, but adds your description to the output prompt |
| `ctc plan <task>` | Break a big task into chunks |
| `ctc plan <task> -s component` | Chunk by directory/module instead of phase |
| `ctc plan <task> -s manual --chunks-file chunks.txt` | Use your own chunk list |
| `ctc status` | See progress on current plan |
| `ctc next` | Print the next chunk's prompt |
| `ctc next -c` | Copy it to clipboard |
| `ctc done <id>` | Mark a chunk as complete |
| `ctc show <id>` | View a specific chunk's prompt |

## What `ctc scan` Detects

It auto-detects your project type and runs the right tools:

| Project | What it runs |
|---------|-------------|
| **Python** | pytest, ruff, mypy, syntax check |
| **Node/TypeScript** | npm/yarn test, eslint, tsc --noEmit |
| **Rust** | cargo check, cargo test --no-run |
| **Go** | go build, go vet, go test |
| **Any** | grep for TODO/FIXME/HACK/BUG markers |

## Decomposition Strategies

### `phase` (default)
Breaks work into: Research & Plan -> Core Implementation -> Tests -> Integration & Cleanup.

### `component`
One chunk per top-level directory. Good when changes are spread across independent modules.

### `manual`
You write a text file with one chunk per line:

```
# chunks.txt
Set up database models for users and roles
Build registration and login API endpoints
Add JWT middleware and session management
Build role-based access control decorators
```

```bash
ctc plan "Add user auth" -s manual --chunks-file chunks.txt
```

## Tips

- **Always `ctc scan` before asking Claude to fix errors** — saves huge amounts of usage
- **`ctc init` once per project** — the CLAUDE.md stays in the repo and works every session
- **Keep chunks independent** — the less each chunk depends on others, the cleaner the handoff
- **Add `.claude-chunks/` to `.gitignore`** — it's working state, not source code
- **Commit CLAUDE.md to your repo** — it benefits every Claude Code session in that project