npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

drovr

v1.0.0

Published

CLI that picks up Linear tickets or GitHub issues and puts your Herdr agents to work.

Readme

drovr

drovr is a CLI that picks up Linear tickets or GitHub issues and puts your Herdr agents to work.

drovr polls Linear or GitHub Issues for tickets that match your criteria (by default: label agent-ready, state Todo). For each newly eligible ticket it creates a git worktree, runs the repository's setup, opens a workspace in your running Herdr session, starts an interactive Codex or Claude Code agent there, and hands it the ticket. Each ticket gets its own worktree and workspace, and at most maxConcurrent (default 1) run at once. You watch, answer questions, approve actions, and give follow-ups in Herdr as usual. drovr only automates the pickup: it never merges, and never deletes worktrees, branches, or workspaces.

Linear / GitHub ──poll──▶ eligible? ──▶ already dispatched? ──▶ slot free? ──▶ worktree ─▶ setup ─▶ Herdr workspace ─▶ agent ─▶ prompt
                             │                  │                    │
                           skip (why)         skip (state)         queue

drovr run --dry-run --once checks every provider and shows what would launch, without launching or recording anything:

$ drovr run --dry-run --once --label bug
16:41:38 drovr   DRY RUN — nothing will be launched or recorded
16:41:38 config  using ./drovr.config.json
                 repository ~/code/drovr (the current git repository)
                 workflow "yss14-drovr" (from the repository), poll every 60s, max 1 active, first run: dispatch
                 tickets: github repo (current), labels [bug], states [open], assignee any
                 launch: claude in herdr session main, 1 repo(s)
                 state: ~/.local/state/drovr/drovr.db
16:41:39 check   ✓ tickets: github — gh version 2.97.0 (2026-07-31), issues of yss14/drovr; labels bug exist
16:41:39 check   ✓ terminal: herdr — herdr 0.9.5, session "main" running
                 warning: herdr 0.9.5 differs from the tested 0.7.5; response shapes may differ
16:41:39 check   ✓ agent: claude — 2.1.316 (Claude Code) (~/.local/bin/claude)
16:41:39 check   ✓ prompt — built-in template, file delivery to .drovr/{identifier}.md
16:41:39 check   ✓ repo: ~/code/drovr — base main (remote HEAD), worktrees via git (auto) — ~/code/drovr
16:41:39 check   ✓ vcs: git — git version 2.55.0
16:41:39 dry-run 0 ticket(s) fetched (issues of the current repository, labels [bug], states [open], any assignee)
16:41:39 dry-run nothing new would launch

Contents

Why drovr

Hosted coding agents (Codex cloud, the Copilot coding agent, the Claude Code GitHub Action) run headless on someone else's machine and hand back a pull request. drovr runs the agent on your machine instead:

  • Your real dev environment. The agent works in a git worktree of your checkout, after your worktrunk pre-start hooks or setup commands have run, with your local tools, credentials, and agent config (agent.env).
  • Interactive, not headless. Each agent is a normal Codex or Claude Code session in its own Herdr workspace. You see it work, answer its questions, approve its actions, and keep giving it instructions after its first run.
  • Picks up work as it appears. Label a ticket agent-ready and it launches on the next poll, in priority order, up to your concurrency limit. A ticket is never dispatched twice, even across restarts and interrupted launches.

When not to use it

  • You want unattended runs in CI or the cloud. drovr needs a running Herdr session on your machine. Use a hosted agent or a CI action instead.
  • You don't use Herdr. Herdr is the only built-in terminal provider. Others need a plugin.
  • Your tracker isn't Linear or GitHub Issues. Other trackers (Jira, for example) need a ticket-source plugin.
  • You want the loop closed for you. drovr doesn't review, merge, or clean up. It starts the work and tracks it until the ticket completes or you close the workspace.

Install

npm install --global drovr     # or: pnpm add --global drovr

From source:

git clone https://github.com/yss14/drovr.git && cd drovr
pnpm install && pnpm build && pnpm link --global

Requirements, all checked by drovr check:

  • Node.js ≥ 22. drovr uses better-sqlite3, a native module. npm downloads a prebuilt binary for common platforms and otherwise compiles it, which needs a C++ toolchain such as Xcode Command Line Tools or build-essential.
  • For Linear: linear (Linear CLI), authenticated with linear auth login. For GitHub Issues: gh (GitHub CLI), authenticated with gh auth login.
  • herdr (Herdr, herdr.dev) with a running named session.
  • codex and/or claude.
  • git.
  • wt (worktrunk), for repositories that use worktrunk hooks.

