Prompt an agent remotely.

Prompt the agent

prized prompt --provider claude "fix the failing tests in app/ and run them again"

This starts a headless run of Claude Code on the box (claude -p, in your home directory), streams its events to your terminal, and exits when the agent is done. Nothing runs in a tmux session; the first prompt installs three small helper scripts on the box and nothing else.

• Output: the agent's text plainly, each tool call and result as one dim line, and a last line with the run's verdict and event count; -v adds the provider's system events.
• Exit code: 0 when the run ends cleanly, 1 when the provider reports an error, exits non-zero, or the run was interrupted, 130 on Ctrl-C, which also interrupts the run on the box (prized events --follow leaves the run alone on Ctrl-C).
• The prompt travels to the box as a file, never on a command line, so it is not in the box's process list or shell history. A suspended box wakes for prized prompt; prized events, prized prompt ls and prized interrupt do not wake one.

Sign in first

The agent runs as you, on the box, with the sign-in already there: hand your credentials over once with prized agents handoff claude codex. prized prompt refuses with provider_not_signed_in when the box has no sign-in for the provider (Claude Code: ~/.claude/.credentials.json or CLAUDE_CODE_OAUTH_TOKEN in a login shell; Codex: ~/.codex/auth.json). What travels is in Credentials; the interactive alternative is Agents.

Approvals

By default the agent can edit files but not act freely: Claude Code runs with --permission-mode acceptEdits (commands it wants to run are denied, since a headless run cannot ask you), and Codex runs in its workspace-write sandbox. --auto lifts both (claude --dangerously-skip-permissions, codex --dangerously-bypass-approvals-and-sandbox), which is what "run the tests and fix them" needs.

--auto means no approvals at all: the agent runs any command and edits any file your account on the box can, with your credentials and synced projects in reach. Use it for work you would let the agent do unattended, and interrupt it when it strays.

Continuity

Every run records the provider's session id, and --continue starts the next run with --resume <that id> (Claude Code) or codex exec resume <id> (Codex), so "now also update the docs" works; the newest session of the same provider on the box is the one continued, and prized prompt ls --json shows each run's sessionId and resumedFrom. With no earlier session on the box, --continue refuses (exit 5, no_session_to_continue on the API) rather than quietly starting fresh.

One run at a time, and a queue

A box runs one prompt at a time. A second prized prompt while one is in progress answers prompt_in_progress; with --queue the text is queued and runs as soon as the current run ends, continuing its session. Two commands on the box itself do the same, so a setup script or any shell there can drive the agent:

queuePrompt "then run the linter and fix what it finds"
stopAgent

queuePrompt appends to the queue (from its arguments, or stdin); stopAgent interrupts the run in progress. Both live in ~/.prized/bin, on the PATH of login shells after the first prompt. A queued prompt with no run in progress waits for the next prized prompt to finish; an interrupted run does not drain the queue.

A prompt queued with --queue keeps its own provider, model, effort, working directory and --auto; one queued with queuePrompt inherits them from the run it follows. A queued prompt of the same provider continues the session of the run it follows (with --continue, the provider's newest session when it runs); a different provider starts fresh.

Where a run lives on the box

Everything about a run is a directory on the box, so it survives a pause, rides a snapshot, and can be read with ls and tail -f:

~/.prized/prompts/active names the run in progress; ~/.prized/prompts/queue/ holds queued prompts, one directory each.

Run directories are never deleted for you. rm -r ~/.prized/prompts/pr_… on the box when you are done with one.

JSON and JSON Lines

--json on prized prompt prints the started run as one object and does not follow. --jsonl follows and prints one normalized event per line: this is the one command, with prized events --jsonl, that prints more than one JSON document, because a live stream has no end to wait for.

{"seq": 7, "type": "tool_use", "text": "Let me run the suite.", "tool": {"name": "Bash", "input": {"command": "npm test"}}, "raw": {…}}

A run object (prized prompt --json, prized prompt ls --json, prized events --json) has id, provider, model, reasoningEffort, auto, status (running, done, failed, interrupted), exitCode, pid, cwd, startedAt, finishedAt, sessionId, resumedFrom, parent, eventCount, prompt.

The edge API

The same surface is HTTP for scripts that hold a CLI token: POST /prompts starts or queues a run, GET /prompts lists them, GET /prompts/{runId}/events pages the events or streams them as Server-Sent Events (follow=1, or Accept: text/event-stream; a stream holds one of the token's concurrent request slots until the run ends), and POST /prompts/{runId}/interrupt stops one. Every route is under $EDGE/v1/box/{box}/ with the token as the bearer, found as for running commands; only POST /prompts wakes a suspended box. Routes, bodies and answers are on API reference: Prompts and events.

Errors

A failed request answers {"ok": false, "error": {"code", "message"}}. On top of the shared edge codes, these routes add invalid_provider, prompt_required, invalid_request, prompt_in_progress, provider_not_signed_in, provider_not_installed and no_session_to_continue, described on API reference: Errors. From the CLI a run in progress is exit 6 (CONFLICT) and the rest exit 5 (CHECK_FAILED) with the hint.

Limits

Every cap for prompts, runs, and events is on Limits.

Compared with prized agents run

prized agents run starts the agent interactively in a tmux session you attach to and approve things in. prized prompt is the headless form: one prompt in, a stream of events out, a verdict at the end, and an API for scripts. Both use the same sign-in on the box and keep working when your laptop is closed.