handoff

workflow
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Fail
  • Hardcoded secret — Potential hardcoded credential in tests/test_hooks.py
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

A memory and workflow plugin for Claude Code. Just markdown files, No server, no database, committed with your code.

README.md

handoff

Shift-change notes for your coding agent.

Coding sessions lose context. handoff is the note the
last session leaves for the next one.

Version
CI
License: MIT
GitHub stars

A simple memory and workflow system for Claude Code and local Codex.


The problem

Every new coding-agent session needs to recover what you
built yesterday, what you decided against, or which folder has the tricky code.

The existing fixes have real downsides:

  • A giant CLAUDE.md / AGENTS.md — everything loads every session, whether you need it
    or not. You pay for all of it, every time, and it keeps growing.
  • Memory servers and databases — another thing to install, run, and keep
    alive. Your project's memory lives outside your project.
  • Hoping the agent figures it out — it re-reads your codebase every
    session and reaches slightly different conclusions each time.

What handoff does instead

It keeps memory in plain markdown files, inside your repo, committed with
your code
. A few small hooks make sure the right file reaches the agent at
the right moment — and nothing more:

  • When a session starts, the agent gets the current status, your project
    rules, and a short reminder to state each task's risk tier (loading the
    workflow skill for T2/T3). That's it — a few hundred tokens, not thousands.
  • When it's about to edit a file in a folder that has notes (CONTEXT.md),
    those notes get injected right then. Not before.
  • When a session ends having changed code — committed or not — without
    updating the status, the agent gets reminded to bring the notes up to date,
    in the same commit as the code. It knows the difference between your
    session's work and dirt that was already there, and it never nags twice
    about the same thing.
  • When a session's context grows past 200k tokens (and again at 400k, 600k…),
    the agent is asked once to leave a handoff a fresh session can continue
    from, and to tell you a new session would be cheaper — even if the turn was
    only discussion.
  • Unfinished work doesn't vanish with the session. Follow-ups, bugs, and ideas
    become small task files in a backlog inside the repo — written so that any
    future session can pick one up cold and know when it's done (more
    below
    ).

No server. No database. No dependencies — three Python hooks and one shared
helper file, standard library only. If a hook ever fails, it stays silent and
your session is unaffected. And since it's all just files in git, your memory
travels with the repo: every clone and every teammate gets it for free.

Quick start

Inside Claude Code:

# 1. Add this repo as a plugin marketplace (once)
/plugin marketplace add AbdurRafay2004/handoff

# 2. Install the plugin
/plugin install handoff@handoff

Inside Codex (desktop or CLI, with local execution), use the same marketplace:

# Test a local checkout; replace the path with your clone
codex plugin marketplace add /absolute/path/to/handoff
codex plugin add handoff@handoff

For a published release, the marketplace source can instead be
AbdurRafay2004/handoff. In the desktop app, install from that marketplace in
Plugins. Review and trust the plugin hooks (/hooks in the CLI), then start
a new chat. Updating a plugin's hook definition requires another trust review.
See Codex setup and compatibility for details and limitations.

Then, in any repo where you want memory, ask:

set up handoff

Coming from agent-orch (v1.x)? The plugin and its .agent-orch/ directory
were renamed at v2.0.0 — see docs/MIGRATION-v2.md
for a copy-paste migration prompt.

Setup copies the file templates into .handoff/, reads your actual codebase
to draft the status, map, and tech notes, and asks you to confirm before
saving anything
— it never invents facts about your project. Run it once per
repo. After that, everything is automatic.

After updating the plugin, refresh or reinstall it through your host and start
a new chat. Existing .handoff/ files are preserved, so template changes need
a separate refresh. To adopt the writing guidance in an existing repo, ask the
agent to merge the Communication section from the plugin's bundled
templates/RULES.md into .handoff/RULES.md, preserving the other rules.

What ends up in your repo

.handoff/
  STATUS.md       # where the project stands right now (loaded every session)
  RULES.md        # your non-negotiables (loaded every session)
  MAP.md          # where important files live (read when needed)
  CHANGELOG.md    # what changed and why (read when needed)
  context/        # stable notes: product intent, tech stack
  tasks/          # a real backlog: inbox / now / done
  handoffs/       # optional overflow notes for the next session (listed, not loaded)

Plus optional CONTEXT.md files in folders that need explaining — those load
only when the agent edits there.

To check the memory for drift, say "check handoff". The setup skill runs a
read-only lint that reports task files whose folder and status disagree, MAP.md
and CONTEXT.md paths that no longer exist, leftover template placeholders, an
oversized STATUS.md, and CONTEXT.md notes that fell behind their folder.

The whole idea in one sentence: the files that are always relevant are
pushed every session; everything else costs nothing until it's actually
needed.

The tasks backlog

This might be the best part of the whole system. Instead of follow-ups dying
in chat history, they live as small markdown files that move through three
folders:

tasks/inbox/   # new ideas, bugs, follow-ups land here
tasks/now/     # the small set you're actually working on
tasks/done/    # finished (or deliberately closed)

Each task is one file that carries everything a future session needs to pick
it up cold — no chat history required:

---
title: Fix flaky checkout test
status: now
priority: high
why_it_matters: Blocks every release; CI reruns waste ~20 min a day.
context: Fails only when the cart has a discount code. Started after #142.
---

## Notes
- Repro: run checkout.spec.ts with SEED=7

## Verification
- npx vitest checkout.spec.ts — passes 10/10 runs

Notice the Verification section: a task states how to prove it's done, so
whoever (or whatever session) finishes it knows when to stop.

The hooks quietly keep this tidy. If the agent tries to write a task file to
the tasks/ root instead of a status folder, it gets corrected before the
file lands
— and again at the end of the turn if any strays remain. Skills
feed the backlog too: debugging leaves architectural findings there, and
retrospectives file their action items as tasks instead of letting them
evaporate.

Guard rails you'll appreciate later

A few small mechanisms that don't show up until they save you:

  • Approval gates that hold. Risky work (T3) stops at a .handoff/GATE
    file with the question awaiting your answer. While that file exists the
    agent won't proceed — even an autonomous loop just idles there until you
    rule.
  • Risky paths get flagged automatically. Touch anything matching
    migrations, auth, billing, .env and the like, and the end-of-turn check
    asks whether this was treated with the care it deserves. The pattern list
    is per-repo configurable via .handoff/SENTINELS.
  • Status bloat is policed. STATUS.md loads every session, so it's a tax
    if it grows. Past 40 lines the agent gets told to prune it (target: 25).
  • Clones without the plugin still work. Setup writes a small fallback
    block into your host's CLAUDE.md or AGENTS.md, so a teammate who hasn't installed handoff
    still gets the core rules and knows where the notes live.
  • Stale installs get noticed. Setup stamps .handoff/VERSION; when the
    plugin moves ahead of an install, you're told instead of drifting silently.

The workflow part

handoff also ships a set of skills that give the agent a sane way of working.
The core one, workflow, sorts every task into a tier:

Tier Example What the agent does
T1 fix a typo, tweak styling just edits it, checks it compiles, done
T2 a normal feature brief and short plan together, one approval, build, test what changed, review
T3 money, auth, user data, migrations written plan you approve, tests first, security review, proof it works

So a two-line fix never gets buried in ceremony, and a payment change never
skips review. Thirteen companion skills cover the techniques: writing a brief,
planning, debugging properly, TDD, shipping, security audits, browser QA, and
more — including grill-me, which interrogates your plan until you've both
thought it through.

One more keeps the sessions themselves lean: say "audit context" and
context-audit lists every plugin, MCP server and skill that loads for this
project, with a rough per-session token cost, checks them against what the
project actually uses, and proposes turning off the unused ones for this
project only (in .claude/settings.local.json). Nothing changes until you
approve. On Codex it reports and leaves the edits to you.

For normal T2 work, you review what you want, how the agent will do it, and how
it will check the result in one proposal. If you already approved that scope
and approach, the agent continues without asking again. Risky T3 work keeps
separate spec and plan approvals.

The workflow and default rules also guide the agent to write clear, connected
explanations: start with the result, explain why it matters, and keep useful
technical detail. Short answers should still make sense on the first reading.

These skills are adapted from open-source work by Jesse Vincent, Matt Pocock,
Garry Tan, and RampStack Co. — see ATTRIBUTION.md. One
deliberate change: the workflow skill alone decides the process, so the
skills never fight each other over sequencing. If you install handoff,
disable the original packs to avoid duplicate instructions.

Honest limitations

  • Files edited through shell commands (sed, cat >) don't trigger the
    folder-notes injection. Claude file tools and Codex's native apply_patch
    do, including all files in a patch and both sides of a move.
  • On very large repos, git commands in the hooks time out after 10 seconds;
    when that happens the affected check quietly skips that turn.
  • Change tracking survives /compact and resuming a session, but it lives in
    the system temp folder: if that is cleared (for example by a reboot), work
    done before then may not get the end-of-turn reminder.
  • Work you've already pushed doesn't trigger the reminder (deliberate: the
    hook would rather stay quiet than nag about published commits), and the
    very first turn after adopting the hooks is silent while it takes its
    baseline.
  • The risky-path flagging is pattern matching, not a security scanner — it
    catches migrations/, misses cleverly-named danger.
  • Repos without git don't get the end-of-session reminder (it needs git to
    see what changed).
  • Automatic hooks require Claude Code or a local Codex runtime with hooks
    enabled and trusted. Cloud-orchestrated ChatGPT Work does not run bundled
    plugin hooks; use the instructions in AGENTS.md to read memory manually.

Every limitation fails quiet, never broken.

Development

# run the same tests CI runs
python3 tests/test_hooks.py

The suite covers Claude and Codex payloads, hook command registration,
multi-file/move patches, subfolders/worktrees, path safety, and Stop cooldowns.

No build step. Ground rules for contributions: hooks stay standard-library
only, hooks stay fail-safe (silent exit on any error), and the workflow
skill alone owns process. The full invariants are in CLAUDE.md.

Star history

Star history chart

License

MIT © Rafay. Adapted portions credited in
ATTRIBUTION.md.

Reviews (0)

No results found