Orca CLI
stablyai/orca
Operate Orca-managed worktrees, folder contexts, terminals, repos, automations, artifacts, skill sharing, worktree comments, and Orca's embedded browser…
Keeps a branch-local issue brief, decision log and session handoffs so a pull request's context survives across separate agent sessions.
Install Branch Context Handoff
$ npx skills add pydantic/pydantic-ai-harness --skill branch-context -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install pydantic/pydantic-ai-harness branch-context --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai-harness.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/branch-context .claude/skills/branch-context && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "branch-context" agent skill from https://github.com/pydantic/pydantic-ai-harness/tree/main/.agents/skills/branch-context into .claude/skills/branch-context/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "branch-context", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/pydantic/pydantic-ai-harness/tree/main/.agents/skills/branch-contextType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add pydantic/pydantic-ai-harness --skill branch-context -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install pydantic/pydantic-ai-harness branch-context --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai-harness.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/branch-context .agents/skills/branch-context && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "branch-context" agent skill from https://github.com/pydantic/pydantic-ai-harness/tree/main/.agents/skills/branch-context into .agents/skills/branch-context/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "branch-context", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add pydantic/pydantic-ai-harness --skill branch-context -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install pydantic/pydantic-ai-harness branch-context --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai-harness.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/branch-context .cursor/skills/branch-context && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "branch-context" agent skill from https://github.com/pydantic/pydantic-ai-harness/tree/main/.agents/skills/branch-context into .cursor/skills/branch-context/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "branch-context", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/pydantic/pydantic-ai-harness.git --path .agents/skills/branch-context--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add pydantic/pydantic-ai-harness --skill branch-context -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install pydantic/pydantic-ai-harness branch-context --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai-harness.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/branch-context .gemini/skills/branch-context && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "branch-context" agent skill from https://github.com/pydantic/pydantic-ai-harness/tree/main/.agents/skills/branch-context into .gemini/skills/branch-context/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "branch-context", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install pydantic/pydantic-ai-harness branch-contextInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add pydantic/pydantic-ai-harness --skill branch-context -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai-harness.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/branch-context .github/skills/branch-context && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "branch-context" agent skill from https://github.com/pydantic/pydantic-ai-harness/tree/main/.agents/skills/branch-context into .github/skills/branch-context/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "branch-context", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add pydantic/pydantic-ai-harness --skill branch-context -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install pydantic/pydantic-ai-harness branch-context --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai-harness.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/branch-context .opencode/skills/branch-context && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "branch-context" agent skill from https://github.com/pydantic/pydantic-ai-harness/tree/main/.agents/skills/branch-context into .opencode/skills/branch-context/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "branch-context", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
branch-context- GitHub stars
- 946
- Token cost
- ~1.7k tokens
- SKILL.md length
- 767 words
- Files
- 7
- Skills in repo
- 3
- Repo updated
- First seen
- Licence
- MIT
At a glance
Keeps a branch-local issue brief, decision log and session handoffs so a pull request's context survives across separate agent sessions.
- Works in 4 steps: Confirm the branch matches the brief's… → Read issue-brief.md, pr-decisions.md,… → Read the latest handoff -- the last… → …
- Picking up a pull request where a previous session left off
- SKILL.md covers Session defaults, When to write each surface, Session turnover and Scope boundary, plus 1 more section
- Runs Shell scripts from its folder; calls git
What it does
Three surfaces persist per branch: `issue-brief.md`, rewritten only when adopting or re-syncing a branch; `pr-decisions.md`, an append-only log of non-obvious PR-shaping decisions that gets superseded rather than edited; and a `handoffs/` folder plus index that is never overwritten, with the index always pointing at the latest entry.
At the start of a session it confirms the current branch matches the brief, reads the brief, the decisions and the latest handoff, and populates the brief from an adopt step or the linked issue if it is still an unfilled template. While working, a non-obvious decision is appended to the decisions log in the same turn it is made, and a handoff is written only when the user asks or session turnover is already decided, not because the context merely feels full.
When your agent uses it
- Picking up a pull request where a previous session left off
- Recording a non-obvious decision so it isn't lost between sessions
- Writing a handoff before switching tools or ending a session
Example prompts
- “Read the branch context before we continue work on this PR.”
- “Log that we chose approach A over B in the decisions file.”
- “Write a handoff for the next session since I'm wrapping up today.”
Requirements
- Bash
- A git branch tracking an issue or pull request
- Pre-approved tools (allowed-tools): Read, Write, Edit, Bash
Workflow steps
4 steps, taken from the first numbered list in SKILL.md.
- Confirm the branch matches the brief's branch: field
- Read issue-brief.md, pr-decisions.md, and handoffs-index.md.
- Read the latest handoff -- the last entry in handoffs-index.md points at
- If the brief is still the unfilled template, populate it first: run
What it can do on your machine
Read from SKILL.md and the folder at commit 4399efa. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves these tools, so the agent can use them without asking each time:
ReadWriteEditBash
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships script files (Shell), which the agent can run.
Shell commands in SKILL.md call:
git
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Branch Context Handoff loads about 1.7k tokens when it runs. Until then it costs about 65 tokens; SKILL.md has 767 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check: notes
The automated check noted patterns worth knowing about, such as sudo or a known installer.
- NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
allowed-tools: Read, Write, Edit, Bash
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from pydantic/pydantic-ai-harness at commit 4399efa, republished under its MIT licence (© pydantic). 767 words, ~1,661 tokens.
Download SKILL.mdSave it as
.claude/skills/branch-context/SKILL.md (or your agent's skills folder). This skill also uses 6 other files; get the full folder from GitHub.- name
- branch-context
- description
- Branch-local durable PR state -- issue brief, decisions log, and session handoffs. Read the brief, decisions, and latest handoff at session start; append decisions as you work; write a handoff only on user request or explicit session turnover.
- allowed-tools
- Read, Write, Edit, Bash
Branch Context
This directory is the home for durable PR/branch state that outlives a single session. Three surfaces:
| File / dir | Role | Lifetime |
|---|---|---|
issue-brief.md | Synthesis of the issue(s) this branch addresses | Rewritten only when adopting or re-syncing a branch |
pr-decisions.md | Append-only log of non-obvious PR-shaping decisions | Append forever; supersede, never edit |
handoffs/ + handoffs-index.md | Append-only session handoffs for the next agent | Never overwrite a handoff file; index points at the latest |
The instances (issue-brief.md, pr-decisions.md, handoffs-index.md,
handoffs/) are per-branch and git-ignored. The scaffolding (this file, the
scripts, the *.template.md files) is committed. Instantiate the instances from
the templates, or via /adopt-pr when a PR already exists.
Session defaults
On start, before coding:
- Confirm the branch matches the brief's
branch:field (git rev-parse --abbrev-ref HEAD). - Read
issue-brief.md,pr-decisions.md, andhandoffs-index.md. - Read the latest handoff -- the last entry in
handoffs-index.mdpoints at its file underhandoffs/. That is what the previous session left for you. If the index has no entries, there is no handoff yet; start from the brief. - If the brief is still the unfilled template, populate it first: run
/adopt-prwhen a PR already exists, or write it from the linked issue when starting fresh.
While working -- persist without being asked:
- A non-obvious decision (picking path A over B, a plan deviation, an ambiguous
thread resolution) goes into
pr-decisions.mdviaappend-pr-decision.shin the same turn you make it, not "later". - Disk in this directory is the continuity channel, not chat history. Do not rely on the conversation surviving a context clear or a new session.
- Do not write a handoff because the context "feels full" -- that misjudges and primes an early stop. Write a handoff only when the user asks, or when session turnover is already decided (the user is clearing, switching tools, or ending the sitting).
When to write each surface
issue-brief.md
Rewritten only when adopting a branch (/adopt-pr) or re-syncing after new
issue activity. Do not freestyle-edit it mid-session.
pr-decisions.md
Append whenever you make a decision the issue did not already spell out:
.claude/skills/branch-context/append-pr-decision.sh \
--title "<short title>" \
--decision "<one-line decision>" \
--why "<one-line why>" \
--source "<source url -- mandatory>" \
[--iter N] [--supersedes "<earlier title>"]Named flags are preferred (they resist arg-order mistakes). Positional order is
title decision why source [iter] [supersedes] -- do not pass iter as the
second argument.
Entry shape (the script writes this):
## YYYY-MM-DD · <short title> · iter <N or "-">
- Decision: <one line>
- Why: <one line>
- Source: <link -- mandatory>
- Supersedes: <earlier title, if applicable>When the decision restates a modal claim (always / never / only if / must / unless), quote that clause verbatim instead of paraphrasing -- "always X unless Y" compressed to "always X" is a different instruction.
Show full SKILL.md (366 more words)Show less
Handoffs
One handoff per session, newest last. Never overwrite another session's handoff.
.claude/skills/branch-context/append-handoff.sh [--writer <name>] "<one-line summary>" [path-to-body.md]--writer tags the index line with the skill that produced the handoff. If you
omit the body path, the script writes a stub you must fill in via Write/Edit
before stopping; prefer writing the full body first and passing its path. To
revise a handoff you already wrote this session, edit the file in place rather
than appending a second index entry.
Handoff body sections (required):
# Handoff · YYYY-MM-DD · <summary>
## Done
- ...
## Next
- ... (ordered; first item is what the next agent starts on)
## Commitments & constraints carried forward
- ... (verbatim; or "none")
## Key paths
- `path` -- why
## Open questions
- ... (or "none")
## Branch-context pointers
- Brief: issue-brief.md (still valid? yes/no)
- Decisions appended this session: <titles or "none">
- Related plan file (if any): <path>Commitments & constraints is a required check, not an optional extra. Before writing the handoff, sweep the session for two things and quote them verbatim -- do not paraphrase, the modality is the payload:
- Constraints the user stated that are not already in the brief's Constraints section. "Always X unless Y" and "always X" are different instructions, and a one-line paraphrase is where the qualifier gets dropped.
- Promises you made and have not kept -- to the user ("I'll add the regression test next"), or on the record in a PR/review comment ("I'll file a follow-up issue", "I'll re-run this once CI clears"). A promise made to a reviewer and then dropped across a session boundary is the expensive kind: the next agent cannot know it exists, and the reviewer is still waiting.
A longer, accurate handoff beats a short lossy one. Do not compress this section to save space.
Session turnover
Write the handoff (and any unlogged decisions) when the user turns the session
over. If the harness has a plan mode, capture the remaining work as a concrete
plan (next steps, files, verification), persist the handoff, then exit plan mode
so the fresh session inherits it. If the harness has no plan mode, persist the
handoff and tell the user to start a new session in this worktree whose first
action is to read handoffs-index.md and the latest handoff.
Scope boundary
- Not for research notes or repro scripts -- those belong outside this directory.
- Not for durable codebase facts that outlive the PR -- those belong in longer-lived project docs or memory. Rule of thumb: if removing the linked thread would make this PR's diff confusing, it is a decision; if the fact still helps after merge, it belongs elsewhere.
Helpers
.claude/skills/branch-context/status.sh # JSON: brief/decisions/handoffs state
.claude/skills/branch-context/append-pr-decision.sh ...
.claude/skills/branch-context/append-handoff.sh ...© pydantic, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 6 other files in .agents/skills/branch-context of pydantic/pydantic-ai-harness.
- SKILL.md
- append-handoff.sh
- append-pr-decision.sh
- handoffs-index.template.md
- issue-brief.template.md
- pr-decisions.template.md
- status.sh
Open the folder on GitHubat commit 4399efa
Compare with similar skills
Branch Context Handoff next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Branch Context Handoff this skillpydantic/pydantic-ai-harness | 946 | — | ~1.7k | Automated safety check: Notes | MIT | |
| Orca CLIstablyai/orca | 87k | 2 repos | ~593 | Automated safety check: Pass | MIT | |
| Beads Task Memorygastownhall/beads | 28k | — | ~1.2k | Automated safety check: Pass | MIT | |
| Session History Searchslopus/happy | 24k | — | ~3.1k | Automated safety check: Pass | MIT | |
| Paseo Agent Handoffgetpaseo/paseo | 20k | 1 repos | ~606 | Automated safety check: Pass | Custom licence | |
| Memori Long-Term MemoryMemoriLabs/Memori | 17k | — | ~2k | Automated safety check: Notes | Custom licence |
Similar skills
Beads Task Memory
gastownhall/beads
Tracks multi-session work with dependencies in the bd issue tracker so the agent can find ready tasks and recover its context after conversation compaction.
Session History Search
slopus/happy
Searches past Claude Code, Codex and Cursor sessions and summarizes what was worked on, tried or decided, using extraction scripts instead of reading raw logs.
Paseo Agent Handoff
getpaseo/paseo
Hands off the current task, including context, decisions and failed attempts, to a fresh agent through Paseo by writing a self-contained briefing prompt and launching that agent.
Memori Long-Term Memory
MemoriLabs/Memori
Connects Claude Code to Memori Cloud for long-term memory, recalling stored context before substantive replies and saving new context afterward.
Beads
liwp/again
A skill your agent uses when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory.
More from pydantic/pydantic-ai-harness
- Official
Adopt PR Branch Context
pydantic/pydantic-ai-harness
Fills in issue-brief.md and pr-decisions.md for an existing pull request, so you can pick up a PR mid-flight with its linked issue and past review decisions summarized.
- Official
Pushing Commits To The Repo
pydantic/pydantic-ai-harness
What to do when you open a PR and every time you push -- label the PR, watch CI to green, triage every review comment to a reply and a reaction, and escalate genuine design trade-offs to maintainers.
Related
Works with
Categories
Questions about Branch Context Handoff
What does Branch Context Handoff do?
Keeps a branch-local issue brief, decision log and session handoffs so a pull request's context survives across separate agent sessions. md`, an append-only log of non-obvious PR-shaping decisions that gets superseded rather than edited; and a `handoffs/` folder plus index that is never overwritten, with the index always pointing at the latest entry.
When should I use Branch Context Handoff?
Branch Context Handoff fits situations like: picking up a pull request where a previous session left off; recording a non-obvious decision so it isn't lost between sessions; writing a handoff before switching tools or ending a session.
How do I install Branch Context Handoff in Claude Code?
Run `npx skills add pydantic/pydantic-ai-harness --skill branch-context -a claude-code`. Or copy the skill folder (.agents/skills/branch-context in pydantic/pydantic-ai-harness) into .claude/skills/branch-context in your project. Claude Code loads it when a task matches its description.
How do I install Branch Context Handoff in Codex?
Run `npx skills add pydantic/pydantic-ai-harness --skill branch-context -a codex`. Or copy the skill folder (.agents/skills/branch-context in pydantic/pydantic-ai-harness) into .agents/skills/branch-context in your project. Codex loads it when a task matches its description.
Can I use Branch Context Handoff in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pydantic/pydantic-ai-harness --skill branch-context -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/branch-context, .gemini/skills/branch-context, .github/skills/branch-context and .opencode/skills/branch-context in your project.
What does Branch Context Handoff need to run?
Going by SKILL.md and its folder, Branch Context Handoff needs a shell for the scripts in its folder and the command-line tools its instructions call (git). Our summary lists: Bash; A git branch tracking an issue or pull request. Its frontmatter pre-approves these tools: Read, Write, Edit, Bash.
Does Branch Context Handoff access the network?
SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.
Is Branch Context Handoff safe to install?
Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.
What licence does Branch Context Handoff use?
Branch Context Handoff is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Branch Context Handoff use?
About 1.7k tokens (SKILL.md is roughly 6.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Branch Context Handoff?
Skills that share tags, products or a category with Branch Context Handoff: Orca CLI (stablyai/orca, 87k stars), Beads Task Memory (gastownhall/beads, 28k stars), Session History Search (slopus/happy, 24k stars) and Paseo Agent Handoff (getpaseo/paseo, 20k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Branch Context Handoff?
pydantic (a GitHub organization, an official publisher) maintains it in pydantic/pydantic-ai-harness, which has 946 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on October 2, 2026.
Source: pydantic/pydantic-ai-harness on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.