@agimon-ai/po-git

Git worktree sessions for Po: spawn an isolated worktree with its own session and manage it from the parent

This package is a composable Po subsystem. Select it through the native distribution configuration.

Requirements

• Node.js 24 or newer
• A Po native server host

Install

Add @agimon-ai/po-git to a selected layer in .po/modes.yaml, then run po sync. Native metadata selects its server and browser plugins; there is no standalone Pi entry.

Use

Use the browser worktree controls, or an agent session. In code mode the worktrees namespace (list, status, spawn, close, merge, prune, send, messages) returns structured records and the run_worktree tool is withdrawn from the model for that session; without code mode run_worktree stays. The codemode-how-to-git skill carries the usage rules.

New-session dialog

In the web cockpit, po-git replaces the new-session dialog for a git workspace. It offers three choices:

• Existing branch: a worktree session on a local branch, or on a remote-only branch (a local tracking branch is created). Branches already checked out elsewhere are disabled.
• New branch: a worktree session on a new branch from a base, preselected to the repository's default branch.
• No branch: a plain session in the workspace folder.

Worktree sessions opened here start at the top level of the session rail, with no parent. A workspace that is not a git checkout offers the plain session only. For remote devices, creating a worktree session needs the same passkey step-up as any new session.

Worktree setup

A new worktree has no node_modules or builds. Put the commands that prepare one in .po/worktree.yaml at the repository root:

setup:
  - pnpm install --frozen-lockfile
  - pnpm build

After the worktree session starts, po-git runs them in the worktree, in order and stopping at the first failure, as that session's runner worktree-setup (po-runner's /runners start), so the log is under Runners. A delegated task tells the agent setup is still running. The file is read from the checkout the worktree is created from; a malformed file refuses the spawn before any branch or checkout exists. The worktree session's own extensions do not need this: they load from the workspace checkout.

Package behavior

Review this session's changes

The # git group in the activity dock shows the focused checkout's branch and +added -removed, followed by its worktrees. Regular and worktree sessions use the same diff row, even when they have no child worktrees. The row opens review (g d); the group heading opens worktrees (g w). The counts measure this session's checkout against its base, the way a pull request counts it: every commit since the branch left its base, plus staged, unstaged and untracked work. The base is the worktree's recorded base when the session owns one, then the remote's default branch (origin/HEAD, origin/main, origin/master), then the branch's upstream; with none of those only uncommitted work counts. The count refreshes after every tool call and settled turn; nothing polls.

The lane opens the review tab: changed files grouped by folder on the left, every diff stacked on the right. Select lines, or click a line number, to write a comment under that line; a comment on a removed line points at the old file. Comments queue on the tab, and send review hands them to the agent as one message, queued behind a running turn rather than dropped.

Pull, push and rebase

The review tab's header runs them by hand, one at a time per session:

• pull fetches, then rebases local commits onto the upstream.
• rebase fetches the base's remote, then rebases onto the base.
• push sets the upstream on a first push. A push the remote rejects after a rebase asks first, then forces with --force-with-lease --force-if-includes, which git refuses if the remote holds commits this branch never fetched and integrated.

Pull and rebase refuse uncommitted changes. A rebase that stops on conflicts stays paused and lists the files, with ask agent to resolve and abort rebase.

Remote auth, per workspace

Settings, then repository, then git remote, sets how one workspace's sessions reach the remote when you pull, push or rebase from the cockpit: this machine's own git (the default), an SSH key path (blank uses your ssh config and ssh-agent), or an HTTPS username and token for one host. Worktree sessions use their workspace's setup.

The setup lives outside every repository in ~/.po/git/credentials.json (folder 0700, file 0600). The token is write-only: the page shows only that one is saved. It goes into the environment of one git fetch or git push at a time, only for the host it was entered for, with git's credential helper list emptied first so the macOS keychain never stores it. The agent's own git commands never see these credentials. Saving from a remote device needs passkey step-up. An unknown SSH host is refused: trust it once with ssh -T git@<host> in a terminal.

Help

The native server root registers codemode-how-to-git as a skill resource and the package index as Help-gated context. Guidance stays published under src/prompts and is not exported or copied into dist.

Public API

import { DefaultGitExtensionService } from '@agimon-ai/po-git';

The service layer is host-neutral. The native session server root owns worktree operations, resources, hooks, and message-inbox disposal. Browser routes own presentation. Public symbols are forwarded through flat src/exports files.

Development

pnpm build
pnpm typecheck
pnpm test
pnpm lint
pnpm exec vibe-lint check .
npm pack --dry-run

Maintained by Agimon.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.

Native routed declarations own commands, APIs, resources, hooks, and tools. Services own worktree operations and filesystem persistence. Session delivery is consumed through the fixed Session service; no terminal compatibility entry is published.