bug

An alternative CLI for git-bug that simplifies working with agents on issues

add version subcommand, bump to 1.1.0
BT  ·  2026-09-13
c150b55

README.md

Bug CLI Tool

A simplified CLI interface for git-bug issue tracking. Git-bug has its own CLI, but it’s not intuitive to use. This project implements an alternative API that is suitable for a user and an agent to use git-bug to collaborate on issues, while staying fully compatible with the original git-bug.

Quick Start

Initialize git-bug in your repository:

bug init

This creates user and agent identities and configures git remotes for syncing bugs. Unlike git-bug, this sets up refspecs for remote tracking of bug references and identities. You no longer need to git push and then git-bug push. A simple git push or git fetch will also update tracked bugs.

Commands

List Issues

Display all issues in a formatted table:

bug list              # List all open issues
bug ls                # Same as above (alias)

Filtering:

bug list --filter label:bug              # Show only issues with label "bug"
bug list --filter label:bug,critical     # Show issues with both labels
bug list --filter age:<10d               # Show issues newer than 10 days
bug list --filter age:>30d               # Show issues older than 30 days

Sorting:

bug list --sort id:asc                   # Sort by ID ascending
bug list --sort id:desc                  # Sort by ID descending
bug list --sort age:asc                  # Sort by age, newest first
bug list --sort age:desc                 # Sort by age, oldest first (default)

Status:

bug list --status open                   # Show only open issues (default)
bug list --status closed                 # Show only closed issues
bug list --status all                    # Show all issues

Parent/child tree: Issues created with --parent are nested under their parent with tree markers (├─, └─). Parents sort oldest first, with each parent’s children nested below it oldest first. Passing --sort forces a flat table with that sort order instead.

Create a New Issue

Using flags:

bug new --title "Bug title" --message "Detailed description"
bug new -t "Bug title" -m "Detailed description"

Interactively (opens editor):

bug new

The editor opens with a template. The first non-empty line becomes the title, and the rest becomes the description. Lines starting with ;; are ignored.

Linking to a parent issue:

bug new --title "Subtask" --message "Details" --parent abc1234
bug new -t "Subtask" -m "Details" -p abc1234

The parent ID accepts a 7-character short ID or a full ID.

Read/Show an Issue

Display an issue with all its metadata and comments:

bug read abc1234              # Display bug with ID prefix abc1234
bug show abc1234              # Same as above (alias)
bug read --repo /path abc1234 # Display bug from specific repository

Output includes: - Title, ID (7-char prefix), Author, Creation date, Status, Labels - Parent (Parent: <7-char> - <title>, only if the issue has a parent) - Description (first comment) - All additional comments with their IDs

Add a Comment

Using flags:

bug comment abc1234 --message "This is my comment"
bug comment abc1234 -m "This is my comment"

Interactively (opens editor):

bug comment abc1234

Edit an Issue or Comment

Edit an issue:

bug edit abc1234                    # Open editor with current content
bug edit abc1234 -t "New Title"     # Update only the title
bug edit abc1234 -m "New desc"      # Update only the description
bug edit abc1234 -t "Title" -m "Desc"  # Update both
bug edit abc1234 -p def5678         # Set the parent issue (only if none set)

A parent link can only be added when the issue has none; parent links cannot be changed or removed afterwards. Links that would close a dependency cycle are rejected.

Edit a comment:

bug edit def5678                    # Open editor with current comment text
bug edit def5678 -m "New text"      # Update the comment

When using the editor: - For issues: title on first line, blank line, then description - For comments: edit the comment text directly - Lines starting with ;; are ignored (instructions)

Open/Close Issues

Open a closed issue:

bug open abc1234

Close an open issue:

bug close abc1234

Remove an Issue

WARNING: This action is permanent and cannot be undone.

bug rm abc1234                    # Remove bug with short ID
bug rm abc1234567890abcdef        # Remove bug with full ID
bug remove abc1234                # Same as above (alias)

Note: Individual comments cannot be removed. Use bug rm <bug-id> to remove the entire issue including all comments.

Check Version

Print the version of the installed bug binary:

bug version              # Prints e.g. "bug version 1.0.1"

The version is embedded at build time from the version field in flake.nix. Agents use this to determine which features are available in the installed binary.

IDs: Short vs Full

Bug IDs are 64-character hex strings, but the CLI accepts shortened prefixes:

Commands automatically resolve short IDs to full IDs. Use short IDs for convenience when interacting with bugs.

Working with a Repository in a Different Location

All commands accept a --repo flag:

bug --repo /path/to/repo list
bug --repo /path/to/repo new --title "Title" --message "Message"

By default, commands operate on the current directory (.).

Agent Collaboration

This tool supports agent collaboration. Agents use commands under bug agent which are designed for non-interactive use. See SKILL.md for agent-specific documentation. Copy the SKILL.md to ~/.agents/skills/working-with-bug. It is designed for use with superpowers skills if colocated in ~/.agents/skills/superpowers/working-with-bug.

A typical flow is to define a complicated prompt in a git-bug issue, then tell the agent to read bug [bugID] and come up with a plan. It will then use the skill in coordination with the superpowers/writing-plans and superpowers/executing-plans skills to document its plan as a comment on the bug. It will also add a summary after completion of development as a comment on the bug. I like this workflow better because it retains information about which prompts/bugs led to which plans in a way that the typical superpowers flow of a docs/plans folder full of random markdown plans does not.

Syncing Bugs

After bug init, git is configured to automatically sync bugs and identities when you push/fetch from the origin remote. Bugs are stored in git refs and will be synchronized with your team.