GitHub - steviee/git-issues: Repository based Issue Tracker (think Github Issues) for AI Agents

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

Relations

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:

Bulk Operations

Other

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:

.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