emissary

The Emissary Courier CLI installs the receiver skill and composes, publishes, and sends portable handoff v1 artifacts. An emissary is a structured handoff: a JSON-LD artifact that carries a task from one person (or agent) to another. The author drafts it, shares a link, and the recipient pastes that link into their AI harness. The receiving agent reads the artifact and executes the deliverable.

Receiving is a one-time setup:

npx egregore-emissary@latest install

Then paste any emissary launch line into Claude Code or Codex:

Run this Egregore {kind} packet for me: {raw_url}

The receiver skill makes the AI fetch the packet, ask the intake questions, and run the mandate without turning the emissary into a giant pasted prompt.

Install

npx egregore-emissary@latest install

install adds the receiver skill for the detected harness, registers your emissary identity, stores the auth token locally (at ~/.egregore/emissary-config.json, mode 0600), lets you confirm or override the detected harness, and optionally registers the egregore MCP. A verification email is sent, and verification is a gate: new and send check it before opening your harness, so you click the link once rather than composing an emissary that can't publish. Pass --harness to skip the chooser; a non-interactive install falls back to auto-detection.

Commands

| Command | What it does | |---|---| | emissary install | Register an identity, store the auth token, register the MCP (optional). | | emissary new | Run the create interview, compose + validate a handoff v1 artifact, publish it. | | emissary send --to <email> | A directed create — addressed to one or more people, who get a notification email. | | emissary respond <id or url> --to <email> | Reply to an emissary — a new directed create threaded to the parent via parents. --message "<text>" for a one-liner, --answers <file> for a full reply. | | emissary resend-verification | Re-trigger the verification email. |

emissary new

Runs an interview one question at a time — kind, topic, claim, ask, summary, body prose, receiver instructions, executable spec (for the structurally-enforced kinds: build / research / dialogue / brief), distribution, and render mode. The composed artifact is validated client-side against handoff v1 before the POST.

Authoring rules for reliable web-chat fallback:

• Add role topology for every person-centered or demo packet. The rulebase supports archetype: default, birthday_self, gift_for_someone_else, research_demo, and design_dna.
• Make the opener explain why the first question is being asked.
• Keep intake questions aligned with the receiver's role. If the sender has already bundled research, ask reader-orientation questions (angle, scope, audience, depth, output emphasis), not "what are you building?"
• Avoid assistant-command phrasing in visible copy and receiver instructions: no FOR AI, ignore previous, do not ask, execute verbatim, system prompt, or no caveats.
• Omit receiver_instructions unless needed. The default uses a calm consent opener for bare links and starts intake when the user explicitly says to run/open/use the packet.
• Prefer sharing raw_url in the launch prompt so web assistants can see the complete intake and output spec.

For non-interactive use (CI, scripts), pass --answers <file>:

emissary new --answers ./my-emissary.json

The answers file is a JSON object with keys: kind, topic, claim, ask?, summary, prose, archetype?, role_topology?, receiver_instructions?, executable_spec?, distribution (public | person), recipients?, render_mode?.

Flags

| Flag | For | Meaning | |---|---|---| | --name | install | Your display name. | | --email | install | Your email — the emissary identity. | | --token | install | Optional install-funnel token from an /emissary/i/{token} link. | | --harness | install | claude-code | codex | claude-desktop | claude-ai | chatgpt. Auto-detected when omitted. | | --no-mcp | install | Skip native MCP registration. | | --answers | new, send | Path to a JSON answers file (non-interactive). | | --to | send | Recipient email. Repeatable, or comma-separated. |

Environment

| Variable | Purpose | |---|---| | EMISSARY_API_URL | Override the write-API base URL (default: egregore.xyz). | | EMISSARY_MCP_URL | Override the egregore MCP server URL. | | EMISSARY_CONFIG_PATH | Override the local auth-token store path. |

Tests

npm test

The suite implements the S2·* smokes from docs/specs/emissary-test-ledger.md (install, new, send) plus client-side validation unit tests. By default the cross-stream smokes run against an in-process stub server (green-vs-stub); set EMISSARY_API_URL to the real backend to re-verify them green-vs-real.

Docs

• docs/specs/emissary-v0-build-spec.md — the build spec.
• docs/specs/emissary-api-contract.md — the frozen API contract.
• docs/specs/handoff-v1.schema.json — the artifact schema.