Skip to content
Paddock Paddock

Concepts

Short, canonical explanations of Paddock’s core ideas. Read these to understand what things are; read ../ARCHITECTURE.md to understand how the code fits together.

  • Projects — a directory + project.yaml; the two types, notebook and repo-backed.
  • Keeper vs. scratch agents — one keeper per project, one shared scratch, and how a scratch chat is promoted into a project.
  • Chats are Claude Code sessions — persisted on disk, resumable across reloads, reconnects, and devices.
  • The sweeper — the per-project, post-turn, tool-less agent that curates OVERVIEW.md and CHANGELOG.md.
  • Event hooks — run an agent turn when a lifecycle event fires (e.g. onArchive); its granted tools are its whole capability.

The one-sentence version: a project is a directory; its keeper is one Claude Code agent whose working directory is that directory; a chat is one resumable Claude Code session belonging to a project; and after each of your turns a sweeper quietly updates the project’s notes.