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.
• Schedules — durable cron/interval turns that fire when nobody is watching; each firing lands as its own chat.
• Event hooks — run an agent turn when a lifecycle event fires (e.g. onArchive); its granted tools are its whole capability.
• Provenance: who did what — how a chat records whether a human, a schedule, or another agent started it, and per-message attribution for machine-injected turns.
• The sweeper — the per-project, post-turn, tool-less agent that curates OVERVIEW.md and CHANGELOG.md.

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; schedules and hooks start those sessions without you; provenance records who did; and after each turn a sweeper quietly updates the project’s notes.