Quick start

cd ~/code/my-repo
drovr init                     # asks a few questions, writes the config
drovr check                    # providers, auth, Herdr session, repo, team, labels
drovr run --dry-run --once     # what would launch, without doing anything
drovr run                      # watch

drovr init looks at the repository you run it in and at your Linear teams, the repository's GitHub issues, Herdr sessions, and installed agents, then asks for the rest with those as choices. When gh can read the repository, it asks whether tickets come from Linear or GitHub. It finds the team's (or repository's) labels and workflow states, the running Herdr session, and a setup command from the repository's lockfile. It writes either drovr.config.json at the repository root, added to .git/info/exclude so it is never committed, or the per-user ~/.config/drovr/config.json (--global). --yes takes every suggested answer without asking, and so does running without a terminal.

While drovr run is running in a terminal: space pause/resume · p poll now · r reload config · s status · q / Ctrl-C quit. Pausing stops polling and launching. A launch already in progress finishes first.

r re-reads the config file and prompt template (command-line flags still win), runs the checks again, and swaps in the new config, then polls right away. A launch already in progress finishes with the old config first. If the file is invalid or a check fails, drovr keeps the current config and logs why. workflow, database, and dryRun cannot change while running, and plugin modules are not re-imported, so changes to those need a restart.

Several repositories

drovr works on the git repository you run it in. Unless the config lists repositories, the current repository is used, found from any subdirectory or worktree, and the workflow is named after its remote ([email protected]:acme/web.git → acme-web). Each repository therefore keeps its own dispatch records and watcher, all in the one database.

  • Shared settings: run drovr init --global once, then drovr run in each repository. Leave workflow and repositories out of the global file, or every repository shares them.
  • Per-repository settings: run drovr init in each repository. Its drovr.config.json is used instead of the global one.

Commands

| Command | | | --- | --- | | drovr run [--dry-run] [--once] [-v] [flags] | Watch (default command). -v also logs skipped tickets and why. | | drovr check [flags] | Check providers: binaries, Linear or GitHub auth, team and labels exist, Herdr session running, agent supported, repos valid. | | drovr config [flags] | Print the resolved config. | | drovr init [--global] [--yes] [--force] | Set up a config interactively. See Quick start. | | drovr history [ticket] [-a] [--json] | Open dispatches (-a: all), or one ticket's record and event log. | | drovr retry <ticket> [--resend-prompt] | Resume a failed, needs-attention, baseline, or completed ticket on the next poll. | | drovr done <ticket> | Mark completed and free the slot. The worktree and workspace are left alone. | | drovr forget <ticket> | Delete the record so the ticket launches the next time it matches. | | drovr prompt <ticket> \| --default \| --variables | Preview the prompt for a ticket, print the built-in brief, or list template variables. | | drovr plugins | List providers. |

drovr <command> --help lists every flag. drovr never deletes worktrees, branches, or workspaces. Its only write to the tracker is moving a launched ticket to tickets.startedState (adding that label, for GitHub).

Configuration

drovr resolves its configuration in three layers. Later layers win:

  1. built-in defaults (below)
  2. the config file: --config <path>, else $DROVR_CONFIG, else ./drovr.config.json, else drovr.config.json at the root of the current git repository, else ~/.config/drovr/config.json
  3. command-line flags

Objects merge key by key. Arrays (labels, states, repositories, agent args) are replaced, not appended. Relative paths in the file resolve against the file's directory, and ~ expands everywhere. drovr config prints the resolved result. See drovr.config.example.json.

Reference

| Key | Default | Flag | Description | | --- | --- | --- | --- | | workflow | repository name | --workflow | Names the dispatch scope. Records, the first-run baseline, and the watcher lease are kept per workflow, so different repositories and criteria run as separate workflows. Defaults to owner-name from the first repository's remote (else its directory name), or "default" without a repository. | | pollIntervalSeconds | 60 | --interval | Ticket poll interval (min 10). | | monitorIntervalSeconds | 10 | | How often agent and workspace state is checked between polls. | | maxConcurrent | 1 | --max-concurrent | Maximum active dispatches (launching, running, or needs-attention) started by drovr. | | firstRun | "dispatch" | --first-run | What the first poll of a workflow does with tickets that already match. See First run. | | dryRun | false | --dry-run | Show what would happen; launch and record nothing. | | database | ~/.local/state/drovr/drovr.db | --db | SQLite state. | | plugins | [] | | Extra plugin modules. See Plugins. | | tickets.provider | "linear" | | Ticket source plugin: linear, github, or a plugin. See GitHub Issues. | | tickets.team | CLI default team | --team | Linear team key, name, or ID. Not used by github. | | tickets.labels | ["agent-ready"] | --label (repeatable) | The ticket must have all of these. | | tickets.excludeLabels | [] | --exclude-label (repeatable) | The ticket must have none of these. | | tickets.states | ["Todo"] | --state (repeatable) | State names or types (triage, backlog, unstarted, started, …). Matches any of them. Empty means any state. | | tickets.assignee | "any" | --assignee | any, none (unassigned), @me, or a user. | | tickets.project | | --project | Linear project ID, slug, or name; for github, a milestone number or title. | | tickets.startedState | "In Progress" | --started-state (none disables) | State (name or type) a ticket is moved to once its agent has acknowledged the ticket. See Moving the ticket. null disables it. | | tickets.options.workspace | | | Linear workspace slug (for multiple Linear logins). | | tickets.options.repo | the repository's GitHub remote | | github only: [HOST/]OWNER/REPO whose issues are watched. Without it, gh uses the first repository's remote. | | completion.stateTypes | ["completed", "canceled"] | | A dispatch completes when its ticket reaches one of these state types… | | completion.states | [] | | …or one of these state names (e.g. "Review"). | | completion.whenWorkspaceClosed | true | | …or when you close its Herdr workspace. | | completion.whenAgentFinished | true | | Free the slot once the agent finishes its first run on the ticket. See Slots. | | repositories[].path | current repository | --repo | Main checkout. Without repositories, the git repository containing the current directory is used. --repo replaces the list with a single repository. | | repositories[].vcs | "auto" | | How worktrees are created: worktrunk, git, or auto, which picks worktrunk when the repo has .config/wt.toml. See Worktree setup. | | repositories[].baseBranch | remote default branch | --base-branch | Branch new worktrees start from. Without it, drovr uses origin/HEAD. | | repositories[].remote | "origin" | | | | repositories[].fetch | true | | Fetch the base branch first, then branch from <remote>/<base>. | | repositories[].branch | "{ticketBranch}" | | Branch name template. {ticketBranch} is Linear's suggested branch name. | | repositories[].fallbackBranch | "drovr/{identifierLower}-{titleSlug}" | | Used when the ticket has no suggested branch name (always, for GitHub issues). | | repositories[].worktreePath | "{repo}/.worktrees/{branchSlug}" | | Worktree location template. | | repositories[].setup | [] | | Extra shell commands run in a new worktree before the agent starts, after any worktrunk hooks. They should be safe to re-run. | | repositories[].routeLabels | [] | | With several repositories, the first one whose route labels intersect the ticket's labels is used. Otherwise the single repository without route labels is used. | | terminal.provider | "herdr" | | Terminal plugin. | | terminal.session | — (required) | --session | Named Herdr session that receives the workspaces. | | terminal.focus | false | --focus / --no-focus | Focus new workspaces. | | terminal.workspaceLabel | "{identifier} {titleShort}" | | Workspace label template, e.g. "PQ-7859 Show price and CTA in the standalone mobile…". | | agent.provider | "codex" | --agent | codex, claude, or a plugin. | | agent.args | [] | --agent-arg (repeatable) | Extra arguments for the agent executable. | | agent.env | {} | | Environment variables set in the agent's Herdr workspace, e.g. { "CLAUDE_CONFIG_DIR": "~/.claude-team" } to run Claude Code against another account's config. A leading ~ expands. DROVR_TICKET and DROVR_WORKFLOW always win. | | agent.name | "{identifierLower}-{titleSlugShort}" | | Herdr agent name template, e.g. pq-7859-show-price-and-cta-in. Must be unique in the session. | | agent.startTimeoutSeconds | 90 | | How long to wait for the agent to become interactive. | | prompt.delivery | "file" | --prompt-delivery | file or inline. See Prompt delivery. | | prompt.templateFile | | --prompt-file | Ticket brief template file. Takes precedence over prompt.template. See Customising the prompt. | | prompt.template | built-in | | Ticket brief template, inline. | | prompt.briefPath | ".drovr/{identifier}.md" | | Brief location inside the worktree (file delivery). | | prompt.message | "{marker} You are assigned ticket {identifier}: {title}. Read the brief in {briefPath} …" | --prompt-message | The one-line text typed to the agent with file delivery. It must contain {briefPath}; it is not a file path (use prompt.templateFile for that). Newlines are collapsed to spaces. |

Name and path templates use {identifier}, {identifierLower}, {title}, {titleShort}, {titleSlug}, {titleSlugShort}, {url}, {ticketBranch}, {state}, and {team}. Paths can also use {repo} and {branchSlug}. Prompt variables are listed under Customising the prompt.

How it behaves

Eligibility

On every poll, drovr asks the ticket source for candidates with the team, state, label, assignee, and project filters. For Linear that is linear issue list --json --limit all, which follows pagination. For GitHub it is the issues API through gh api. drovr then re-checks each ticket locally (labels, excluded labels, state name or type, assignee). That local check is authoritative and produces the reasons drovr logs. Run with -v to also see skipped tickets and why they were skipped.

A ticket is newly eligible if it matches and has no dispatch record in the workflow. An old ticket that gets the label or state later becomes eligible on the next poll. Eligible tickets launch in priority order (urgent first), then oldest first.

First run

The first poll of a workflow decides what happens to tickets that already match:

  • dispatch (default): they launch like any newly eligible ticket, highest priority first and one slot at a time under maxConcurrent.
  • baseline: they are recorded as seen and not launched. Only tickets that start matching afterwards launch. If a baselined ticket stops matching and matches again later, it launches then. drovr retry <ticket> launches one on the next poll.

drovr run --dry-run shows which of the two would happen.

Dispatch states

| State | Meaning | Uses a slot | | --- | --- | --- | | baseline | Matched on the first poll; never launched. | no | | launching | The launch pipeline is running (step: worktree → setup → workspace → agent → prompt). | yes | | running | The agent acknowledged the prompt. | yes | | needs_attention | Waiting on you: a startup dialog, a name or branch conflict, or a prompt that could not be confirmed. The reason is logged and shown in drovr history. | yes | | failed | A step failed. Nothing retries it until drovr retry. | no | | retry | You asked to resume it. It is picked up before new tickets once a slot is free. | no | | finished | The agent finished its first run. The workspace stays open for review and follow-ups. | no | | completed | The ticket reached a completion state, its workspace was closed, or you ran drovr done. | no |

Records are keyed by the ticket's stable ID within the workflow, so a ticket is never dispatched twice. Each record stores the identifier, repo, branch, worktree path, Herdr workspace and pane, agent name and kind, last agent status, timestamps, attempts, and an event log.

Slots: finished vs. completed

Herdr reports agent activity: working, blocked, idle, done, unknown. drovr logs each change. For example, blocked is logged as "waiting for you — approval or question in workspace …".

With completion.whenAgentFinished (the default), the slot is released when the agent finishes its first run. That means the prompt was acknowledged, and Herdr then reports the agent as idle or done on two consecutive monitor checks, monitorIntervalSeconds apart. Requiring two checks means a brief pause doesn't free the slot. blocked keeps the slot, because the agent is waiting on you. The dispatch moves to finished, the next queued ticket starts right away, and the workspace stays open for your review and follow-up instructions. An agent that stops to ask a clarifying question has also finished its run.

A finished agent run does not mean the ticket is implemented. With whenAgentFinished: false, a dispatch keeps its slot until the ticket reaches a completion state, its workspace is closed, or you run drovr done <ticket>. Those conditions also free the slot of a running dispatch in the default mode.

Worktree setup

The agent starts only after the worktree is fully set up. For repositories using worktrunk (vcs: "worktrunk", or auto with a .config/wt.toml), drovr creates the worktree with wt switch --create <branch> --base <remote>/<base> --no-cd. worktrunk runs the repository's pre-start hooks and blocks until they finish (for example mise run setup, then pnpm build). drovr waits for that before it opens the Herdr workspace. drovr pins the path to repositories[].worktreePath, so keep that consistent with your worktrunk worktree-path. The default {repo}/.worktrees/{branchSlug} matches {{ repo_path }}/.worktrees/{{ branch | sanitize }}. post-start hooks run in the background as worktrunk normally runs them, and drovr does not wait for them.

If a hook fails or a launch is interrupted, drovr retry reuses the worktree and runs wt hook pre-start --foreground again before starting the agent, so hooks should be safe to re-run.

Hook approvals. worktrunk asks you to approve project hooks, and it cannot ask without a terminal. drovr never passes --yes. drovr check lists unapproved hooks, and a launch that hits one goes to needs_attention. Approve them once with wt config approvals add in the repository, then run drovr retry <ticket>.

For plain git repositories, worktrees are created with git worktree add and only repositories[].setup runs.

Startup dialogs (trust, login)

On a folder it hasn't seen before, Codex shows "Trust this folder?" and Claude Code shows "Quick safety check… Yes, I trust this folder". Herdr 0.7.5 reports both agents as idle and interactive while these dialogs are open. A prompt submitted at that point answers the dialog. For Codex that means trusting the folder. For Claude Code, where the default option is "No, exit", the agent quits.

After the agent starts, drovr waits briefly and reads the visible screen. If it recognises one of these dialogs (patterns per agent plugin, in src/plugins/builtin/agents.ts), it does not answer it. The dispatch goes to needs_attention, you answer the dialog in the Herdr workspace, and drovr notices within monitorIntervalSeconds and submits the ticket. The same applies when an agent does not report readiness within agent.startTimeoutSeconds.

Prompt delivery

Herdr delivers multi-line text as a paste, and Claude Code may decline to act on instructions that arrive only as pasted content. So by default (delivery: "file") drovr writes the ticket brief to .drovr/<ID>.md in the worktree and sends a single-line message telling the agent to read it. drovr adds /.drovr to the repository's .git/info/exclude, which is local and never committed. delivery: "inline" sends the brief directly, which works with Codex.

drovr submits with herdr agent prompt --wait and treats the prompt as delivered only when the agent reacts. A prompt that is swallowed leaves the dispatch in needs_attention instead of falsely running.

Moving the ticket

Once the agent has acknowledged the ticket prompt, drovr moves the ticket to tickets.startedState (default "In Progress") with linear issue update --state. drovr only moves tickets that have not started yet (triage, backlog, or unstarted state types). A retried or adopted ticket that is already in "Review" or "Done" stays where it is. If Linear can't be reached, the launch still counts as running, and the move is retried on the next polls. drovr check verifies that the state exists for the team. GitHub issues get a label instead; see GitHub Issues.

Moving a ticket out of tickets.states (e.g. out of "Todo") does not affect its dispatch. drovr tracks dispatched tickets by ID and never launches them twice.

Interrupted launches and overlapping watchers

  • One watcher per workflow. drovr run takes a lease in SQLite and keeps it alive with a heartbeat. A second watcher for the same workflow refuses to start. A lease whose process is gone, or whose heartbeat is stale, is taken over. A watcher that loses its lease stops.
  • Atomic claims. A ticket is claimed with an insert-if-absent before anything is created.
  • Reconciliation. Each step records its intent before acting, and on re-run first checks whether its effect already exists. An existing worktree is reused. A workspace whose create response was lost is found by label and cwd and adopted. An agent already in the pane is adopted and renamed. A prompt whose outcome is unknown is looked up in the agent's terminal output by its [drovr:<ID>] marker. If the prompt can't be confirmed, drovr asks you rather than risk sending it twice (drovr retry <ID> --resend-prompt). On startup the watcher resumes dispatches left in launching before polling.

GitHub Issues

With "tickets": { "provider": "github" }, drovr watches the issues of a GitHub repository through gh. Without tickets.options.repo, that is the repository gh finds from the first repository's remote, so a global config works across repositories.

{
  "tickets": { "provider": "github", "labels": ["agent-ready"], "states": ["open"], "startedState": "in-progress" },
  "completion": { "states": [] }
}

GitHub issues differ from Linear tickets in a few ways:

  • States. An issue is only open or closed. Use "states": ["open"]. Only open, closed, and the types below can match; drovr check rejects anything else, such as the Linear default ["Todo"] or started. Open issues have the state type unstarted. Closed issues are completed, or canceled when closed as not planned or duplicate, so the default completion.stateTypes frees the slot when an issue is closed.
  • Started state. There is no "In Progress" to move to, so tickets.startedState is a label that drovr adds to the issue once its agent has it, e.g. "in-progress". The label must exist (gh label create in-progress); drovr check verifies it. Set it to null to leave issues alone.
  • Identifiers. Issue #12 is GH-12 in logs, branch names, and workspace labels. drovr retry, done, forget, history, and prompt also take 12 and #12.
  • Branches. Issues suggest no branch name, so repositories[].fallbackBranch is used, e.g. drovr/gh-12-support-dark-mode.
  • Filters. Labels, assignee (any, none, @me, or a login), and project (a milestone number or title) are passed to the issues API through gh api, which follows every page, so no matching issue is cut off. Issues have no priority, so eligible issues launch oldest first.

Customising the prompt

What the agent receives is built from two templates:

  • The brief (prompt.templateFile or prompt.template) holds the ticket context and your instructions. With file delivery, it is written to prompt.briefPath in the worktree. With inline delivery, it is what gets sent.
  • The message (prompt.message) is the single line sent with file delivery, pointing the agent at the brief.

Start from the built-in brief, edit it, and point drovr at it:

drovr prompt --default > ~/.config/drovr/brief.md   # the built-in brief, as a starting point
drovr prompt --variables                           # every variable and what it contains
drovr prompt <ticket>                              # preview exactly what a launch would send
{ "prompt": { "templateFile": "~/.config/drovr/brief.md", "message": "{marker} Pick up {identifier} ({title}) — your brief is in {briefPath}." } }

The same works per run with --prompt-file, --prompt-message, and --prompt-delivery. Variables include the ticket's {identifier}, {title}, {url}, {description}, {labels}, {state}, {priority}, {project}, and {assignee}. The launch context adds {worktreePath}, {branch}, {baseBranch}, {repo}, {agent}, and {briefPath}. drovr check fails on an unknown placeholder (e.g. a typo like {descripton}) rather than sending it verbatim. If the sent text lacks {marker}, drovr puts [drovr:<ID>] in front, because it uses the marker to recognise a delivered prompt after an interruption.

Plugins

Every external system sits behind a provider interface in src/plugins/types.ts:

  • TicketSource: list candidates, fetch details, optionally validate criteria (built in: linear, github)
  • TerminalProvider: workspaces, panes, agent start, prompt, read (built in: herdr)
  • AgentProvider: availability, launch spec per terminal, startup-dialog detection (built in: codex, claude)
  • VcsProvider: worktrees and their blocking setup hooks (built in: git, worktrunk)
$ drovr plugins
tickets   linear     Linear via the linear CLI
tickets   github     GitHub issues via the gh CLI
terminal  herdr      Herdr terminal workspaces
agent     codex      OpenAI Codex CLI
agent     claude     Claude Code
vcs       git        git worktrees
vcs       worktrunk  worktrees via worktrunk (wt), waiting for its pre-start hooks

To add one, write an ES module whose default export registers definitions, list it in plugins, and select it by ID:

// my-tracker.mjs
export default (registry) =>
  registry.register({
    kind: "tickets",
    id: "jira",
    description: "Jira issues via jira-cli",
    create: (ctx, options) => ({
      kind: "tickets",
      id: "jira",
      checkAvailability: async () => ({ ok: true, detail: "jira ok" }),
      describeQuery: (criteria) => `labels ${criteria.labels.join(", ")}`,
      listCandidates: async (criteria) => [/* Ticket[] */],
      getTicket: async (ref) => ({ /* Ticket */ }),
    }),
  });
{ "plugins": ["./my-tracker.mjs"], "tickets": { "provider": "jira", "options": {} } }

ctx.exec runs commands and ctx.log writes to drovr's output. tickets.options (with cwd, the first repository's path, unless set) and terminal.options are passed to create.

Development

pnpm install
pnpm dev -- run --dry-run --once   # run from source
pnpm test                          # vitest, with in-memory fake providers
pnpm typecheck
pnpm build
pnpm link --global                 # put this checkout's build on your PATH as `drovr`

Report bugs and request features in GitHub issues. Changes are listed in CHANGELOG.md.

Releasing

  1. Move the Unreleased entries in CHANGELOG.md under a new version heading.
  2. npm version <patch|minor|major> bumps package.json, commits, and tags vX.Y.Z.
  3. npm publish. prepublishOnly runs the typecheck, tests, and a clean build first.
  4. git push --follow-tags, then create the GitHub release from the tag (gh release create vX.Y.Z --notes-from-tag or with the changelog section).

Verified against

herdr 0.7.5, linear CLI 3.0.0, gh 2.97.0, worktrunk 0.70.0, codex-cli 0.162.1, Claude Code 2.1.296. drovr check warns when the Herdr version differs. Startup-dialog patterns depend on agent wording and may need updating when agents change.

License

MIT