git-issues

README

git-issues

A git-native issue tracker. Issues are stored as Markdown files with YAML frontmatter inside your repository under .issues/, version-controlled alongside your code.

No database. No server. No accounts. Just files and git.

Install

# With Go (recommended)
go install github.com/steviee/git-issues@latest

# From source
git clone git@github.com:steviee/git-issues.git
cd git-issues
make install   # builds and copies to /usr/local/bin/issues

Requires Go 1.22+. The go install command places the binary in $GOPATH/bin (or $HOME/go/bin). Make sure this directory is in your $PATH.

Setup (for AI agents)

# 1. Install
go install github.com/steviee/git-issues@latest

# 2. Initialize in your project
cd /path/to/your/project
issues init

# 3. Read the agent context
cat .issues/.agent.md

# 4. Start working
issues next              # find next actionable issue
issues claim <id>        # mark as in-progress
# ... do the work ...
issues done <id>         # close when finished

The .issues/.agent.md file contains the full schema, all commands, and the recommended workflow.

Quick Start

# Initialize in any git repo
issues init

# Create issues
issues new --title "Fix login bug" --priority high --label bug
issues new --title "Add dark mode" --label feature

# List open issues
issues list

# Work on the next actionable issue
issues next
issues claim 1
# ... do the work ...
issues done 1

All changes are auto-staged for your next git commit.

How It Works

Each issue is a Markdown file in .issues/:

---
id: 1
title: "Fix login bug"
status: open
priority: high
labels: [bug, auth]
relations:
  blocks: [3]
created: 2026-03-04
updated: 2026-03-04
---

Description and notes go here as free-form Markdown.

Filename format: 0001-fix-login-bug.md (zero-padded ID + slug, never changes).

Command Reference

Core Commands

Command	Description
issues init	Initialize .issues/ in current directory
issues new --title "..." [--priority P] [--label L] [--body "..."]	Create a new issue
issues list [--status S] [--priority P] [--label L] [--format F]	List issues (formats: table, json, ids)
issues show <id> [--format F]	Show issue details (formats: text, json)
issues edit <id>	Edit issue in $EDITOR
issues close <id> [--wontfix] [--reason "..."]	Close an issue
issues reopen <id>	Reopen a closed issue
issues set <id> <field> <value>	Set priority, status, title, or label

Relations

Command	Description
issues relate <id> <relation> <target-id>	Add relation (blocks, depends-on, related-to, duplicates)
issues unrelate <id> <relation> <target-id>	Remove relation
issues graph [--open-only] [--root <id>]	Show dependency graph

Relations are always bidirectional: issues relate 1 blocks 2 also writes depends-on: [1] to issue #2.

Agent-Optimized Commands

Designed for AI agent workflows with machine-readable output:

Command	Description
issues next [--format json]	Next unblocked, highest-priority issue
issues claim <id>	Set status to in-progress
issues done <id>	Close the issue
issues blocked [id]	List blocked issues or show blockers for one issue
issues check [--fix]	Verify database consistency, optionally auto-fix

Bulk Operations

Command	Description
issues batch close [--label L] [--status S]	Close all matching issues
issues batch set <field> <value> [--label L] [--status S]	Set field on all matching issues

Other

Command	Description
issues labels [--sort count|alpha]	List all labels with frequency

Filtering & Sorting

# Filter by status (default: open)
issues list --status all
issues list --status closed

# Filter by priority
issues list --priority critical

# Filter by label (OR logic)
issues list --label bug --label auth

# Sort (default: priority desc, then ID asc)
issues list --sort updated
issues list --sort created

# Output formats
issues list --format table   # human-readable (default)
issues list --format json    # machine-readable
issues list --format ids     # space-separated IDs for scripting

Relations & Dependencies

# Issue 1 blocks issue 2
issues relate 1 blocks 2

# Show dependency graph
issues graph --open-only

# Output:
# #1  Fix auth [open, critical]
# └── blocks:
#     #2  Login bug [open, high]

Relation types: blocks, depends-on, related-to, duplicates.

issues close warns if an issue has open blockers.

AI Agent Integration

git-issues is designed to work as the task management layer for AI coding agents. The .issues/.agent.md file (generated by issues init) provides agents with the schema and recommended workflow.

Recommended agent workflow:

issues next                    # find next actionable issue
issues claim <id>              # mark as in-progress
# ... agent does the work ...
issues done <id>               # close when finished

All commands support --format json for machine-readable output.

Import from GitHub

Migrate existing GitHub issues using the gh CLI:

issues init

gh issue list --state open --json number,title,body,labels --limit 500 | \
  jq -c '.[]' | while read -r issue; do
    title=$(echo "$issue" | jq -r '.title')
    body=$(echo "$issue" | jq -r '.body // ""')
    labels=$(echo "$issue" | jq -r '[.labels[].name] | join(",")')
    if [ -n "$labels" ]; then
      issues new --title "$title" --body "$body" --label "$labels"
    else
      issues new --title "$title" --body "$body"
    fi
  done

Working with Git Worktrees

git-issues works in multi-worktree setups. One rule to remember:

New issues: only on main. Updating existing issues (claim, done, set): any branch.

This prevents ID collisions from parallel issues new. Additional tips:

• Claim before working — issues claim <id> prevents two worktrees from modifying the same issue
• Only modify your claimed issue from a feature branch
• Run issues check --fix after merging — repairs any broken relations

Configuration

.issues/.config.yml:

default_priority: medium
auto_stage: true
labels:
  - bug
  - feature
  - auth
  - security
  - docs

• default_priority: Used when creating issues without --priority
• auto_stage: Automatically git add issue files on every change
• labels: Predefined label list (informational, not enforced)

Claude Code Integration

git-issues ships with a Claude Code skill that teaches the agent to use git-issues as its sole task management system — replacing Claude's built-in TaskCreate/TaskUpdate tools entirely.

What the skill does

• Makes /git-issues available as a slash command in Claude Code
• Auto-activates when Claude detects task-management context (planning, creating tasks, tracking progress)
• Enforces the Iron Workflow: pick → claim → branch → implement → done → merge
• Requires comprehensive issue bodies with context, success criteria, and implementation details
• Maps every TaskCreate/TaskUpdate instinct to the equivalent git-issues command

Install the skill

# Option 1: Plugin (recommended — auto-updates)
/plugin marketplace add steviee/git-issues
/plugin install git-issues

# Option 2: Install script (manual)
./claude-skill/install.sh

# Option 3: Manual copy
mkdir -p ~/.claude/skills/git-issues
cp skills/git-issues/SKILL.md ~/.claude/skills/git-issues/SKILL.md

The plugin method is recommended because it pulls updates automatically when the skill is improved.

How it works with .agent.md

The skill is complementary to the .agent.md file generated by git-issues init:

File	Purpose
.issues/.agent.md	Command reference — schema, commands, basic workflow (auto-generated, project-local)
Skill (/git-issues)	Behavioral rules — quality standards, creation protocol, recovery patterns (installed via plugin or ~/.claude/skills/)

.agent.md tells the agent what commands exist. The skill tells the agent how to use them well.

---

Development

make build    # build binary
make test     # run tests
make lint     # run go vet
make install  # install to /usr/local/bin

License

MIT