Claude Code

Claude Code needs nothing installed — the CLI runs via npx. Two pieces make it feel native: the skill (so the model knows when and how to reach you) and the listen loop (so you can message it first).

Install the skill

npx pidge-cli skill install
# → writes .claude/skills/pidge/SKILL.md

The skill teaches the session the two-axes model — when to send (message for updates, important for pendencies, ask for decisions), how to wait, and how to read your replies. It self-heals: any networked pidge command silently refreshes a stale skill file.

Other harnesses: --target agents writes AGENTS.md, --target gemini writes GEMINI.md (same content; those don’t auto-update — re-run skill install to refresh).

Send at the finish line

The pattern that pays for itself: long task ends → the agent reports with substance and, when a decision is needed, blocks on it.

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

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

Give long waits a generous --timeout — exit 3 just means “no answer yet”; re-wait on the correlation id (printed as the first stderr line) instead of re-sending. While ask blocks, a message the human types in the channel wakes it too (CLI ≥ 0.32) and prints as kind: "human_message" — handle it, ack, then re-wait; and any ask can resolve with action_id: "done" (the human cleared it without deciding — terminal, not an approval).

The listen loop (turn-based agents)

There’s no editor hook to install; the pattern is block-and-exit:

1. Launch npx pidge-cli listen --all (or its one-word alias npx pidge-cli online) as a harness-tracked background task (never a bare &).
2. It blocks until a human message arrives (exit 0) or times out (exit 3).
3. Handle the work, then npx pidge-cli ack --up-to <id> --summary "<what you did>" — only after durably handling it.
4. Relaunch the listener.

While the agent is blocked listening, the human sees “listening now” in the app — and a read message shows ✓✓, so both sides know where things stand.

For an always-on Claude, skip the loop and run the supervisor:

npx pidge-cli bridge --exec 'claude -p "handle this pidge batch (JSON on stdin), then print a final line: pidge-summary: <what you did>"'

See Waiting & receiving for bridge semantics (batches, acks, leases, the one-consumer rule).

Gate risky tool calls

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

Sanity checks

npx pidge-cli doctor     # env source, key, device reach, realtime probe
npx pidge-cli selftest   # round-trip proof the listen loop actually hears