issues

Issue tracking for the agent-native development loop.

issues is a fast, self-hosted command-line issue tracker built for teams that use AI agents as real collaborators, not just autocomplete. It gives every agent a shared queue, an isolated worktree, a durable handoff trail, and a simple way to pick up exactly where the last session stopped.

Status: Beta: usable for real agent-assisted workflows, with commands and storage still subject to change before a stable release.

No SaaS account. No browser tab archaeology. No heavyweight project-management ceremony. Just a tiny Go server, a SQLite database, and a CLI that keeps issues close to the code.

Why issues?

• Built for parallel agents: claim work, create per-issue branches/worktrees, and avoid collisions across concurrent sessions.
• Designed for handoffs: capture what changed, what remains, key decisions, blockers, and uncertainty before context disappears.
• Distributed by design: coordinate many repos, machines, worktrees, and agents through one lightweight server.
• Self-hosted by default: run it on your LAN, laptop, homelab, or dev box with your data in SQLite.
• Repo-aware by default: each repository gets its own project config while sharing one server.
• Scriptable from day one: every command supports --json for coordinators, shell scripts, dashboards, and agent tooling.

What makes it click

issues is built around the moments where agent-assisted development usually gets messy:

• One command to spin up isolated work: issues start creates the branch and worktree, marks the issue in progress, and drops the agent into a clean lane.
• A queue agents can actually coordinate through: issues next, issues ready, dependencies, priorities, and owners make it obvious what should happen next.
• Handoffs that survive context resets: issues handoff turns partial progress into durable project memory instead of scattered chat history.
• Fast orientation for new sessions: issues context shows the current issue, latest handoff, recent comments, and ready queue in one shot.
• Cleanup built into the workflow: issues done --merge --rm closes the loop by merging, closing, and removing the temporary worktree.

Go client-server architecture: issues CLI talks to the issue-server daemon over HTTP/JSON, backed by SQLite. Designed for multi-repo, multi-worktree, multi-agent development on a LAN.

Install

From pre-built binary (recommended)

Cross-compile on the build machine, then copy the binary for your platform:

# On the build machine (requires Go 1.26.4+)
git clone https://github.com/scotthaleen/issues.git && cd issues
go-task release        # builds CLI + server for linux/darwin × amd64/arm64
go-task release:cli    # builds CLI only

# Binaries land in dist/release/
ls dist/release/
# issues-darwin-arm64  issues-linux-amd64  issue-server-linux-amd64  ...

Copy the right binary to the target machine and rename it:

scp dist/release/issues-darwin-arm64 mac:~/.local/bin/issues

Or use the install script from a repo checkout:

./install.sh             # installs CLI for current platform
./install.sh --server    # also installs issue-server

From source (build machine)

go-task install       # server + CLI to ~/.local/bin, restarts systemd
go-task install:cli   # CLI only to ~/.local/bin

Client-only setup

On machines that only need the CLI (no server):

# Copy or install the binary, then:
cd ~/myproject
issues init --server http://your-server:4747 --project myproject
issues list

Quick Start

# Start the server (runs on port 4747)
issue-server start

# Initialize a repo
cd ~/myproject
issues init --server http://localhost:4747 --project myproject

# Create and manage issues
issues create "Add login page" -t feature --priority 1
issues list
issues next                    # pick the top unblocked issue
issues claim 3                 # lightweight: just mark in_progress
issues start 3                 # heavyweight: create worktree + branch
issues comment 3 "WIP on auth"
issues handoff 3 --done "Built login form" --remaining "Tests and validation"
issues context                 # session orientation dump
issues done 3 --merge --rm    # merge branch, close, cleanup worktree

Architecture

issues (CLI)  ──HTTP/JSON──>  issue-server (daemon)  ──>  SQLite

• Two binaries, one module: issues CLI and issue-server daemon share internal/ packages
• Pure Go SQLite via modernc.org/sqlite (CGO_ENABLED=0, single static binary)
• Stdlib HTTP with Go 1.22+ ServeMux routing (no frameworks)
• CalVer versioning (YYYY.MM.DD) injected at build time

API Docs

The server exposes lightweight API documentation for automation clients and custom dashboards:

• GET /docs — Swagger UI
• GET /openapi.json — OpenAPI 3.1 spec

Commands

Issue Management

Command	Description
issues list	List open + in_progress issues
issues list -s closed	List closed issues
issues list -d	List soft-deleted issues
issues list -a	List across all projects
issues show <id>	Full issue detail
issues create "title"	Create issue (-t type, --priority N, -d desc)
issues update <id>	Update fields (--title, --priority, etc.)
issues close <id>	Close issue (-r "reason")
issues reopen <id>	Reopen a closed issue
issues delete <id>	Soft-delete issue(s) (bulk-capable)

Workflow

Command	Description
issues next	Show the top-priority unblocked issue
issues ready	List all unblocked issues
issues claim <id>	Set in_progress + owner (no git ops)
issues start <id>	Create git worktree + branch, set in_progress
issues current	Show issue for current worktree
issues open <id>	Print worktree path (cd $(issues open 3))
issues done <id>	Close issue (auto-detect from .issue file)
issues done <id> --merge --rm	Merge branch, close, remove worktree

Session Continuity

