An opinionated, semi-deterministic agentic tool. One declarative ProblemSpec in, a buildable, testable application out. By capitalizing on the modularity of Clean Architecture, Squeaky orchestrates atomic agents in parallel across compact, low-parameter models.
Small-parameter models frequently hallucinate, forcing engineers toward high-parameter alternatives where computational costs scale quadratically with context. Squeaky Clean is an opinionated, semi-deterministic agentic software development tool designed to break this cycle.
Squeaky Clean (or Squeaky) capitalizes on the modularity and granularity of Clean Architecture, SOLID principles, and GoF + DDD patterns. By doing so, it maximizes parallelization and wall-clock velocity while minimizing both the "hallucination blast radius" and operational costs.
The framework defines an Architectural DSL called Squib to orchestrate atomic, pattern-specialized agents that run efficiently on compact, low-parameter models. The Squib between tiers is a frozen, validated grammar (~200 chars per class, machine-checkable), ensuring the cheaper tier never has to guess what the more capable tier meant.
Clean, twice over. The same discipline that holds frameworks and databases at the edges also holds compute down: because each atomic agent sees only one class — a ~200-character Squib — the token volume runs on compact models, not one long context on a big one. LLM cost grows super-linearly with context (attention is O(n²)), so smaller contexts on smaller models mean measurably lower cost per run, and proportionally lower energy. Cutting the ecological footprint of AI-assisted development is a goal this open-source project is building toward — measured in tokens and cost today, not a carbon figure it claims.
# Install directly from GitHub
$ pip install git+https://github.com/garciaalan186/squeaky-clean.git
# Set your Anthropic API key
$ export ANTHROPIC_API_KEY="<your-key>"
# Install directly from GitHub via py launcher
> py -m pip install git+https://github.com/garciaalan186/squeaky-clean.git
# Set your Anthropic API key in PowerShell
> $env:ANTHROPIC_API_KEY="<your-key>"
# Clone and install in editable mode
$ git clone https://github.com/garciaalan186/squeaky-clean.git
$ cd squeaky-clean
$ pip install -e ".[dev]"
# Set your Anthropic API key
$ export ANTHROPIC_API_KEY="<your-key>"
SOLID, GoF, and DDD patterns are the shared vocabulary between agent tiers. The Dependency Rule is enforced by a real validator: domain imports nothing, application imports only domain, infrastructure implements domain ports. The framework's own source obeys every constraint it enforces on generated code.
Architects emit a multi-MODULE plan via the DSL, deploying one pattern-specialized atomic agent per file. By routing the vast majority of token volume to compact models—and reserving the larger tier strictly for architectural decisions—the framework builds distributed architectures in a single, high-velocity, low-cost parallel sweep.
Two services produce/consume the same Kafka topic? The Contract
Registry enforces field-shape agreement across language
boundaries with case-tolerant validation. The consumer's
ConsumedEvent carries the producer's contract field
names verbatim.
34 GoF + DDD patterns across four categories. The architect picks from this catalog when emitting a Squib; one atomic agent specializes in each pattern.
Squeaky includes a meta-evaluation framework to iteratively benchmark codegen performance against efficiency metrics, such as wall-clock velocity, cost, and artifact-token ratios.
Rather than relying on raw lines of code (LOC), it normalizes these metrics against a composite architectural complexity score that captures the structural, source (McCabe + Halstead), and constraint complexity of the output.
Squeaky Clean runs in both directions. Beyond generating from a
ProblemSpec, it points at an existing brownfield project
and rebuilds it as Clean Architecture: it ingests the code into a
faithful Squib, analyzes it for architecture violations,
lets you triage which to fix, refactors framework-coupled classes into
Entity + Repository + Adapter, and re-enters the standard generation
pipeline. Messy legacy code in, a freshly generated
Clean-Architecture project out — with human checkpoints in the middle.
Five phases, each persisted and independently re-runnable: Recover → Analyze → Triage → Refactor → Regenerate. A generic coupling detector flags ORM/Active-Record classes without indexing any framework (it allowlists the language standard library); a weighted trade-off analysis decides preserve vs split from architectural criteria you rank. Four-language ingest today — Python via a real AST walk, Java, JavaScript, and TypeScript via regex extractors — with Go and Rust to follow.
Tracked as Milestones L / M / N on the public roadmap. Read the docs: Agentic Architecture Recovery.