Claude Code

Claude Code needs nothing installed — the CLI runs via npx. This is the whole path in the order an agent walks it, for the human wiring it up and for the agent reading it cold. The contract behind every step is GET https://api.pidge.sh/api/v1/manifest; the condensed agent version is api.pidge.sh/agent-setup.

You rarely do this by hand

Paste the setup prompt from the app into your agent and it walks this path itself. This page is what it does, so you can check it — and what to type when you’d rather drive.

1. Set up, once

In the app, create a channel and tap Copy setup prompt — a single-use claim code (15-minute TTL), never the key. Run it inside your project:

npx -y pidge-cli@latest setup --claim <code> --url https://api.pidge.sh
npx -y pidge-cli@latest doctor

setup writes the key (mode 600) scoped to this git project, the skill (.claude/skills/pidge/SKILL.md + AGENTS.md) and, under Claude Code, a SessionStart hook running pidge presence — one line telling a fresh session whether the watch is up. Safe to re-run inside the TTL. Two agents in one directory: PIDGE_AGENT=<id>, sticky for every later command. doctor validates without exposing secrets.

2. First contact

npx -y pidge-cli@latest hello

The debut on a fresh channel: a 3-stage Live Activity narrates it on the lock screen and the command blocks up to two minutes for the tap. A timeout exits 3 — normal; the tap stays in your queue. Inheriting a channel? Skip hello: npx pidge-cli whoami shows the agent_handoff baton, npx pidge-cli catchup --digest shows the thread without consuming anything.

3. Learn the human

Before the first real send, read GET /api/v1/preferences (notes other agents left: tone, quiet hours, formats) and whoami → notify_contract + channel.default_profile. Advice you honor voluntarily; the channel’s ceiling is what the server enforces.

4. Declare how you stay reachable

npx pidge-cli contract set listen_mode=persistent   # turn_based = one round at a time · external_daemon = a stand-in

Advisory: the human sees declared vs observed, and a different expectation they register comes back as operating_contract_ignored plus a system message on your queue.

5. Stay on the line

The human expects to reach the session they are working with, like a chat. Under Claude Code that is a session-length watch the harness owns — the Monitor tool, persistent, no deadline:

npx pidge-cli online --follow --ndjson --timeout 0

One message per stdout line (type: message · notification_reply · system; batch_end closes a batch). Handle it, reply through npx pidge-cli message — never stdout — run npx pidge-cli typing first when you will take more than ~15 s, and only then npx pidge-cli ack --up-to <id> --summary "<what you did>". Being served is the gray ✓✓; your ack is the green one; un-acked rows re-serve in ~10 min. While the watch runs the human sees listening now; when the session ends they see you offline and their messages wait.

No Monitor tool? One round at a time as a background task your harness tracks (never a loose &), relaunched when it exits: npx pidge-cli online. A stand-in — another agent answering in your place — is opt-in: npx pidge-cli bridge install --handler claude --enable, only when your human asked for one. Details: Waiting & receiving.

6. Send at the finish line

# done, no decision needed:
npx pidge-cli important --title "Migration finished" --body-markdown-file summary.md

# done, needs a call:
npx pidge-cli ask --title "Tests green. Ship it?" --actions yes,no --timeout 14400

Exit 3 means “no answer yet” — re-wait on the correlation id (first stderr line) instead of re-sending. A message the human types while ask blocks prints as kind: "human_message": handle, ack, re-wait. action_id: "done" = cleared without deciding, not an approval. Group a topic with --thread <id>; rewrite one status card with --collapse-key <key>.

7. Gate risky tool calls

pidge approve is a deny-default exit-code gate for a PreToolUse hook — Face ID on your phone before Claude runs a migration or touches prod. Recipe: Approval gates.

8. Prove it

npx pidge-cli selftest              # PASS only if a live listener picks the nonce up and acks it
npx pidge-cli selftest --window 120 # up to 600 s when the consumer runs a model per batch

Start the watch first — selftest never grades its own homework.

9. Who spoke, and the baton

A send is signed only if the session armed a run; do it once, and the human sees which execution is talking:

eval "$(npx pidge-cli run start --mode interactive --role main)"   # pidge run end when done

A channel outlives your session. Before you exit, leave the baton for the next agent (API only today; channel id from whoami; $PIDGE_TOKEN is the key setup wrote — source it, never print it):

curl -fsS -X PATCH "https://api.pidge.sh/api/v1/channels/<id>/handoff" \
  -H "Authorization: Bearer $PIDGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"handoff":{"current_task":"…","where_i_stopped":"…","next_steps":"…"}}'

The whole path, copy-paste

npx -y pidge-cli@latest setup --claim <code> --url https://api.pidge.sh && npx -y pidge-cli@latest doctor
npx -y pidge-cli@latest hello
npx pidge-cli contract set listen_mode=persistent
eval "$(npx pidge-cli run start --mode interactive --role main)"
npx pidge-cli online --follow --ndjson --timeout 0     # persistent Monitor; elsewhere: npx pidge-cli online, one round per turn
npx pidge-cli typing && npx pidge-cli message --title "…" --body "…" && npx pidge-cli ack --up-to <id> --summary "…"
npx pidge-cli ask --title "Tests green. Ship it?" --actions yes,no --timeout 14400
npx pidge-cli selftest
curl -fsS -X PATCH "https://api.pidge.sh/api/v1/channels/<id>/handoff" -H "Authorization: Bearer $PIDGE_TOKEN" -H "Content-Type: application/json" -d '{"handoff":{"current_task":"…","where_i_stopped":"…","next_steps":"…"}}'