Command	Description
issues context	Session orientation dump (current issue, handoff, ready queue)
issues handoff <id>	Record structured handoff (--done, --remaining, --decision, --uncertain)
issues handoffs <id>	List handoff history
issues comment <id> "msg"	Add a comment
issues log <id> "msg"	Add typed log entry (--decision, --blocker)
issues comments <id>	List comments

Dependencies

Command	Description
issues dep add <from> <to>	Add dependency (blocks, related, discovered-from)
issues dep rm <from> <to>	Remove dependency
issues dep list <id>	Show dependencies

Setup

Command	Description
issues init	Interactive setup (or --server URL --project NAME for headless)
issues doctor	Check setup health (config, server, git, worktrees)
issues health	Server health check
issues version	Show version info

All commands support --json for machine-readable output. Bare numeric IDs are auto-prefixed with the project name (e.g., issues show 3 becomes issues show myproject-3).

Agent Workflow

The coordinator pattern for multi-agent development:

flowchart TD
    A[issues next] --> B[issues start ID]
    B --> C[Create branch]
    B --> D[Create git worktree]
    B --> E[Mark issue in_progress]
    D --> F[Launch coding agent in worktree]
    F --> G[Code, test, commit]
    G --> H{Finished?}
    H -- No --> I[issues handoff ID]
    I --> J[Next session runs issues context]
    J --> F
    H -- Yes --> K[issues done ID --merge --rm]
    K --> L[Merge branch]
    K --> M[Close issue]
    K --> N[Remove worktree]

Loading

# 1. Pick next task
ISSUE=$(issues next --json | jq -r .id)

# 2. Create isolated workspace
issues start $ISSUE
# -> creates worktree at ../project-$ISSUE with branch $ISSUE

# 3. Launch agent in worktree
opencode --dir ../project-$ISSUE "Work on $ISSUE"

# 4. Agent records progress
issues handoff $ISSUE \
  --done "Implemented feature X" \
  --remaining "Tests needed" \
  --decision "Used approach A over B"

# 5. Merge and cleanup
issues done $ISSUE --merge --rm
git push origin master

The issues context command orients a new agent session:

issues context
# Shows: current issue, latest handoff, recent comments, ready queue

Agent Setup

To make issues discoverable by coding agents in your own repo:

# 1. Initialize the repo
issues init --server http://localhost:4747 --project myproject

# 2. Commit the shared workflow guide
git add .issues/workflow.md

# 3. Add an issues quick reference to AGENTS.md
$EDITOR AGENTS.md

Recommended AGENTS.md snippet:

## Issue Tracking

This project uses `issues` for issue tracking.
The server runs at `http://localhost:4747`. Project: `myproject`.

Read `.issues/workflow.md` for the full workflow.

```sh
issues next                          # highest-priority ready issue
issues start <id>                    # create worktree + branch
issues context                       # current issue + latest handoff
issues handoff <id> --done "..."     # leave structured session state
issues done <id> --merge --rm        # merge, close, cleanup
```

Agents that load AGENTS.md automatically get the issue workflow at session start. The committed .issues/workflow.md gives every human and agent the same rules for worktrees, handoffs, comments, and finishing work.

Labels

Command	Description
issues label add <id> <label>	Add a label to an issue
issues label rm <id> <label>	Remove a label
issues label list <id>	List labels on an issue
issues list --label bug	Filter issues by label
issues create "title" -l bug	Add labels at creation time

Search & Analysis

Command	Description
issues search <query>	Full-text search across titles and descriptions
issues board	Kanban-style grouped view
issues stats	Project statistics (status, priority, type breakdowns)
issues critical-path	Issues sorted by transitive unblock impact
issues children <id>	List subtasks of an epic
issues tree <id>	Show parent-child hierarchy
issues worktrees	List active worktrees with linked issues
issues cleanup	Remove worktrees for closed issues

Systemd Setup

The server runs as a systemd user service for automatic startup:

# Install (self-registering — the server binary creates its own unit file)
issue-server systemd install

# Or with a custom data directory
issue-server systemd install --issues-home /path/to/data

# Management
issue-server systemd status     # show service status
issue-server systemd logs       # recent logs (journalctl)
issue-server systemd uninstall  # stop, disable, remove

The generated unit file lives at ~/.config/systemd/user/issue-server.service:

[Unit]
Description=Issue Tracker Server
After=network.target

[Service]
Type=simple
ExecStart=/home/you/.local/bin/issue-server start
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

The go-task install task handles the stop/copy/restart cycle automatically.

Configuration

Per-repo config lives in .issues/config.yaml (gitignored):

server: http://localhost:4747
project: myproject
base_branch: master

Environment variables:

• ISSUES_HOME — override server data directory (default ~/.config/issues/)
• ISSUE_SERVER — override server URL
• ISSUE_TOKEN — auth token

Development

go-task build          # build both binaries to dist/
go-task lint           # golangci-lint v2
go-task fmt            # gofumpt
go-task test           # go test -race -count=1 ./...
go-task check          # fmt + lint + test
go-task dev            # run server locally with ISSUES_HOME=./tmp

See AGENTS.md for coding conventions and project structure.

Credits

Inspired in part by marcus/td, a simple command-line todo manager.

License

MIT