agent-handoff

Minimal handoff packets for agent sessions that share a codebase but not a conversation history.

agent-handoff is a small TypeScript package for packaging intent, summary, artifacts, constraints, decisions, open questions, and next actions into a deterministic handoff file that other agents or humans can continue from.

Agent metadata

• Built for: OpenClaw agents, autonomous agents, and human operators running multi-agent workflows
• Category: agent-infrastructure
• Use cases: cross-CLI handoff, design-to-code transfer, agent session continuity, structured task delegation
• Runtime: Node.js / TypeScript

Install

Clone the repo and install dependencies:

git clone https://github.com/Else-Ventures/agent-handoff.git
cd agent-handoff
npm install
npm run build

npm publish coming once v1 is reviewed and stable.

API

createHandoff(packet: HandoffPacket): HandoffPacket
writeHandoff(path: string, packet: HandoffPacket): void
readHandoff(path: string): HandoffPacket
renderHandoff(packet: HandoffPacket): string

Render contract

renderHandoff() always renders this section order and never invents extra formatting:

# Handoff: {id}
{created_at} · {from.agent} → {to.agent or "any"}

> ⚠️ Status: expired handoff

## Intent
{intent}

## Summary
{summary}

## Artifacts
- [{label}]({path or url}) — {note}

## Constraints
- {constraint}

## Decisions Already Made
- {decision}

## Open Questions
- {question}

## Next Action
{next_action}

---
Repo: {repo.branch} @ {repo.commit}

The expired marker only appears when expires_at is present and already in the past. Empty sections are omitted entirely.

Example

import { createHandoff, renderHandoff, writeHandoff } from '@else-ventures/agent-handoff';

const packet = createHandoff({
  version: '0.1',
  id: 'design-to-code-001',
  created_at: new Date().toISOString(),
  from: { agent: 'claude-design' },
  to: { agent: 'claude-code', role: 'implementation' },
  repo: { branch: 'main', commit: 'abc123' },
  intent: 'Turn the approved mockup into a website alpha',
  summary: 'Design is approved. Implementation should continue in the current repo.',
  artifacts: [
    {
      type: 'image',
      path: './mockup.png',
      label: 'Approved mockup',
      note: 'Primary design reference',
    },
  ],
  constraints: ['Keep the dark visual style'],
  decisions: ['Landing page only'],
  open_questions: ['Should the CTA scroll or navigate?'],
  next_action: 'Implement the alpha in the current repo.',
});

writeHandoff('./handoff.json', packet);
const markdown = renderHandoff(packet);

See examples/design-to-code.ts for a full example that writes both handoff.json and handoff.md.

Development

npm install
npm test
npm run build
npm run example