Skip to main content

Paddles, Explained

Paddles is a recursive in-context planning harness for local-first coding agents. It wraps HTTP model clients in a structured loop that lets them investigate a workspace iteratively instead of answering in one shot.

The result: a smaller model hosted behind a local HTTP service can use bounded tools and recursive evidence gathering instead of answering from memory alone.

What The Harness Does​

Paddles gives the selected model client three things it cannot provide for itself:

  • Operator context — project conventions, guidance, and priorities loaded from AGENTS.md memory files before the model sees the prompt
  • Recursive investigation — a bounded loop where the model searches, reads, refines, and branches until it has real evidence from the workspace
  • Structured final rendering — a separate rendering step that produces a grounded answer from the accumulated evidence, not from the model's training data

These are not plugins or prompt tricks. They are architectural commitments that change what a small model can accomplish.

How A Turn Works​

Every interaction follows the same cycle:

  1. Interpret — load operator memory, derive a guidance graph, assemble tool hints and procedures
  2. Classify — the model classifies the prompt as casual, direct, deterministic, or planned
  3. Select actions — for planned turns, a recursive loop lets the model search, read, and refine until evidence is sufficient
  4. Render — a separate model call produces the final answer from the evidence bundle
  5. Record — every step is captured as typed trace records with stable ids for replay

The action-selection and final-rendering clients can be different models. The best recursive investigator is not always the best answer writer.

If you are brand new:

  1. Install Paddles and verify the CLI.
  2. Run your first turn in interactive mode.
  3. Read the concept pages when you want the model behind the architecture.

If you want the architecture:

  1. Turn Loop — the full cycle from prompt to answer
  2. Recursive Planning — how recursive action selection works
  3. Search and Retrieval — how evidence queries work, constraints, and telemetry
  4. Context Tiers — how context spans inline, transit, and filesystem
  5. Steering Signals — how truncation and recursive guidance are tracked and surfaced
  6. Model Routing — how action-selection and final-rendering roles are assigned