agent-cli

1# Agent CLI
2 
3Give the app a command line, so an agent can do everything a person can
4do in the window: `tasks items add --title "Call the dentist"`. The app
5binary is the CLI. Each command goes to the running app over a private
6socket, runs there like a button press, and the window updates live.
7 
8```text
9Claude Code --bash--> tasks items add ...  --socket--> Tasks.app (runs the command, saves, redraws)
10Claude Desktop --MCP--> tasks mcp           --socket--> same commands, same app
11```
12 
13## CLI, MCP, or App Intents
14 
15| Way in | Who uses it | Ship it |
16| --- | --- | --- |
17| CLI | Claude Code, Codex, scripts, people in Terminal | Always. Agents learn it from `--help`, and it costs no context until used |
18| MCP (`tasks mcp`) | Claude Desktop and other clients with no shell | Optional. The same commands, one tool each. One line to register |
19| App Intents | Siri, Spotlight, Shortcuts | Separate work. Agents cannot call them |
20 
21The CLI talks to the running app, never to the database file. Then there is
22one writer, the app's checks and side effects run, and the window shows the
23change at once. If the app is closed, the CLI opens it in the background.
24Rules and reasons: [rules.md](rules.md).
25 
26## 1. List the commands
27 
28Read the user stories (`docs/stories/`). Write each thing a person does as
29a command, `<noun> <verb>`, and mark it:
30 
31- **read**: `items list`, `items show`, `status`. Safe to run any time.
32- **write**: `items add`, `items update`, `open`. Changes data, can be undone.
33…