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

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).

Related MCP server: agendum

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

cargo build --workspace
cargo test
cargo fmt --check
cargo clippy --all-targets -- -D warnings

Run locally:

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):

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/:

• IDEA.md — product vision and positioning

• AST_ENGINE_DESIGN.md — engine internals and tree-sitter strategy

• ROADMAP.md — milestone tracking

• TGREP_DESIGN.md — tgrep relation-search design

• TGREP_ROADMAP.md — tgrep milestones