pi-odd-worktree
Pi package for odd-worktree: the Git worktree tools a Pi session uses (create and list the checkouts the agent works in), the /warp worktree panel, the /odd ODD viewer, and the /issues GitHub issue reader. Needs only Pi and git: no companion app, no extra
Package details
Install pi-odd-worktree from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-odd-worktree- Package
pi-odd-worktree- Version
3.7.1- Published
- Nov 22, 2026
- Downloads
- 2,171/mo · 610/wk
- Author
- jonasotoaguilar
- License
- MIT
- Types
- extension
- Size
- 4.9 MB
- Dependencies
- 0 dependencies · 3 peers
Pi manifest JSON
{
"extensions": [
"./extensions/odd-worktree-tools.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-odd-worktree
A Pi extension that gives an agent session worktrees, ODD documents and GitHub issues, with git as its only external requirement.
What It Does
Two agent tools, four panels, one background-explorer command, one sidebar section and two tool designs, loaded from one extension entry point. Each ODD feature gets its own checkout beside the clone, and you move between checkouts and read your ODD documents, files and issues without leaving Pi.
| Surface | Kind | What it does |
|---|---|---|
worktree_create |
tool | Creates <repo-parent>/<repo-name>-worktrees/<odd> on a branch, prepares it and starts its install in the background. |
worktree_list |
tool | Read-only list of the checkouts this package created, each by its ODD and branch. |
/warp |
panel | Moves this session to another checkout, creates one, and removes one. |
/odd |
panel | Reads this checkout's odd/tasks/*.md: list on the left, styled markdown on the right. |
/files |
panel | Browses one checkout's files with a live, language-coloured preview: enter pastes the chosen paths into your prompt, ctrl+e opens the file in $EDITOR. |
/issues |
panel | Reads this checkout's GitHub issues — the three scoped tabs on open, every open issue behind g — and, when your role allows it, edits them. |
GITHUB rail section |
sidebar section | Lists the open issues of this checkout's repository assigned to you, seven at a time plus a count of the rest; a click opens that issue in /issues on Assigned and the overflow row opens /issues. Needs gh and gentle-shell-bridge with its rail; without gh on PATH it is never added to the rail at all. |
activity tags design |
design on the bridge's Card tags line |
Optional: /gentle:customize → Cards → Card tags, with default (the host's own card) and activity, which is selected for you on the first run. It covers bash, the read-only shell tools grep, find, ls, and read, write and edit: a bash card's heading names what the command does, each family in its own theme colour (⌕ exploring, ✓ checking, …; an unnamed command reads $ bash), those three are always ⌕ exploring, and a read — which runs no shell command — is left exactly as the host drew it. read, write and edit are covered so that the file card can ask about them too, write and edit through a scope limited to skill and ODD paths (gentle-shell-bridge 0.9.0): the design draws nothing of its own for any of the three, so a read, a write or an edit on a skill or an ODD artifact is the file card's row and everything else stays the host's. A finished call shows its duration on the closing rule and the frame turns warning while the call runs and error when it fails. Needs gentle-shell-bridge 0.6.0 or newer for the one Card tags row over the six tools, and 0.9.0 for edit and the scope that claims a write or an edit; on 0.5.0 the row is Card bash, covers bash alone and keeps everything above for bash cards. Registered through gentle-shell-bridge's registerToolDesign; the bridge owns the choice, remembers it and repaints cards already on screen. |
color diff design |
design on the bridge's Card diff line |
Optional: /gentle:customize → Cards → Card diff, with default (the host's own card) and color, which is selected for you on the first run. It covers write and edit and redraws them as an IDE pane: a write's content behind a line-number gutter, and an edit's diff, both in the active theme's own syntax roles from Pi's highlighter — the same one /files previews with. A write or an edit on a skill or an ODD artifact stays the file card's row, because the Card tags line claims exactly those calls and a specific claim wins over this generic one. Needs gentle-shell-bridge 0.9.0 or newer; on anything older nothing is registered and Card diff never appears. |
Moving the session and removing a checkout are human actions: only /warp does either, and no agent tool can. A checkout has one identity, its ODD: the directory name is the ODD it serves, and branch is only the git branch.
The activity design is not a preference of this package: it adds that value to the bridge's own line, Card tags on a bridge that can put several tools on one (0.6.0 and later) and Card bash on anything older, which keeps default (the host's own card, stored as native) available. The bridge names that row after the line's own key, so the grouped row was Card tools and is Card tags now — the older single row was always Card bash, and it was never renamed. The rename is one-time, and no choice is lost with it: a value you already stored on Card tools is carried over to Card tags before the design registers, so a default you picked stays default (a stored value the bridge could not read as a choice — anything but a non-empty, non-blank id string, native included — is left exactly where it is, and the document is not written at all). On the first run, and only when you have not chosen yet, the package selects activity once — before it registers the design, so a 0.6.0 bridge carries that choice over to the grouped line — and a later choice of default is never undone. The colours are theme roles, so a theme that gives two roles the same colour draws those two families alike. Load order does not matter. See the cards the activity design paints.
The diff card is a design of the same kind, on a line of its own: Card diff, with default (the host's own card, stored as native) kept available and color selected once on the first run that finds no choice. It registers nothing at all on a bridge older than 0.9.0, because its line needs the per-(line, tool) claim that release introduced, and the Card tags line claims a write and an edit on a skill or an ODD artifact through a scope, so that specific claim wins and those stay the file card's. See the diff card.
The file cards are not a preference of this package either: they belong to that same activity value. While the bridge answers that activity draws the tool being painted, a read, edit or write call on a skill or an ODD artifact heads as that file — its own mark and label, the tool, the path and a read's line range, each in the theme role the reference design gives it — instead of a bare tool row, and its Markdown body is drawn by Pi's own renderer with the theme's Markdown roles. Choosing default on Card tags, or any other design on that line, gives every one of those calls back to the host. The question is asked of the bridge on every paint, so a mid-session switch repaints cards already on screen, and a bridge older than 0.7.0 — which cannot answer it — keeps the card it always had. See the file cards.
The jobs card follows the same value. Gentle Shell registers bash_background, monitor, job_stop and job_list with no renderer of their own, so Pi draws them in a plain box and neither neon nor float ever reaches them. While the bridge answers that activity draws the tool being painted, they are drawn on the same card substrate in the style the shell has chosen: the job's mark and name (its label, else the first line of its command), the whole command when expanded, and the job's own answer below. Under the minimal card content level the call is drawn alone, and a failure still says why. Any other answer on Card tags, no bridge, or a bridge older than 0.7.0 leaves Pi's own box exactly as it was. Unlike the file cards, the answer is read when a job card is built, because there is no host drawing to hand back on a later paint: a switch made mid-session reaches the next job card. See the jobs card.
The two advisory messages Gentle Shell sends follow that same value, through the bridge's message-design surface rather than a tool renderer: gentle-pi.exploration-budget heads as ⌕ Exploration budget and gentle-pi.verifier-settle-reminder as ⚑ Verifier reminder, each with the numbers the message states as its detail, drawn on the same card substrate in the style the shell has chosen. Their body is never clipped — both are instructions the agent must read, so every row is drawn at any card content level, with no preview and no expand hint — and the bridge's own [customType] label row is dropped because the card's heading already names the alert. There is no second switch: each design FOLLOWS the Card tags line, so activity paints both alerts, live — flipping that line repaints the messages on screen and turns them off again — and /gentle:customize gains no row for them. A bridge older than 0.12.1 cannot keep that follow promise — 0.12.0 let a leftover stored value veto it — and gets no registration at all, so Pi's own box stays byte-identical; only a clean numeric release is trusted, and there is no capability probe. An inactive alert costs a registry walk and at most one tool-document read, and paints nothing. See the message cards.
Quick Start
| Requirement | Why it is needed |
|---|---|
Pi (@earendil-works/pi-coding-agent, @earendil-works/pi-tui) |
Peer dependencies supplied by the host; the package installs no runtime dependencies. |
Node.js >= 18 and git |
Every repository operation is a git child process. |
gh, authenticated (gh auth login) |
/issues and the GITHUB rail section, and them alone. Without it neither is registered at all — /issues never loads and the section is never added to the rail, so there is nothing to refuse and no line to draw — and every other surface keeps working. |
| Gentle Shell (recommended) | Supplies the session records the deletion guard reads to see other sessions. |
Gentle Shell with gentle-shell-bridge (and its rail, for the section) |
Every surface this package registers. The activity value of the Card tags line (or Card bash, on a bridge older than 0.6.0) in /gentle:customize → Cards — which the skill/ODD file cards obey too — and the GITHUB rail section, which needs the rail too. The file picker's alt+p and the issues panel's alt+i are not the bridge's: both are bound directly on the host, and GENTLE_PI_FILES_KEY / GENTLE_PI_ISSUES_KEY override the keys. Install it with pi install npm:gentle-shell-bridge, or gentle-shell install npm:gentle-shell-bridge inside a Gentle Shell session. Without it the package loads nothing at all — no command, no tool, no card, no rail — and only names that install line, in a primary session. |
# plain Pi
pi install npm:pi-odd-worktree
# inside a Gentle Shell session: its launcher, same place
# (the bridge above is the prerequisite for every Gentle Shell surface)
gentle-shell install npm:pi-odd-worktree
From a local clone, pi install . installs the working copy, and gentle-shell install . does the same from inside a Gentle Shell session.
Expected result: /warp, /odd, /files and /issues are available as commands — /issues only where gh is on PATH — the agent is offered worktree_create and worktree_list, a Gentle Shell whose gentle-shell-bridge is installed and whose rail is drawn shows a GITHUB section for this checkout, and its /gentle:customize → Cards page offers activity on its Card tags line — Card bash on a bridge older than 0.6.0.
Core Workflow
- Create a checkout with
worktree_create(anoddand abranch) or presscin/warp. It answers at once; the install continues in the background. - List with
worktree_listor by opening/warp. - Move with
/warp <name>, or pick a checkout in the selector. - Delete with
ctrl+don a checkout in/warp, after its confirmation.
The full rules of each step, including every refusal, are in Create, list, move and delete, in detail.
Key Features You Should Know About
- A create is instant and writes no state. The directory is the whole record; there is no list file and no lock file.
- Deleting refuses on a live session. The guard reads Gentle Shell's presence records, discloses what it could not resolve, and never auto-warps. Removal is
git worktree removeand the branch is kept. See the deletion guard. - A warp is queued, never dropped. While this session's tools, agent tasks or background jobs are still running,
/warpkeeps the request pending and moves when they finish. See the queued warp. /fileslists one checkout's files and pastes them. It always asks for a checkout first —mainincluded, even with nothing else registered — offeringmain, the current checkout and the worktrees this session registered, withawidening the list to every worktree Git lists for the clone;ctrl+ocyclesfiles,treeandext(the trees open folded,spacefolds the focused group andshift+spacecollapses or expands every group), and the preview is read-only, bounded and coloured from your active theme.enterinserts@-prefixed paths — a file of another checkout travels as its absolute path instead, because@would resolve against the wrong directory — andctrl+eopens the highlighted file in$VISUAL/$EDITOR.alt+popens the picker from anywhere: the shortcut is bound directly on the host, andGENTLE_PI_FILES_KEYoverrides the key. See the file picker./issuesopens on three tabs, not four. The bar isMy issues,AssignedandInvolved;Allis thegshortcut's own view, read the first time you enter it and reused after that, with the footer sayingg all issuesoutside it andg related issuesinside. A typed filter spans the three tabs and travels with you intoAll, which then reads a capped search and says so instead of claiming an exact total.alt+iopens the panel from anywhere: the shortcut is bound directly on the host, andGENTLE_PI_ISSUES_KEYoverrides the key. See the tabs, the shortcut and the filter./issuescan open on one issue./issues 42(or/issues #42) opens the panel onAssignedwith that issue selected, and a number that tab cannot find says so instead of guessing a row./issuespins the repository. Every read, mutation and browser open is bound to the repository that was loaded, and capabilities fail closed. See the repository pin.- The issues rail is checkout-scoped and optional. When a Gentle Shell has
gentle-shell-bridgeinstalled and draws its rail, aGITHUBrail section lists the open issues of this checkout's repository assigned to you — that one repository, not every issue across every repository you touch — seven at a time, withand N more issuesfor the rest and a pull-request mark on the issues that already have one. A click opens that issue in the/issuespanel onAssigned, not in a browser: the click first proves the number belongs to this checkout, so a row left over from another checkout — or a checkout whose repository cannot be proven — opens nothing instead of guessing, and/issues' ownokey is still the browser. The overflow row opens/issueswith no number. While the rail's cache holds this repository,/issuespaints its first frame from it and reads one tab at mount instead of three, the other two reading the first time you open them; the cache outlives both the session and the process — one document under$XDG_CACHE_HOME/odd-worktree/— so a warm checkout's first read is already a delta. A frame never waits ongh, and neither does a session start: theghgate is dispatched, never awaited, so no child process and no network call sits on opening or switching a session. While the section is drawn it re-reads on its own 20 s timer, keeps no timer while hidden and stops the moment it is no longer drawn, and abashcommand that mutates an issue or a pull request forces one read behind a 5 s cap; a failed refresh keeps the rows and marks themstalerather than emptying the list. WithoutghonPATHneither the section nor/issuesexists at all — the command is never registered and the section is never added to the rail — and every other surface keeps working. With no bridge the section simply never appears; the one thing you get is a single warning naming the install command, in a primary session only. See the rail section. - Cards follow your shell. Tool and warp cards use the card style Gentle Shell publishes, and a click expands that card only. See card style.
- Tool headings can name the activity. With
activitychosen on theCard tagsline, a bash card whose heading shows the whole command is headed with the family its command names (mark and word) instead of$, and agrep,findorlscard is headed⌕ exploringinstead of its own glyph and name, while aread— which runs no shell command — keeps the host's own card, colour and width; a bash command the classifier cannot name, or a heading that hides part of it, keeps the host's$. See the cards theactivitydesign paints. - File calls on a skill or an ODD are cards too. While
Card tagsanswers withactivityfor the tool being painted, aread,editorwritecall whose path names a skill (anything below askillsfolder) or an ODD (anything below anoddfolder) heads as that file, with the tool, the path and a read's line range; its Markdown body — the whole document when expanded, the first rows when collapsed — is drawn by Pi's own renderer in the theme's Markdown roles — for anedit, the fragment it leaves behind, never its diff, and a call that leaves no fragment falls back to its own rows. Any other file call, and every call while that line answers anything else, is the host's own row. See the file cards. - Background-job tools are cards too. While
Card tagsanswers withactivityfor the tool being painted,bash_background,monitor,job_stopandjob_listare drawn in the shell's own card style instead of Pi's plain box. Any other answer leaves Pi's box untouched. See the jobs card. - The two advisory messages are cards too. While
Card tagsanswers withactivity,gentle-pi.exploration-budgetandgentle-pi.verifier-settle-reminderare drawn as⌕ Exploration budgetand⚑ Verifier reminderin the shell's own card style, the whole body at every content level. They follow that line — no second switch, no row added toCards, and a flip repaints the messages on screen and turns them off again. Any other answer hands the message back as Pi drew it, for the price of a registry walk and at most one tool-document read, and a bridge older than0.12.1— or one whose release string is not a clean numeric release — registers nothing at all. See the message cards. editandwritecannot land in the principal checkout's default branch. A write whose path is inside the principal checkout of the session's repository, while that checkout is on the default branch, is refused with one line pointing atworktree_listandworktree_create. Paths outside the repository, anything under the OS temp directories, other repositories and linked worktrees are never blocked. See the guard.bashcannot leave the principal checkout's default branch. Agit worktree addorgit worktree listis refused in any cwd and pointed atworktree_createandworktree_list; in the principal checkout, a switch that would leave the branch it is on is refused while that branch is the repository's default, and creating a branch is not blocked. See the guards.- Two blocks in the system prompt.
## ODD worktreestells the agent how worktrees and ODDs work.## CodeGraphtells a session that already holds a CodeGraph tool how to use it, with one text per role. Both are appended after the host's own text, andODD_WORKTREE_PROMPT=0suppresses them. See the prompt blocks. - CodeGraph stays fresh, only when its CLI is installed. At session start the package creates or syncs the checkout's index and warms its daemon, and makes sure your global
mcp.jsonhas thecodegraphentry (it adds it or fixes only the differing fields and keeps the rest). It also syncs after a compaction, after a nativecodegraph initand after aneditorwrite, in the background and without ever blocking you. See CodeGraph. Its tool rows are drawn as a card. - Two reminders keep a session on the CodeGraph rule. The first
grep,find,ls,readorbashsearch in a checkout gets one sentence appended to its result: usecodegraphfirst, or — for another checkout — callmcp__codegraph__codegraph_explorewith that path asprojectPath. Each message that starts with a search instead of the graph gets the one about your own checkout once, on its first search, and no later search of it repeats it (a new request re-arms it, a compaction starts it from zero); the one about another checkout stays once per checkout; neither is ever a block. See the reminders. - Deliberately absent. No customize panel, no plugin-tools toggles, no companion-app integration and no worktree-to-issue association. There is nothing to configure here: the tools design — and, with it, the skill/ODD file cards — is chosen on the bridge's own
Card tagsline (orCard bash, on an older bridge), so this package owns no preference of its own.
Documentation
| Your task | Start here |
|---|---|
| Look up a panel key | Panel keys |
| Understand a create, a warp or a delete in detail | Reference |
| Run the suite or see what CI and releases do | Tests, CI and releases |
| Change the package, follow its invariants or cut a release | docs/codebase/mental-model.md |
| Report a bug or request a feature | .github/ISSUE_TEMPLATE/ |
| Open a pull request | .github/PULL_REQUEST_TEMPLATE.md |
Next Steps
- Run
/warpin a repository with at least one other checkout to see the selector, thenworktree_listfrom the agent to confirm both surfaces agree. - Install
ghand rungh auth loginonce if you want/issues. - Install Gentle Shell if the deletion guard should see sessions other than the one you are in.