Per-project handoff notes: the missing layer between your CLI history and your standup
Bouncing across three or four repos in a day, your terminal history isn't a handoff. The fix is per-project notes — auto-derived from the session, scoped to the repo, surfaced when the next engineer cd's in.
If you've spent the last few weeks bouncing across three or four repos in a day, you already know the shape of the problem: at 6pm someone on the team asks "what's the state of the billing-svc work?" and your honest answer is "let me scroll up in my terminal."
Raw shell history is not a handoff. gh pr view, git log --oneline -20, kubectl get pods -n staging — none of that tells the next engineer what project you were in, what you were trying to do, or what's blocking forward motion. By the time you reconstruct it, the timezone window has closed and the work waits another twelve hours.
The fix isn't another note-taking app. It's a handoff layer that lives next to your sessions, knows which project each command belonged to, and rolls up the day per repo — not per terminal tab.
What changed
Per-project handoff notes are the missing layer between your CLI history and your standup. They're not session transcripts (too noisy) and they're not standup blurbs (too coarse). They're a per-repo, time-bounded summary of what you actually did, what's in flight, and what the next person needs to read first.
The right primitive is one note per project per work session, generated mostly from the session itself, edited only when you have something a tool can't infer.
How it works in practice
Scope the note to a project, not a terminal
The unit of handoff is the repo, not the shell. If you spent 40 minutes in billing-svc and 20 in auth-svc, that's two handoff notes — not one combined "Tuesday morning" entry. The receiver almost always cares about one of them, not both.
Cheap way to enforce this: tag the working directory at session start (pwd, branch, ticket) and again whenever it changes meaningfully. A wrapper around your shell init that writes ~/.handoff/<repo>/<date>.md is enough — no daemon, no service.
Derive the skeleton automatically
Most of the content can be machine-built from what already happened:
- Branch deltas:
git log --since="this morning" --onelineper repo - PRs opened/touched:
gh pr list --author @me --search "updated:>$(date -v-1d +%F)" - Failing commands: lines from history with non-zero exit
- Open todos: grep for
// TODO(handoff):markers you sprinkled mid-task
These four lines of context cover ~80% of what a remote teammate needs to pick up. They're also the four things humans consistently forget to write down at the end of the day.
Annotate only the decisions
The remaining 20% is rationale — why you chose option A over B, what you ruled out, what the staging env's current weirdness is hiding. This is the part that has to be human-written, but it should fit in three or four sentences. If you find yourself writing more, the right output is a doc commit in the repo, not a handoff note.
A useful pattern: prefix annotated lines with // because. Five minutes a day, two annotations per repo. That's the entire write cost.
Surface them per-project on the receiving end
The handoff note for billing-svc should appear when the next engineer cds into billing-svc — not when they open Slack. A cd hook that prints "last handoff: 14h ago by jess — see ~/.handoff/billing-svc/2026-05-22.md" closes the loop without anyone having to remember to check.
Before vs after
| Without per-project notes | With per-project notes | |
|---|---|---|
| What "handoff" means | Slack thread or 20-minute call | Single markdown file per repo per day |
| Where it lives | Cloud doc, easily abandoned | Next to the repo, surfaces on cd |
| Time to write | 10–20 min at EOD if you remember | 3–5 min, mostly auto-generated |
| Coverage when you forget | Zero | The skeleton still ships from git/gh history |
| Cross-timezone catch-up | "Let me re-read three PRs" | "Read four lines, ask one question" |
The asymmetry matters. Without this layer, the cost of forgetting is total. With it, the floor is "skeleton from history alone" — which is still better than nothing.
Who benefits most
Async teams across more than two timezones. The window for synchronous handoff is small or non-existent. Per-project notes mean the next shift doesn't lose two hours getting oriented.
Solo consultants with three or four active clients. Context-switching tax is the biggest hidden cost in consulting work. Pulling up the prior session's ~/.handoff/<client-repo>/ note in five seconds is the difference between billable hours and rebuilding state from git log.
Engineers working alongside AI agents. When part of your work is delegated to Claude Code, Codex, or a custom agent, you need a record of what the agent did in this project today that you can read before you re-engage. The per-project note is also where the agent's session summary belongs.
A note on what this is not
This pattern is not session replay. It's not pair-debugging telemetry. It's not full audit logs. Those are heavier tools with different goals — useful, but expensive to read.
The handoff note is the summary above those layers: short enough to scan in 30 seconds, structured enough that you trust it, scoped tightly enough that you don't have to filter. If you find yourself reaching for a video of the session to understand the note, the note is too thin.
Try it tonight
Pick the repo you spent the most time in today. Open ~/.handoff/<repo>/<date>.md. Paste in:
git log --since=8am --oneline- The two or three commands that mattered (with
# because <reason>) - One sentence on what's blocked and what you'd do next
That's the whole note. Tomorrow morning, repeat for whichever repo you cd into first. The format will tighten as it gets used — but the discipline of "one note per project per day" is the thing that actually moves the handoff problem.