Behaviour
How CLIs, agent tools, progress, status and notifications behave, so every tool works alike.
The parts that aren’t pixels. A new system follows these, and the cli-tool template shows each one working.
CLIs
- One Effect CLI tree per system. The same tree feeds the CLI, Code Mode and MCP, so a new command reaches all three at once.
- Every command that returns data takes
--json, which is the agent interface. - When there’s nothing to do, say so in one line and exit 0.
- Choices are a multi-select with the sensible ones ticked, and Enter runs them.
--yes,--jsonor no terminal skips the picker. - Long runs print numbered sections with one line each (
[3/7] mise tools) and stream as they go. --checklists what would change without changing anything;--forceskips the check.- Help, completions and a generated reference come from the tree.
- Plain output uses the terminal’s 16 ANSI colours and respects
NO_COLOR.
Agents
Every system gets the same agent surface:
| Surface | What it is |
|---|---|
| Code Mode | A manifest from <tool> agent tools --json, the shape dot already prints |
| MCP | A server on stdio from the same operations |
| Skill | A tool-owned skill in the repository’s skills/ |
Each operation has one access class, which decides how agents may use it:
| Access | Code Mode | MCP |
|---|---|---|
| Read | Read | A read-only tool |
| Write | Write | A tool |
| Ask every time (fixes, anything destructive) | Write, always asks | A tool marked destructive |
| Power (reboot, shut down) | Write, always asks | Left out unless the server starts with --allow-power |
Long commands run as jobs only, so an agent starts them and comes back for the result.
Status and notifications
- One status source per system, as
dot updates status --jsonis for updates. The bar widget, the OpenCode footer, the CLI and the panel all read it, so each shows the same counts. - The bar counts what needs you, and hides in quiet hours.
- Toasts only for something new that needs you. Nothing for green runs.
- Decisions go to the Plannotator Inbox; reviews go through Plannotator, not GitHub.