{"id":51594334,"url":"https://github.com/wardmos/waybill","last_synced_at":"2026-07-11T17:01:59.349Z","repository":{"id":369311225,"uuid":"1286337381","full_name":"wardmos/waybill","owner":"wardmos","description":"Continue unfinished coding tasks across agent CLIs with portable handoff bundles.","archived":false,"fork":false,"pushed_at":"2026-07-04T16:38:21.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T17:10:43.752Z","etag":null,"topics":["agent-handoff","agent-resume","ai-agents","claude-code","codex","coding-agents","cursor","gemini-cli","opencode","python","skills","task-continuation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wardmos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-07-01T17:13:44.000Z","updated_at":"2026-07-04T16:35:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wardmos/waybill","commit_stats":null,"previous_names":["wardmos/waybill"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/wardmos/waybill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wardmos%2Fwaybill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wardmos%2Fwaybill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wardmos%2Fwaybill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wardmos%2Fwaybill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wardmos","download_url":"https://codeload.github.com/wardmos/waybill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wardmos%2Fwaybill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35368768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-handoff","agent-resume","ai-agents","claude-code","codex","coding-agents","cursor","gemini-cli","opencode","python","skills","task-continuation"],"created_at":"2026-07-11T17:01:55.887Z","updated_at":"2026-07-11T17:01:59.331Z","avatar_url":"https://github.com/wardmos.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Waybill\n\nPortable handover bundles for agents, starting with coding agents.\n\nWhen an agent gets stuck, runs out of context, or needs to hand work to another\ntool, Waybill gives the next agent a local, reviewable handoff bundle.\n\nExport an unfinished task from Claude Code:\n\n```text\n/handoff export\n```\n\nContinue it in Codex:\n\n```text\n/handoff import .waybill\n```\n\nWaybill helps continue unfinished coding work across different agents. Native\n`resume` commands usually continue sessions inside one agent CLI.\nWaybill keeps handoffs agent-neutral and portable across coding agents.\nWaybill started with Claude Code and Codex. The current adapter set also\nincludes OpenCode, Cursor CLI, and Gemini CLI.\n\nWaybill is not a replacement agent or a standalone workflow runner. It is a\nlocal handoff format plus thin adapters for existing coding agents.\n\nFor the shortest setup path, see `QUICKSTART.md`.\n\n## At A Glance\n\n| Area | Status |\n| --- | --- |\n| Bundle format | Draft `.waybill/` directory |\n| Primary entrypoint | Agent commands: `/handoff` and `/waybill` |\n| Support CLI | Python standard library, no package manager install |\n| Adapters | Claude Code, Codex, OpenCode, Cursor CLI, Gemini CLI |\n| Data model | Local-first files in the target repository |\n| Import behavior | Non-destructive; patches are not applied automatically |\n| Sharing | Best-effort redaction, validation, render, pack, and unpack |\n\n## When To Use Waybill\n\nUse Waybill when:\n\n- An agent session is running out of context and another agent needs to continue.\n- You want to switch tools, models, or agent CLIs without losing task state.\n- A human reviewer needs a compact summary of current progress, failed attempts,\n  tests, diffs, and risks.\n- You want a local handoff artifact that can be validated, redacted, rendered,\n  packed, and shared intentionally.\n\n## Validated Handoffs\n\nWaybill has been exercised with real cross-agent handoffs in both directions:\n\n- Claude Code exported an unfinished coding task, and Codex imported the bundle,\n  verified repository state, finished the focused fix, and ran tests.\n- Codex exported an unfinished coding task, and Claude Code imported the bundle,\n  verified repository state, finished the focused fix, and ran tests.\n\nImport remains non-destructive: the next agent reads the bundle and checks the\ncurrent repository state before deciding what to do.\n\n## Agent-Assisted Install\n\nGive your coding agent this repository URL and ask:\n\n```text\nUse https://github.com/wardmos/waybill to install Waybill adapters into this\nrepo. Follow QUICKSTART.md, then run the doctor check.\n```\n\nThe agent should run:\n\n```bash\n./cli/waybill init --target /path/to/your/repo\n./cli/waybill doctor --target /path/to/your/repo\n```\n\n`init` installs file-based project adapters for Claude Code, OpenCode, Cursor,\nand Gemini CLI. Codex uses the local plugin marketplace described in\n`INSTALL.md`.\n\n## What Waybill Creates\n\nA Waybill Bundle is a local directory in the current repository:\n\n```text\n.waybill/\n  WAYBILL.md\n  metadata.json\n  diff.patch\n  commands.log\n  test-summary.md\n```\n\nRequired files:\n\n- `WAYBILL.md`\n- `metadata.json`\n\nRecommended files:\n\n- `diff.patch`\n- `commands.log`\n- `test-summary.md`\n\n## Agent Commands\n\nWaybill supports two command names with the same behavior inside supported\nagent CLIs:\n\n```text\n/handoff export\n/waybill export\n```\n\n```text\n/handoff import .waybill\n/waybill import .waybill\n```\n\n`/handoff` is the primary command because it describes the user action. `/waybill`\nis an alias for users who think in terms of the project name.\n\n## Examples\n\nSynthetic example bundles are available in:\n\n```text\nexamples/claude-to-codex/\nexamples/codex-to-claude/\nexamples/failed-test-handoff/\n```\n\n`failed-test-handoff` shows a focused failing-test handoff with a partial patch,\ncommand log, and test summary.\n\nTry one locally:\n\n```bash\n./cli/waybill validate examples/failed-test-handoff\n./cli/waybill inspect examples/failed-test-handoff\n./cli/waybill render examples/failed-test-handoff\n```\n\n## Support CLI\n\nThe primary user flow happens inside agent CLIs with `/handoff` and `/waybill`.\nThe Python CLI is a small support tool for installing file-based adapters,\nvalidating bundles, checking repository state, redacting, packing, unpacking,\nand rendering review reports. It uses only the Python standard library.\n\nWhen installed from the `agent-waybill` Python package, it provides the\n`waybill` support command. Agent adapters are still installed into project\nrepositories.\n\n| Command | Purpose |\n| --- | --- |\n| `init` | Install file-based project adapters into a target repo |\n| `doctor` | Check adapter installation and `.waybill/` ignore setup |\n| `new` | Create a draft Waybill Bundle from a repo |\n| `validate` | Validate bundle structure, metadata, artifacts, and obvious secrets |\n| `inspect` | Summarize metadata, artifacts, and validation status |\n| `verify-repo` | Compare bundle metadata with the current repo state |\n| `preflight` | Run validation plus repository-state checks before import |\n| `ready` | Check whether a bundle is ready for handoff |\n| `redact` | Create a redacted review copy |\n| `share` | Redact, validate, and pack a shareable archive |\n| `pack` | Validate and zip a bundle |\n| `unpack` | Unzip and validate a bundle archive |\n| `render` | Render a Markdown review report |\n\nMost commands support `--json` for scriptable workflows. See `QUICKSTART.md`\nand `TESTING.md` for full command examples.\n\n### Adapter Matrix\n\n| Agent CLI | Project entrypoint | Installed by `init` | Smoke coverage |\n| --- | --- | --- | --- |\n| Claude Code | `.claude/skills/` | Yes | Read-only import smoke |\n| Codex | `adapters/codex/` plugin | No | Read-only import smoke |\n| OpenCode | `.opencode/commands/`, `.opencode/skills/` | Yes | Read-only import smoke |\n| Cursor CLI | `.cursor/rules/` | Yes | Read-only import smoke |\n| Gemini CLI | `.gemini/skills/` | Yes | Read-only import smoke |\n\n## Install\n\nSee `INSTALL.md` for full local installation and smoke-test instructions.\n\n### Claude Code\n\nUse the project-scoped Claude Code skills in:\n\n```text\n.claude/skills/\n```\n\nCompatibility command instructions are also available in\n`adapters/claude-code/commands/`.\n\n### Codex\n\nUse the Codex plugin in:\n\n```text\nadapters/codex/\n```\n\n### OpenCode\n\nUse the OpenCode project commands and skills in:\n\n```text\n.opencode/\n```\n\nReusable adapter files are available in:\n\n```text\nadapters/opencode/\n```\n\n### Cursor CLI\n\nUse the Cursor project rules in:\n\n```text\n.cursor/rules/\n```\n\nReusable adapter files are available in:\n\n```text\nadapters/cursor/\n```\n\n### Gemini CLI\n\nUse the Gemini CLI workspace skills in:\n\n```text\n.gemini/skills/\n```\n\nReusable adapter files are available in:\n\n```text\nadapters/gemini-cli/\n```\n\n## Safety Defaults\n\n- `.waybill/` is ignored by default.\n- Waybill does not upload handoff data.\n- Import instructions do not automatically apply patches.\n- Export instructions may run read-only git inspection commands.\n- Export instructions do not run tests unless the user asks.\n- Users should review `.waybill/` before sharing it.\n\n`.waybill/` can contain prompts, paths, diffs, logs, test output, and secrets\naccidentally captured from output.\n\n## Testing\n\nRun the repository checks:\n\n```bash\npython3 scripts/validate-waybill.py\n```\n\nRun repeatable local agent smoke tests when the relevant CLIs are installed:\n\n```bash\nscripts/smoke-agents.sh --tool codex\nscripts/smoke-agents.sh --tool opencode\nscripts/smoke-agents.sh --tool cursor\nscripts/smoke-agents.sh --tool gemini\nscripts/smoke-agents.sh --tool claude\n```\n\nUse `scripts/smoke-agents.sh --dry-run` to print the exact commands without\ncalling any agent model.\n\nSee `TESTING.md` for the manual Claude Code to Codex and Codex to Claude Code\nhandoff test plans.\n\n## Current Limitations\n\n- No automatic patch application.\n- No automatic transcript parsing.\n- Secret redaction is best-effort pattern replacement; users still need to\n  review redacted bundles before sharing.\n- OpenCode support is file-based commands and skills; no OpenCode plugin hooks\n  are required yet.\n- Cursor support uses project rules loaded by Cursor Agent and Cursor CLI; no\n  Cursor plugin hook is required yet.\n- Gemini CLI support uses workspace skills loaded by Gemini CLI; no extension\n  install is required yet.\n\n## Roadmap\n\nNear-term:\n\n- Add more compatibility fixtures and documented walkthroughs for failed tests,\n  code review, patch verification, and cross-agent handoff recovery.\n- Strengthen conformance checks for agent-generated bundles.\n\nDelegation:\n\n- Add delegation request and result templates for parent/child agent workflows.\n- Add parent/child examples such as Claude Code parent to Codex child, and Codex\n  parent to Claude Code child, using synthetic repositories and non-destructive\n  imports.\n- Explore optional delegation metadata such as `handoff.kind`.\n\nOrchestration Compatibility:\n\n- Keep Waybill usable as an agent-neutral task envelope that future\n  orchestrators can write and read.\n- Keep Waybill out of the business of scheduling, running, or supervising\n  agents.\n\nAdapters:\n\n- Add more adapters where the target CLI has a lightweight project instruction\n  mechanism, after the handoff and delegation formats stay stable.\n\nNon-goals for now:\n\n- Automatic patch application.\n- Automatic transcript parsing.\n- Daemon behavior, cloud sync, and Web UI.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwardmos%2Fwaybill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwardmos%2Fwaybill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwardmos%2Fwaybill/lists"}