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.

• Workspaces — the nesting: a project can contain projects, and every project is also a workspace you can open on its own.
• Projects — a directory + project.yaml, described by two independent axes: a derived managed flag (whether Paddock curates the metadata) and where the content lives (path and/or repo).
• Agents — one keeper agent per project (the root included), plus the sweeper and one agent per trigger, and how a chat is promoted into a project of its own.
• 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; Paddock runs one Claude Code agent whose working directory is that project’s workingDir — the project directory itself, a nested checkout, or a directory you nominated with path; 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.