A TypeScript extension that opens an interactive zot panel, lets you select a BugHerd project and one unfinished bug or all unfinished bugs, fixes the selection in the current codebase, posts completion comments, and moves fixed bugs to a configured status.

It runs through npx and does not require a local node_modules directory.

• zot with extension support
• Node.js 18 or newer
• npx
• A BugHerd API v2 key from Settings > General

The extension sends the key only to https://www.bugherd.com using BugHerd's required HTTP Basic authentication. Do not commit the key.

Install the extension directly from GitHub:

zot ext install https://github.com/inoovum/zot-bugherd

Restart zot after installation, then configure the BugHerd API key before running /bugherd.

Start zot and run:

/bugherd setup

The setup panel edits the extension's bugherd.config.json. Configure the API key, optional default project ID or exact name, completion status, and optional commenter email. The API key is masked in the panel. Select Save configuration to write the file with user-only permissions where supported.

Use up and down to select a field, enter to edit it, delete to clear it, and esc to cancel editing or close the panel. Your terminal's paste shortcut inserts clipboard text while editing.

Clipboard paste uses pbpaste on macOS, PowerShell on Windows, and wl-paste, xclip, or xsel on Linux. Current zot releases report panel paste gestures as an unknown key without including the pasted text, so the extension reads the system clipboard when it receives that key during setup editing.

Environment variables take precedence over .env, which takes precedence over JSON config.

Copy .env.example to .env in this extension directory or add these values to the code project's .env:

BUGHERD_APIKEY=your-api-key
BUGHERD_PROJECT=12345
BUGHERD_DONE_STATUS=done
# Optional, attributes comments to this BugHerd user
BUGHERD_COMMENTER_EMAIL=developer@example.com

BUGHERD_PROJECT can be a numeric project ID or an exact active project name. It is used by the model-facing bugherd_next_task tool. The interactive /bugherd panel lists all active projects instead.

Alternatively, copy bugherd.config.example.json to bugherd.config.json and edit it:

{
  "apiKey": "your-api-key",
  "project": 12345,
  "doneStatus": "done",
  "commenterEmail": "developer@example.com"
}

Both .env and bugherd.config.json are ignored by Git. A project can override extension configuration with .zot/bugherd.json, using the same JSON fields.

doneStatus may be a built-in status such as done or the name of a custom BugHerd column.

After installation and configuration, start zot in the code project you want to fix and run:

/bugherd

The command opens a project picker. Use up and down to select an active BugHerd project, then press enter to open its unfinished bugs. The first bug-list row selects all unfinished bugs; every other row selects one bug. Press enter to submit the selection to the agent. Press left to return to projects or esc to close the panel.

You can still open one project's bug list directly with /bugherd 12345 or /bugherd Exact Project Name.

For every selected bug, the agent is instructed to:

1. Call bugherd_get_task and retrieve the selected task and its comments.
2. Inspect and fix the issue in zot's current project directory.
3. Run relevant validation.
4. Only after successful validation, call bugherd_finish_task to add a fix summary and move the task to the requested or configured status.

When all bugs are selected, they are processed one at a time. If implementation or validation fails for a bug, the prompt tells the agent not to modify that BugHerd task.

Run the extension directly from a checkout without installing it:

zot --ext .

• bugherd_next_task: accepts an optional project ID or exact name and returns the next unfinished task plus comments. This remains available for non-panel model workflows.
• bugherd_get_task: returns one panel-selected task and its comments by project ID and global task ID.
• bugherd_finish_task: accepts the returned project ID and global task ID, a comment, and an optional status. It posts the comment first, then updates the status. If only the status update fails, the result explicitly reports that the comment was already posted.

Run the tests without installing dependencies locally:

npx --yes tsx --test test/*.test.ts

The implementation uses only Node.js built-ins and the native fetch API. tsx is downloaded into the npx cache when needed, not into this project.

MIT