# handover

> Repo-local handover orchestration for coding agents.

Canonical website: https://handover.openusage.sh/
Source repository: https://github.com/janekbaraniewski/handover
Releases: https://github.com/janekbaraniewski/handover/releases
License: MIT
Primary daemon dependency: https://openusage.sh

## Summary

handover is a handoff layer for coding agents. It captures enough task state before a source tool runs into its usage limit, then exposes that state in boring repo files that another tool can resume from. It also supports on-demand manual capture with `handover capture --title "..." --summary "..." --next-step "..."`.

The project deliberately keeps the canonical handover state repo-local. That means the next tool can inspect the same files, patches, and explicit next steps instead of depending on a hidden service-side session export.

## Core model

- `handover` is a short-lived handoff tool.
- `openusage` is the only daemon in the design.
- `.handover/` is the canonical repo-local state store.
- Triggering is prompt and activity driven, not polling based.
- Source and target tools are intentionally decoupled.

## Stable resume files

- `.handover/current/summary.md`
- `.handover/current/workspace.patch`

## Current CLI commands

- `enable`: initialize the workspace and install the repo-native handover files in one step.
- `disable`: remove or roll back the repo-native handover files that `enable` installed for the workspace.
- `init`: create the repo-local `.handover/` layout and default config.
- `capture`: create a handover manually on demand with a title, summary, and next step.
- `on-event`: react to real tool activity, ask `openusage` for quota state, and capture only when needed.
- `session-start`: render extra session-start context for target-tool hooks in plain, Claude, or Codex format.
- `install`: write repo-native guidance files so tools can find the current handover.
- `render`: render tool-facing handover files into an output directory.
- `inspect`: inspect the current or selected bundle.
- `pending`: inspect whether a handover is waiting for the current project and optionally claim it.
- `pickup`: claim a pending handover for the current project and promote it to `.handover/current/`.
- `run`: check for pending handovers, optionally claim them, then launch a target command.
- `status`: print the current workspace handover status.
- `adapters`: list the supported adapters and their surfaces.
- `print-config`: print the effective workspace configuration as JSON.

## Design choices

- The real ship target is a lightweight local tool, not a Node runtime.
- `openusage` owns quota normalization and stays the only daemon.
- The trigger model is based on real tool events rather than idle polling.
- The product prefers broad target-tool surfaces over deep single-tool specialization.
- Pickup is scoped to the current repo/project rather than a global queue.

## Primary docs

- Website: https://handover.openusage.sh/
- README: https://github.com/janekbaraniewski/handover/blob/main/README.md