Pithy is agent-drivable

The contract

Driving the CLI from an agent is the worked session, driving your AI with docs is how it learns the flags, --json and exit codes is the machine surface, and the CLI is what a human reads.

In Claude Code, the pithy plugin organizes the work into a team — a server, a web client, a mobile client and a runner — built on everything below. For a game, pithy-games adds a Unity client, game design and playtests on top of it.

Operating a live app

Everything on this page is about building. Once your app is deployed, an agent can reach it in two more ways, and they are not the same thing.

An agent you connect administers it. pithy mcp registers the agent’s own connection to one environment, under a key on your machine or, in CI, the job’s own identity with no key at all, and serves your Worker’s admin routes to it as tools. Every call is a control-plane call: one scope, checked and audited by your Worker as an agent’s.

Your users’ agents act as them. Letting your users’ agents in composes mcp(), which serves /mcp on your own Worker. A user approves an agent on your origin, and it calls your routes with that user’s role and nothing more.

And pithy.sh/mcp is neither. It is the docs server, which answers questions about the kit. pithy mcp serve is also the one command with no --json: its stdout is the protocol.

Every command is agent-drivable and supports --json.

One deliberate exception: pithy remove is destructive, so it is manual and interactive-only. Passing --json, --no-input or PITHY_NONINTERACTIVE=1 fast-fails with core/person_required, exit 5, before anything changes.

Its confirmations are typed at a real terminal, and there is no headless path. Automated teardown of an ephemeral environment is a different command — the feature lifecycle, not remove.

--json is one object, on stdout

Machine-readable, on stdout, and nothing else on it. A pipe gets one compact line. A terminal gets the same document indented, and PITHY_JSON=compact keeps it on one line for the whole session. Every payload carries schemaVersion, which moves only when a change would break a parser.

Color detection is decided once from the environment rather than by a library that reads any CI variable as color-capable — because our output is parsed, and a CI runner finding ANSI inside --json is the bug that produces.

deploy and provision also take --json --events. A long run then writes one progress record per line, closed by the same document --json alone writes, so an agent watching it can tell a slow run from a hung one.

The payload is specified where the command is

Every command page carries the same six sections — synopsis, flags, what it does, --json, errors, examples.

And a build gate holds each page to naming every key its command’s --json payload emits. A page that describes a payload it does not have fails the build rather than misleading an agent.

pithy schema --json describes the installed binary — every command, flag, payload and error code, and whether a command changes anything. An agent reads that rather than guessing at a flag.

Ambiguity is refused, not guessed

A multi-Worker project prompts a human. A run that may not ask — --json, --no-input or PITHY_NONINTERACTIVE=1 — fails input/required instead, naming the flag and the Workers it takes, rather than picking one.

Wiring a capability into the wrong Worker would put its bindings, its routes and its migrations somewhere nobody asked for — so the command stops and names what it needs.

The same rule holds for pithy dashboard connect: several Workers means --worker <name>, and a Worker composing no control plane is refused outright.

What is safe to run repeatedly

Every provision is idempotent — find-then-create, create-then-update, a deploy that overwrites. Re-running is a no-op.

pithy worker sync touches no account and runs no deploy. Safe on any branch, at any time, as often as you like. Running it twice changes nothing and writes nothing.

pithy migrate is a registry run, and a database already at the head is a no-op.

--dry-run plans before anything changes. add, ui add, provision, migrate, deploy and the other commands that take it write nothing, make every refusal the real run would, and share one plan shape under --json.

What needs a human

pithy remove, as above.

Production provisioning takes a type-to-confirm phrase that --yes never replaces.

A supplied secret — an OAuth client secret, a payment rail’s key — stops provisioning, because a random string there authenticates against nothing.

Nothing prints a secret

No minted value is printed, logged, or put in an audit event by any command.

Which matters most to an agent, because an agent’s transcript is a log, and a log is forever.

Exit codes mean something

Read the code, not the text. pithy doctor in particular distinguishes a step you have not taken yet from drift you should act on — a project with no domain and nothing provisioned is not red on day one, because turning the report red for everybody on day one teaches people to ignore it.

A failure exits by its kind, so the code says what to do next:

ExitMeansDo
1An unclassified failureRead the error
2A usage or validation errorFix the call
3A precondition is unmetRun the fix the error line names
4An upstream or transient failureRetry with backoff
5It needs a personStop and ask

Test for non-zero, not for 1. Most failures are no longer 1. Under --json the error line carries exit, retryable, and a fix command when the cause is known.

ESC