root/claude-smart-usage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add codebase scanner, CLAUDE.md init, and usage-focused workflow

Browse Source 
- ctc scan: runs linters/tests/type-checkers to find errors without
  burning AI tokens. Auto-detects Python, Node, Rust, Go projects.
- ctc init: drops a CLAUDE.md into any repo teaching Claude Code to
  work efficiently (chunk work, commit often, read scan results first).
- Updated README with the actual workflow: scan -> paste -> fix.

https://claude.ai/code/session_01Fzv8baXnEVVhnrffAb3Ucc
This commit is contained in:
Claude
2026-03-29 22:48:58 +00:00
parent 2d4ead1e3f
commit e211583214
4 changed files with 529 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+103 -63
View File
@@ -4,116 +4,156 @@ Break large coding tasks into self-contained chunks for efficient Claude Code se
## The Problem
You ask Claude Code to make a big change — add auth, refactor a module, migrate a database — 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.
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
`ctc` decomposes large tasks into independent, self-contained chunks. Each chunk is a complete prompt you can paste into a fresh Claude Code session. It includes just enough context for Claude to work without needing the prior conversation.
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 .
```
## Usage
## Quick Start: The Workflow
### 1. Plan — decompose a task
### 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 analyzes your codebase and creates a set of numbered chunks in `.claude-chunks/prompts/`.
### 2. Execute — one chunk at a time
This creates numbered prompt files in `.claude-chunks/prompts/`. Each one is a self-contained session:
```bash
# See what's next
ctc next
# Or copy it straight to clipboard
ctc next -c
# Paste the prompt into Claude Code and let it work
ctc next # see the next chunk's prompt
ctc next -c # copy it to clipboard
```
### 3. Track — mark chunks as done
Open Claude Code, paste the prompt, let it work, then:
```bash
ctc done 1
ctc status
ctc done 1 # mark chunk 1 complete
ctc next # get chunk 2
```
### 4. Repeat until the full task is complete
## Your Actual Workflow
Here's what this looks like day-to-day:
```bash
ctc next # get the next chunk
# paste into Claude Code
ctc done 2 # mark it complete
ctc next # and so on
```
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 standard phases: Research & Plan → Core Implementation → Tests → Integration & Cleanup. Best for most tasks.
```bash
ctc plan "Migrate from REST to GraphQL" -s phase
```
Breaks work into: Research & Plan -> Core Implementation -> Tests -> Integration & Cleanup.
### `component`
Groups work by directory/module. Best when changes are spread across independent components.
```bash
ctc plan "Add input validation everywhere" -s component
```
One chunk per top-level directory. Good when changes are spread across independent modules.
### `manual`
You define the chunks yourself in a text file, one per line.
You write a text file with one chunk per line:
```bash
```
# 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
Add frontend login/logout pages
```
```bash
ctc plan "Add user auth" -s manual --chunks-file chunks.txt
```
## Commands
| Command | Description |
|---------|-------------|
| `ctc plan <task>` | Decompose a task into chunks |
| `ctc status` | Show progress on current plan |
| `ctc next` | Print the next chunk's prompt |
| `ctc next -c` | Copy next chunk's prompt to clipboard |
| `ctc done <id>` | Mark a chunk as complete |
| `ctc show <id>` | Show a specific chunk's prompt |
## How It Works
1. **Analyzes** your codebase structure (languages, key files, directory layout)
2. **Decomposes** the task using the chosen strategy
3. **Generates** self-contained prompts with codebase context, targeted instructions, file lists, and verification steps
4. **Tracks** progress so you always know what's done and what's next
Each generated prompt tells Claude Code:
- What the codebase looks like (summary, not full contents)
- Exactly what to do in this chunk
- Which files to read and modify
- What depends on what
- How to verify the work is correct
## Tips
- **Start with `phase` strategy** — it works well for most tasks
- **Use `manual` for complex tasks** — you know your codebase best; write chunks that make sense for your architecture
- **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