Collaborate with your colleagues—and combine all of your coding agents—on one shared GitHub
branch, coordinated through GitHub Projects v2 and GitHub Issues inside both the
Herdr desktop app (herdr-app + herdr-core / hc, as a native GPUI
board mod) and the herdr TUI.
No custom backend server, no mutual SSH access between colleagues' laptops, and zero Python
runtime dependencies beyond Python 3.11+, git, and gh.
- One shared branch, isolated local worktrees:
- Your team points
.herdr-kanban.tomlat a GitHub Project v2 board and a shared target branch (for examplefeat/unified-auth). - Whenever an issue is claimed or dispatched,
herdr-kanbancreates an ephemeral local Git worktree offorigin/<target-branch>and opens a Herdr tab inside it so Claude Code, Antigravity (agy), Codex, OpenCode, Gemini CLI, or Copilot CLI runs with full sandbox access and never dirties another local agent's working tree.
- Your team points
- Conflict-free distributed claims (zero comment spam):
- Claiming posts one structured comment (
<!-- herdr-kanban:v1 ... -->). Earliest GitHub comment ID wins simultaneous races; losers roll back automatically. - Heartbeats, progress checklists, and touched file paths
PATCHthat same comment in place—giving teammates live file-overlap warnings without notification spam. - Stale leases (>30m) are flagged
STALEfor explicit takeover; local panes closed with zero commits auto-release back toReady.
- Claiming posts one structured comment (
- Triage-first issue deposits:
- Agents deposit newly discovered bugs/follow-ups via
herdr-kanban deposit, landing inTriage(linked to parent issue +file:line) until a human promotes them toReadywithtin the TUI.
- Agents deposit newly discovered bugs/follow-ups via
- Cross-colleague agent-to-agent messaging:
herdr-kanban ask <issue> "..."posts a structured relay comment and wakes the target agent when authored by a trusted collaborator (or uses the local /herdr --machinefast path).
- Guarded shared-branch landing:
herdr-kanban done <issue>fetchesorigin/<target-branch>, rebases the worktree, runs the board'scheck_command, fast-forward pushes toorigin/<target-branch>(or pauses inReviewwhen gated), moves the card toDone, and closes the GitHub Issue immediately.
- Herdr
>= 0.9.3 - Python
>= 3.11 git- GitHub CLI (
gh) authenticated withrepoandprojectscopes:gh auth login gh auth refresh -s project
Paste this prompt to any coding agent running in your Herdr window:
Read ~/.config/herdr-app/AGENTS.md, then add this mod: https://github.com/jellespijker/herdr-kanban
Or install from a terminal:
git clone https://github.com/jellespijker/herdr-kanban.git ~/.local/share/herdr-kanban
cd ~/.local/share/herdr-kanban
./bin/herdr-kanban install-skill
./bin/herdr-kanban install-app-mod
./bin/herdr-kanban setup-keys
herdr-app check ~/.config/herdr-app/mods/herdr-kanban- Installed as
mods/herdr-kanban(~/.config/herdr-app/mods/herdr-kanban) so it coexists cleanly alongside the built-in agent-statusmods/kanbanlayout. - Open the native GPUI board with
Ctrl+Shift+M,herdr-kanban open --mod, orherdr-app do mod.open herdr-kanban. - Supports remote
hcspaces across connected peer machines automatically ({ cwd, on }).
From GitHub:
herdr plugin install jellespijker/herdr-kanbanOr link a local checkout during development:
herdr plugin link /path/to/herdr-kanbanThen run two one-time setup commands (or trigger them from Herdr's plugin action menu):
bin/herdr-kanban install-skill # links SKILL.md + ~/.local/bin/herdr-kanban + Herdr-App GPUI mod
bin/herdr-kanban setup-keys # binds prefix+m (TUI) and ctrl-shift-m (Herdr-App) to open the board-
On your shared branch, connect a GitHub Project v2:
herdr-kanban init --interactive git add .herdr-kanban.toml && git commit -m "Configure herdr-kanban board" && git push
When your colleagues pull the branch, their
herdr-kanbanconnects automatically. -
Open the Kanban board inside Herdr (
prefix+morherdr-kanban open):h/l: switch columns (Triage,Ready,In Progress,Blocked / Review,Done)j/k: select ticketEnter/s: claim & dispatch default coding agent in a fresh worktree tabA: pick a specific coding agent (claude,agy,codex,opencode,gemini,copilot)f: jump to the local Herdr agent pane working on the selected tickett: promote aTriageissue toReadya: approve aReview-gated ticket and push to the shared branchc: send a cross-agent message/comment to a ticketn: create a new Ready ticketw: toggle the What's New colleague & agent landed work briefing (sto synthesize)
GitHub Projects v2 naturally span multiple repositories (firmware, cloud, software, etc.).
To coordinate across multiple repos on a shared feature branch:
- Create a parent directory (either a plain folder or a small Git meta-repo) and clone your repos
inside it:
mkdir acme-platform && cd acme-platform gh repo clone acme/firmware gh repo clone acme/cloud gh repo clone acme/software herdr-kanban init --interactive # auto-discovers firmware, cloud, software into [repos.<alias>]
- Teammates who pull or copy
.herdr-kanban.tomlinto their umbrella folder can clone any missing repos and align every repo onto the sharedtarget_branchin one step:herdr-kanban sync-repos --create-branches
- Tickets are displayed and addressed as
<alias>#<number>(firmware#10,cloud#18), so issue#10infirmwareand issue#10incloudnever collide. - When an agent is dispatched into an ephemeral worktree for
cloud#18,herdr-kanbanautomatically symlinks.siblings/firmwareand.siblings/softwareinside that worktree (and excludes/.siblings/via Gitinfo/exclude), giving sandboxed coding agents read access to sibling repos while keepinggit statusclean.
Installed coding agents receive the herdr-kanban skill automatically:
herdr-kanban board
herdr-kanban whats-new --generate
herdr-kanban list --column ready --unclaimed --json
herdr-kanban claim 42 --json
herdr-kanban progress 42 --note "Parser implemented" --check "[x] Parser" --check "[ ] Tests"
herdr-kanban deposit "Handle empty token header" --parent 42 --file-line "src/auth.py:88"
herdr-kanban ask 41 "Did you rename SessionStore?" --from 42
herdr-kanban inbox --ack
herdr-kanban done 42 --summary "Added parser and unit tests"See docs/spec.md and docs/adr/.
uv run pytest
uv run ruff check src tests
PYTHONPATH=src uv run lint-imports