picassodocs
docs/09-hooks-and-commands.md

09 — Hooks and Commands

Extension surfaces that let users customize agent behavior without forking the codebase. Hooks fire at well-defined transitions in the loop. Slash commands extend the TUI's keyboard surface. User-defined commands compose tools into named workflows. The agent's behavior should never be opaque or unmodifiable.

Hooks

On the CLI path hooks are advisory: they observe tool calls but cannot block one (the fireHook pre-act/post-act seam of the engine adapter). The blocking in-runtime bridge mounts only in the Mac relay.

Slash commands

The TUI and the Mac share one registry of 83 slash commands, packages/commands/command-manifest.json; the full list with usage is in 10-tui.md. /hooks list|add|enable|disable|remove|test|validate [id] and picasso hooks manage shell hooks. /init (and picasso init) writes PICASSO.md and names only the skills installed for you, from the project and home skill roots.

Skills

picasso skills add <source> installs a skill from a GitHub URL, owner/repo or a local git path (it shows the plan first; --yes installs), picasso skills remove <name> removes it, picasso skills scan lists what is installed, and picasso skills import <path> brings in a skill directory. In the TUI, /skills add <owner/repo>; on the Mac, Extensions › Add skills. In the composer, $ opens a skill picker that inserts /<skill-name> .

Schedules

Local schedules message a thread or start a new one, once or repeating. You can create, edit, pause, resume and delete them, see their history, and missed runs are reported until you dismiss them. Schedules need a runner: Picasso for Mac while it is open, or the resident runner (Settings › General › "Keep threads running when Picasso quits", or picasso service install).

Runtime note

Picasso slash commands come from Picasso's own manifest; the engine's interaction commands and its Claude Code/Codex-style hook bridge apply underneath. See architecture.