{"id":51599895,"url":"https://github.com/mkdir700/herdr-plugin-worktree","last_synced_at":"2026-07-11T21:01:54.605Z","repository":{"id":368591028,"uuid":"1285869956","full_name":"mkdir700/herdr-plugin-worktree","owner":"mkdir700","description":"herdr plugin: start a git worktree from a GitHub issue (new branch, claude-named), a PR, or a raw branch name — auto-detected","archived":false,"fork":false,"pushed_at":"2026-07-01T09:41:37.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T10:23:36.455Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkdir700.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-01T08:12:11.000Z","updated_at":"2026-07-01T09:41:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mkdir700/herdr-plugin-worktree","commit_stats":null,"previous_names":["mkdir700/herdr-plugin-worktree"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mkdir700/herdr-plugin-worktree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdir700%2Fherdr-plugin-worktree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdir700%2Fherdr-plugin-worktree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdir700%2Fherdr-plugin-worktree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdir700%2Fherdr-plugin-worktree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkdir700","download_url":"https://codeload.github.com/mkdir700/herdr-plugin-worktree/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdir700%2Fherdr-plugin-worktree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35375153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-11T21:01:53.039Z","updated_at":"2026-07-11T21:01:54.599Z","avatar_url":"https://github.com/mkdir700.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# herdr-plugin-worktree\n\nA [herdr](https://herdr.dev) plugin covering the full worktree lifecycle\naround GitHub work: **create** a worktree from a GitHub issue, a PR, or a\nbranch name, and **remove** the focused worktree when you're done — both\nforce-aware, so a dirty checkout never silently fails to delete.\n\n## `create` — start work from an issue, PR, or branch\n\nStarts work **from a GitHub issue, a PR, or a branch name** — all behind one\noverlay. It **auto-detects** what you paste and picks the right strategy: an\n**issue** gets a brand-new branch + worktree (with names drafted from the\nissue content); a **PR** or a raw **branch name** has its existing **remote**\nbranch imported into a worktree. An agent is launched inside the checkout\neither way.\n\n### Why not `github-start`\n\n[`ogulcancelik/herdr-plugin-github-start`](https://github.com/ogulcancelik/herdr-plugin-github-start)\ncreates a *tab* with a mechanical `gh-issue-614` label, never reads the issue\nbody, and never touches git worktrees. This plugin reads the issue, drafts\nmeaningful names from it, and creates an isolated worktree — so each issue\ngets its own branch and checkout, ready for parallel agent work. It also\nimports existing PR/remote branches, which `github-start` does not do.\n\n### Input detection\n\nThe overlay accepts any of these and routes accordingly:\n\n| Input | Detected as | What happens |\n| --- | --- | --- |\n| issue URL, `issue 614` | issue | new branch, claude-named (flow below) |\n| PR URL, `pr 614` / `pull 614` | PR | import the PR's remote head branch |\n| `#614` / `614` (bare number) | probed via `gh pr view` | PR if it's a PR, else issue |\n| `feature/login`, `origin/feature/login` | branch | import that remote branch |\n\nPR and branch imports use `git fetch` (PRs via `pull/\u003cn\u003e/head`, so fork PRs\nwork too without adding a remote), keep the **original branch name**, then\n`herdr worktree open --branch \u003cname\u003e` checks it out into a worktree. An\nexisting local branch of the same name is reused, never clobbered.\n\n### Issue flow\n\n1. Paste an issue URL / `#614` / `issue 614` in the overlay, pick an agent.\n2. `gh issue view` pulls the title, body, and labels.\n3. `claude -p` drafts `{ branch, workspace }` from that content — e.g.\n   `614-fix-login-redirect` + a short workspace label. Falls back to a\n   deterministic `issue-\u003cn\u003e-\u003ctitle-slug\u003e` if `claude` is missing or the output\n   can't be parsed (naming never blocks the flow).\n4. `herdr worktree create --branch \u003cbranch\u003e --label \u003cworkspace\u003e` makes the\n   worktree, **branched off the repo's default branch** (auto-detected — not\n   whatever branch you happened to trigger from).\n5. If the checkout has a `.superset/config.json`, its `setup` commands run\n   **directly in the worktree's root pane** — you see the output live, and the\n   plugin blocks on `herdr wait output` until they finish (or `setupTimeoutMs`\n   elapses) before the agent starts. So `bun install` / submodule init happen in\n   full view instead of a silent overlay that disappears.\n6. The chosen agent starts in that same pane. The plugin waits for it to be\n   detected `idle`, lets its TUI settle (`afterAgentStartMs`), then **pastes**\n   the seed prompt (`herdr pane send-text`, so newlines and backticks stay\n   literal) and submits it with Enter — so the initial prompt reliably lands in\n   the input box instead of being typed before the agent is ready.\n\n### Naming\n\nThe \"agent drafts the names\" step is a single non-interactive `claude -p`\ncall, not a full interactive agent — names must be decided *before* the\nworktree (the agent's working dir) exists. Tune or disable it in\n`config.json`:\n\n| Key | Effect |\n| --- | ------ |\n| `defaultAgent`    | `claude` or `codex` (the interactive agent started in the worktree) |\n| `baseRef`         | branch off this ref; empty = auto-detect the repo default (`origin/HEAD`, else `main`/`master`/`develop`) |\n| `namingModel`     | model for the naming call (empty = your `claude` default) |\n| `promptTemplate`  | issue seed prompt; `{url}` `{title}` `{number}` `{branch}` `{workspace}` |\n| `prPromptTemplate` | PR seed prompt (import flow); same placeholders |\n| `branchPromptTemplate` | raw-branch seed prompt; `{branch}` `{workspace}` |\n\nConfig seeds from `config.example.json` on first run. Find it with:\n\n```bash\nherdr plugin config-dir worktree\n```\n\n## `remove` — force-aware delete of the focused worktree\n\nherdr's built-in `remove_worktree` calls `herdr worktree remove` **without\n`--force`**. A worktree with uncommitted/untracked changes (or git submodules)\nis \"dirty\", so git refuses to delete it and herdr returns\n`dirty_worktree_requires_force` — leaving the checkout **directory on disk**.\nBecause a worktree is the agent's working dir, it's almost always dirty, so\nthe built-in action looks like it does nothing.\n\nTargets the **focused** workspace (resolved from `herdr workspace list`):\n\n- **clean worktree** → removed immediately, headless, with a notification.\n- **dirty worktree** → opens a confirmation overlay listing the\n  uncommitted/untracked changes; force-removes (discarding them) only after\n  you type `y`.\n- **main checkout / non-worktree workspace** → just closes the workspace\n  (same as herdr's built-in `close_workspace`), so a single \"delete\"\n  keybinding behaves correctly whether you're in a worktree or a plain\n  project.\n\nNo config for this action.\n\n## Install\n\n```bash\nherdr plugin install mkdir700/herdr-plugin-worktree --yes\n```\n\nFor local development, link a checkout instead:\n\n```bash\nherdr plugin link /path/to/herdr-plugin-worktree\n```\n\n## Keybinding\n\nThis plugin registers two actions (`create`, `remove`) plus their overlay\npanes (`prompt`, `confirm`) — it doesn't ship keybindings. Bind them yourself\nin the consumer's `config.toml`, e.g.:\n\n```toml\n[[keys.command]]\nkey = \"prefix+shift+i\"   # i = issue/import\ntype = \"plugin_action\"\ncommand = \"worktree.create\"\ndescription = \"start worktree from github issue/PR\"\n\n[[keys.command]]\nkey = \"prefix+shift+d\"   # d = delete\ntype = \"plugin_action\"\ncommand = \"worktree.remove\"\ndescription = \"remove focused worktree (force-aware) / close workspace\"\n```\n\n`create` pairs well with the built-in `new_worktree` — same \"g/i\" worktree\nfamily, but this one seeds the checkout from GitHub. `remove` is meant to\nreplace the built-in `remove_worktree` (and can subsume `close_workspace`,\nsince it falls back to closing non-worktree workspaces).\n\n## Requirements\n\n- herdr `\u003e= 0.7.0`\n- `gh` (authenticated)\n- `git`\n- `node` \u003e= 18\n- `claude` on `PATH` is optional — only used by `create` to draft names from\n  the issue body; falls back to a deterministic title slug without it.\n  PR/branch imports and `remove` don't use it at all.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdir700%2Fherdr-plugin-worktree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkdir700%2Fherdr-plugin-worktree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdir700%2Fherdr-plugin-worktree/lists"}