FeaturesHow It WorksPricingDocsInstallContact UsGitHub

Parton CLI is in early alpha

Things may break or change between releases. We don't recommend using Parton on production projects yet. If you run into anything unexpected, we'd genuinely appreciate your feedback — it helps us make Parton better for everyone.

How Parton Works

Parton is a local-first AI code execution engine.

It takes an intent, scans the project with tree-sitter, plans strict per-file contracts, scaffolds config files, executes logic files in parallel, checks structure, validates the result, and auto-fixes failures.

Pipeline overview

Intent
→ Setup gate
→ Code Graph (tree-sitter scan)
→ Clarify (graph-aware)
→ Plan (graph-aware)
→ Scaffold + Enrich (parallel)
→ Structure Check
→ Final Execution (parallel)
→ Validation + Auto-fix

1. Setup gate

Before Parton can do any AI work, it must confirm that model access is configured.

If setup is missing, it blocks the run and launches the setup TUI.

2. Code Graph

Before any LLM calls happen, Parton scans the entire project using tree-sitter Wasm and builds a symbol graph.

This extracts:

  • Symbols — functions, types, classes, constants across all files
  • Exports and imports — real module-level dependency graph
  • Key file snippets — the first 25 lines of auth, middleware, schema, and permission files

The graph summary is passed to both the clarifier and planner, so they understand your project's real structure, conventions, and import paths.

Parton supports 11 languages via tree-sitter Wasm: TypeScript, JavaScript, Rust, Python, Go, Java, C, C++, Ruby, PHP, and Kotlin. Grammars are downloaded lazily to ~/.parton/grammars/ on first use. Unsupported languages fall back to regex-based analysis.

3. Clarify

If your request is ambiguous, Parton asks a small number of clarification questions before planning. The clarifier is graph-aware — it no longer asks about things visible in the code (auth mechanism, database, framework) and only asks about business requirements that cannot be inferred from the code graph.

This is especially important for:

  • greenfield tasks
  • vague prompts
  • tasks with multiple valid implementation paths

4. Plan (skeleton)

Parton converts your request into a structured plan with strict per-file contracts. The planner is graph-aware — it sees real import paths, existing module exports, and uses actual project conventions detected from the code graph. If the plan says Create but the file already exists on disk, it is automatically corrected to Edit.

The planner decomposes the task into individual file-level tasks, each with:

  • Goal — what the file must accomplish
  • Exports — exact function signatures, type shapes, and interfaces the file must provide
  • Imports — what the file should consume from other planned files
  • Context — relevant existing code the agent needs to see

The plan also includes:

  • install_command — dependencies to install (e.g. npm install express)
  • check_commands — commands to verify project structure after scaffold
  • validation_commands — commands to validate the final result (build, lint, test)
  • scaffold_only flag — marks files that are finalized during scaffold (config files like tsconfig.json, package.json) and do not need re-generation during execution

Use --review to pause and inspect the plan before execution begins.

5. Scaffold + Enrich (parallel)

Parton splits execution into two tracks:

Scaffold

Files marked scaffold_only in the plan (typically config and project files) are generated first and written to disk immediately. These files are final — they do not get re-generated later.

After scaffold, Parton runs the plan's install_command to install any dependencies.

Enrich

Logic files are generated in parallel. Each file gets its own LLM call with:

  • the file's goal and contracts
  • relevant context from the scaffold output
  • imports and exports from the plan

All enrichment calls run simultaneously.

6. Structure Check

After scaffold and enrich complete, Parton runs the plan's check_commands to verify the project structure is correct before proceeding to final execution.

7. Final Execution (parallel)

All remaining logic files are generated simultaneously:

  • each file gets its own LLM call with goal, contracts, and context
  • all files execute in parallel
  • output is parsed deterministically

8. Validation + Auto-fix

After files are written, Parton runs the plan's validation_commands on the full project.

This typically includes:

  • build or typecheck
  • lint
  • test suite

If validation fails, Parton automatically re-generates the failing files with the error context included. This auto-fix loop continues until validation passes or the retry limit is reached.

Greenfield vs existing repo

Existing repo

Parton modifies an existing codebase. Analysis happens automatically — there is no separate analyze command. The planner uses the project structure and existing code to inform the plan.

Greenfield

If the directory is empty or does not contain a meaningful project structure, Parton switches into greenfield mode and scaffolds a full project from scratch.

Per-stage models

Parton supports different models for different pipeline stages:

  • Planning — benefits from strong reasoning
  • Execution — benefits from fast, accurate code generation
  • Judge — handles validation and auto-fix decisions

You can mix providers (e.g. Claude CLI for planning, OpenAI API for execution, Ollama for judge). See Setup & Model Access for configuration details.

What Parton is optimized for

  • Local-first usage
  • Strict contract-driven planning
  • Maximum parallel execution
  • Scaffold-first architecture (config files are final early)
  • Auto-dependency installation
  • Validation-backed output with automatic repair
  • Model-agnostic, provider-agnostic execution

Related