egregore-handoff

Hand decisive context to another mind. One URL — works in any agent, any harness, any chat.

A handoff is not a session replay. It's the crystallized briefing — what was decided, what's next, what to read first — that lets the receiver (human + their agent) pick up the thinking without parsing your transcript.

Install

One-liner (Node ≥18 required):

curl egregore.xyz/install-handoff | sh

Or directly via npm:

npm install -g egregore-handoff
egregore-handoff install --harness <claude-code|codex|hermes>

Use

In your harness session:

/handoff <topic>

The skill drafts the briefing, prompts you for email + name on first run, and publishes to the relay. Returns a URL.

Receiver pastes the URL into their agent — Claude Code, Codex, Cursor, web ChatGPT, anywhere. Their agent fetches the structured payload from the page's embedded JSON-LD. Zero install on the receiving end.

Format

Each handoff is a v1 JSON-LD artifact with:

• A constrained core: topic, claim, ask, audience.addressed_to, repo_state
• A free-form body: prose (canonical) + sidecar (extracted structure)
• An open kind field (recommended: notification, continuation, review, question, handoff)
• A living extension chain: anyone can extend the same artifact

Full spec: docs/specs/handoff-format-v1.md

Programmatic API

import { buildArtifact, publish } from 'egregore-handoff'

const artifact = buildArtifact({
  kind:   'continuation',
  topic:  'auth refactor',
  claim:  'Auth-redirect isolated as its own service.',
  ask:    'Pull the branch and run through next_steps.',
  author: { handle: 'oguzhan', display: 'Oz', harness: 'claude-code' },
  audience: { addressed_to: [{ handle: 'renc', display: 'Renc' }] },
  prose:  '...',
  sidecar: { briefing: '...', next_steps: [...] },
  references: [...],
})

const { url } = await publish(artifact)
// url: https://egregore.xyz/h/h7x2k9pq

Identity

First publish prompts for email + name, stored at ~/.egregore/handoff-config.json. No verification, no password, no OAuth. Email is captured for the conversion flow if you ever upgrade to a full Egregore.

egregore-handoff identity show     # see what's stored
egregore-handoff identity set      # re-prompt
egregore-handoff identity reset    # delete

When you've sent enough handoffs

If you find yourself repeatedly handing off to the same people, run:

npx create-egregore --import-from-handoffs

Your accumulated handoff history seeds a full Egregore — counterparties become draft invites, topic clusters become quests, past handoffs are imported as initial artifacts. The conversion is "make this persistent," not "start over."

Reply from anywhere — GET relay

Consumer LLM platforms (claude.ai, ChatGPT, Gemini) can fetch URLs but can't POST to arbitrary domains. The GET relay solves this — any agent that can fetch a URL can close the loop.

Per-platform relay paths

GET https://egregore.xyz/h/{id}/reply/claude?name=...&body=...
GET https://egregore.xyz/h/{id}/reply/chatgpt?name=...&body=...
GET https://egregore.xyz/h/{id}/reply/gemini?name=...&body=...
GET https://egregore.xyz/h/{id}/reply/codex?name=...&body=...
GET https://egregore.xyz/h/{id}/reply/generic?name=...&body=...

URL-encode name and body. Returns JSON: { "status": "replied", "reply_url": "https://egregore.xyz/h/..." }.

Content-negotiated main endpoint

GET https://egregore.xyz/h/{id}/reply?name=...&body=...&format=json

Same behavior — format=json (or Accept: application/json) processes the reply server-side.

Programmatic

import { reply, buildReplyUrl } from 'egregore-handoff'

// POST first, falls back to GET on 403
const result = await reply(url, { name: 'Oz', body: 'Looks good.' })

// Force GET relay
const result = await reply(url, { name: 'Oz', body: '...', useGet: true, platform: 'chatgpt' })

// Build the URL for another agent to fetch
const replyUrl = buildReplyUrl(url, { name: 'Oz', body: '...', platform: 'claude' })

Differentiator vs SessionFS

SessionFS ships your raw session (transcript, workspace, tools). egregore-handoff ships your thinking (claim, ask, decisions, next steps). Different problems — both are real. Use SessionFS if you want to resume your own session on another machine. Use this if you want to hand decisive context to another mind.

License

MIT.

Repo

Canonical: Curve-Labs/egregore-handoff.