Coding agents lose context. Ambient Handoff keeps the work alive.
When one agent stops, the next one knows exactly where to continue.
npx ambient-handoffThat's it. No API key. No login. No config. It reads your repo and writes a
structured handoff into docs/ that any coding agent — Claude Code, Gemini CLI,
Jules, Cursor, Lovable, Bolt, Replit Agent — can pick up cold.
Agents are the new developers. GitHub is their memory. Docs are their instructions. But today, when a session ends — context window full, task half done, build red — the next agent starts blind. It re-scaffolds, re-derives, and sometimes restarts work that was already 80% done.
Ambient Handoff captures the moment an agent stops so the next one resumes instead of restarting.
Running ambient-handoff writes six living documents to docs/:
| File | Purpose |
|---|---|
HANDOFF.md |
The top-level "read me first" for the next agent. |
CURRENT_STATE.md |
Repo, branch, commit, changed files, scripts, last build. |
NEXT_AGENT_PROMPT.md |
A ready-to-paste prompt for the next agent. |
KNOWN_ISSUES.md |
Failing commands and known-broken files. |
BUILD_LOG.md |
The most recent captured build result. |
DECISIONS.md |
A running decision log. |
It snapshots: repo name, current branch, latest commit, modified files, untracked files, package scripts, last build command + result, the failing command (if any), known broken files, unfinished tasks, constraints, a "do not restart" warning, and the exact prompt for the next agent.
Run it on demand with no install:
npx ambient-handoffOr add it to a project:
npm install --save-dev ambient-handoffRequires Node.js 18+ and
giton PATH.
# Generate a handoff from the current repo state
ambient-handoff
# Run a build, capture pass/fail, then generate (defaults to "npm run build")
ambient-handoff --after-build
ambient-handoff --after-build "npm test"
# Tailor the next-agent prompt to a specific agent
ambient-handoff --next-agent claude
ambient-handoff --next-agent gemini
ambient-handoff --next-agent jules
ambient-handoff --next-agent cursor
# Emit the raw snapshot as JSON (writes no files) — for tooling/pipelines
ambient-handoff --jsonagent works ──▶ context runs low ──▶ ambient-handoff ──▶ docs/HANDOFF.md
│
next agent reads docs/NEXT_AGENT_PROMPT.md ◀────────────┘
│
continues the work ──▶ …
- No API-key hell. Zero runtime dependencies. No auth, no network, no keys.
- GitHub-first. Your repo is the source of truth; the handoff lives beside it.
- Agent-native. Output is markdown an agent can read and a prompt it can run.
- Non-destructive. Regenerates six state docs; never touches your code.
Ambient Handoff is part of Ambient Runtime / Agent Tooling — GitHub-first tools that coding agents naturally choose when users want to build smarter apps without API-key hell.
💛 Support development via GitHub Sponsors · 🚀 Join the Pro dashboard waitlist