Content
# codesmell
Local CLI that turns a coding goal into ranked, token-budgeted repository context for AI agents.
```
agent → shell → codesmell JSON → agent reasoning
```
No daemon. No MCP. No network. Reads the local checkout, writes `.codesmell/` cache, exits.
## Usage
```sh
codesmell pack --root . --goal "fix refresh token bug" --budget 12000 --format json
```
All commands support `--format json` (agent contract) or plain terminal output (omit the flag).
| Command | Purpose |
|---------|---------|
| `init` | Bootstrap `.codesmell/` config and cache |
| `doctor` | Check local readiness |
| `map` | Repo structure, languages, public symbols |
| `search` | Ranked evidence for a query |
| `pack` | Budgeted context pack for a coding goal |
| `explain` | Deep-dive a file or symbol |
| `diff` | Changed files, symbols, risk hints |
| `test-plan` | Focused test suggestions |
| `review` | Deterministic findings with evidence |
## Agent Contract
`--format json` emits exactly one JSON object on stdout (`schema_version: "codesmell.agent.v1"`). Diagnostics go to stderr.
Key fields: `status`, `confidence`, `budget`, `coverage`, `guidance`, `evidence`, `findings`, `risks`, `test_hints`, `redactions`, `recommended_next`.
Status values:
- `ok` — actionable evidence, proceed.
- `partial` — evidence with caveats; run a follow-up before broad edits.
- `needs_refinement` — goal too broad; narrow via `recommended_next`.
- `error` — no evidence; check `warnings`.
Secrets are redacted before output. Only counts and kinds are reported — never raw values.
## Architecture
```
crates/
codesmell-cli clap commands, JSON/human output
codesmell-core domain types, config, errors
codesmell-facts language-neutral fact model, AST cache schema
codesmell-engine shared workspace analysis orchestration
codesmell-scan gitignore-aware walking, classification, fingerprints
codesmell-parse tree-sitter parsing, symbol/import extraction
codesmell-index lexical ranking, BM25-style scoring
codesmell-pack context budgeting, redaction, evidence selection
codesmell-review diff analysis, findings, test-plan
```
Rust is the only tree-sitter-parsed language today. Other languages are scanned and ranked lexically.
## Development
```sh
cargo build --workspace
cargo test
cargo fmt --check
cargo clippy --all-targets -- -D warnings
```
Run locally:
```sh
cargo run -p codesmell-cli -- pack --root . --goal "fix bug" --budget 12000 --format json
```
Test fixture: `tests/fixtures/rust-basic`. Integration tests synthesize ignored files, secrets, staged changes, renames, and mixed-language scenarios in temp repos.
Large-repo smoke (optional, ignored by default):
```sh
scripts/clone-bun-test-repo.sh
cargo test -p codesmell-cli core_commands_smoke_run_on_ignored_bun_test_repo -- --ignored
```
## Docs
Design and roadmap details live in [`docs/`](docs/):
- [`IDEA.md`](docs/IDEA.md) — product vision and positioning
- [`AST_ENGINE_DESIGN.md`](docs/AST_ENGINE_DESIGN.md) — engine internals and tree-sitter strategy
- [`ROADMAP.md`](docs/ROADMAP.md) — milestone tracking
- [`TGREP_DESIGN.md`](docs/TGREP_DESIGN.md) — tgrep relation-search design
- [`TGREP_ROADMAP.md`](docs/TGREP_ROADMAP.md) — tgrep milestones
MCP Store