Session handoffs
The built-in handoff skill leaves a task note in one coding tool so you can resume the task in another on the same machine. The second tool checks the note against Git before it continues.
Enable the skill
Add this to agnostic-ai.yaml, then run agnostic-ai sync:
requires: ">=0.80.0"
builtins: [handoff]
Projects created with init have it on already. For every project, add the same lines to ~/.agnostic-ai/agnostic-ai.yaml and run agnostic-ai sync --global.
Most tools get a skill; tools set to emit-skills-as-commands also get a command. Aider gets the text inline when outputs.aider.rules-file is set. Jules has no skill support.
Leave a session
Ask the current tool to “write a handoff”, or “write a handoff for feat/x” for another branch. It saves the goal, progress, and next steps in a short note for the branch.
Resume in another tool
Open the other tool in the same project and say “resume the handoff”. It finds the newest note for the branch, reports the next steps, and checks the branch, commit, and working changes against Git. Unexpected differences need your confirmation.
Limits and overrides
Handoffs stay on one machine; teammates never see them. Linked worktrees (extra checkouts of the same repository) can share the notes, which Git ignores. List saved tasks with agnostic-ai handoff list.
To replace the built-in, create your own project skill named Notes live in The project root is the nearest folder with From the main checkout, ask to resume a named branch. If no note matches the current branch, the skill lists local task headers and asks which to resume, the same tasks The old Sync can grant access to the main checkout's ignored handoff store: The absolute path goes only into native config that Git ignores. For a tracked file, sync reports the path and asks you to untrack the file; for a hand-written or unmanaged file, it reports the access to add yourself. Existing restrictions still apply, Factory's grant does not turn its sandbox on, and an explicit Codex sandbox table in an imported overlay stays unchanged. OpenCode and Devin grants go only into files sync created or granted in before; skipping a grant does not skip the rest of the file's sync. OpenCode keeps any existing rule for that path and gets no grant when the path contains glob characters. Hand-written grants always stay. An unchanged generated grant leaves with the built-in, including one in a file you later committed. An unsafe main store (tracked, not ignored, a symlink, or inaccessible) gets no grant, and the skill uses a safe store in the current checkout. Dry runs and checks create no store. The lead asks each delegate to write a handoff for its branch before returning. After a handoff, the skill suggests lessons worth keeping, each with its scope and exact change, and saves only the ones you approve. Project lessons are shared in Git; personal lessons stay in the checkout; global lessons apply across projects. The project file follows The separate The snapshot goes to When a session starts in a linked worktree, the notice names its branch's handoff. In the main checkout, it reports how many branches have handoffs. A manual note and a snapshot for the same branch count as one task, and the notice prefers the manual note. Snapshot worktree headers end with Claude hooks use the working directory ( Claude hooks need Bash; the other hooks need Each tool's own hook settings still apply: approve Codex hooks with Factory hides hook output by default. To see the startup notice, add this settings spec and sync: Factory hooks only work per project, not through Claude Code, Codex, Gemini CLI, and Qoder CLI can also get the hooks through A project handoff; agnostic-ai list shows which one wins. If a global built-in clashes with your project skill, rename yours or turn the built-in off in the global config.Inspect note format, branch matching, and fallback stores
# Handoff
tool: codex | date: 2026-10-05T14:02Z | branch: feat/x | head: abc1234
worktree: /path/to/checkout | status: active | pr: none
## Goal
## Acceptance
## Done
## In progress
## Next steps
## Open decisions
## Gotchas
## Verify
.agnostic-ai/local/handoffs/ in the main checkout. feat/x becomes feat-x.md: any character other than a letter, number, ., _, or - becomes -. A note replaces only its branch's previous note; a filename collision needs confirmation. Status is active, blocked, or ready. Writes go through a private temporary file and an atomic rename, with mode 0600. Notes exclude secrets and native tool memory.agnostic-ai.yaml, or the Git repository root when there is none. A subproject with its own config keeps its own store at the same relative path in the main checkout. If that checkout is bare, its store is not ignored by Git, or a write fails, the skill uses the current checkout's ignored store. It stops if neither is safe.agnostic-ai handoff list shows. A task whose worktree is gone shows as removed, and its note stays available. A tool in the task's live worktree resumes its note without a branch mismatch prompt..agnostic-ai/local/HANDOFF.md and HANDOFF.auto.md still work. The skill finds matching automatic snapshots in the shared store, the checkout store, and the old path. When the newest snapshot is newer than the manual note, it adds that Git evidence and keeps the note's goal, next steps, status, and PR. A shared snapshot survives removal of its worktree.Write notes from linked worktrees
Write from a linked worktree
Tool Native setting Codex sandbox_workspace_write.writable_rootsClaude Code permissions.additionalDirectories in settings.local.jsonQoder permissions.additionalDirectoriesFactory sandbox.filesystem.allowWrite in .factory/settings.local.jsonOpenCode permission.external_directory, "<store>/**": "allow"Devin CLI permissions.allow, Write(<store>/**)Keep useful lessons after a handoff
Save what you learned
Scope File Then run [project] .agnostic-ai/rules/learnings.mdagnostic-ai sync[personal] .agnostic-ai/local/rules/learnings-local.mdagnostic-ai sync[global] ~/.agnostic-ai/rules/learnings.mdagnostic-ai sync --globalsources.rules if you changed it, and the global file follows AGNOSTIC_AI_HOME if set. If agnostic-ai is not on your PATH, the skill prints the sync command for you to run.Save automatic Git snapshots and show startup notices
Add automatic Git snapshots
handoff-hook built-in, off by default, saves the Git state when a session ends or the tool shortens its conversation history (context compaction):requires: ">=0.80.0"
builtins: [handoff, handoff-hook]
Tool Saves a snapshot on Shows a notice on Claude Code PreCompact, SessionEndSessionStartCodex PreCompact, SessionEndSessionStartGemini CLI PreCompress, SessionEndSessionStartQoder CLI PreCompact, SessionEndSessionStartFactory / Droid PreCompact, SessionEndSessionStarthandoffs/<branch-slug>.auto.md in the same store as manual notes, written the same safe way, with the same fallback to the checkout store. It holds the tool, date, branch, HEAD, absolute worktree path, git status --short, and the last five commit messages. Each hook also keeps .agnostic-ai/local/HANDOFF.auto.md as a compatibility copy when that path is ignored. It never reads your handoff note, diffs, transcripts, or tool memory. Outside a git repository, or before the first commit, no snapshot is saved.detached: true or detached: false. A detached snapshot uses its HEAD as the task key, so different detached tasks and a branch named detached stay separate. The final boolean keeps marker-like path text intact. The hooks still show the old messages for .agnostic-ai/local/HANDOFF.md and HANDOFF.auto.md when no task handoff matches. Nothing resumes until you ask.cwd) from the tool's event, including in linked worktrees, even when the hook process runs in the main checkout. Config discovery stays inside that checkout. Empty input or an event without cwd uses the process directory. Invalid or ambiguous input saves nothing. Input is limited to 64 KiB, 32 nested containers, and a two-second read deadline.sh. All need Git and awk. On Windows, use Git for Windows with its Unix tools on PATH. Start Claude Code from the project root so it loads .claude/settings.json./hooks, and approve Gemini project hooks when asked. A tool may stop before the snapshot finishes when it exits or compacts.Factory notices
# .agnostic-ai/settings/handoff-notices.yaml
name: handoff-notices
targets: [factory]
x-factory:
showHookOutput: true
sync --global.Global hooks
agnostic-ai sync --global. They still find the current project at run time.agnostic-ai sync adds .agnostic-ai/local/ to the ignore file. With only global hooks or skills, add that line to the project's .gitignore yourself.
See where it comes from
agnostic-ai list
agnostic-ai explain builtin:handoff
agnostic-ai why .claude/skills/handoff/SKILL.md
Reports show builtin:handoff and its release version. After an upgrade that changes the built-in, sync again.