issueboss

IssueBoss

An AI-native issue tracker built around a structured pipeline and an MCP server, so agents can read, update, and advance issues directly without leaving their tools.

What it does

Issues move through a defined pipeline — triage, research, spec, plan, dev — with explicit gates that enforce process. Gates block transitions until required artifacts exist (e.g. a triage result before leaving triage, a spec before leaving spec review). Phases can be skipped when they aren't needed.

Artifacts attach structured documents to issues: triage results, specs, plans, research notes, handoff summaries, comments. File-backed artifacts track on-disk paths so move_artifact can keep references in sync when files move.

MCP Interface

The primary interface is an MCP server that exposes the full issue lifecycle to AI agents.

Tools

Issues

• list_issues — list issues with optional filters: status, priority, size, limit, exclude_blocked, submitted_by, assigned_to
• create_issue — create a new issue; priority defaults to Medium
• update_issue — update title, description, priority, or size
• transition_issue — advance through the pipeline with an optional reason

Artifacts

• add_artifact — attach an artifact to an issue; kinds: TriageResult, Spec, Plan, Research, ResearchTopic, Comment, Handoff
• update_artifact — update an artifact's body (StatusTransition artifacts and file path fields are immutable)
• remove_artifact — remove an artifact by slug
• list_artifacts — list artifacts, with optional kinds filter and uncovered_only flag for uncovered ResearchTopics
• move_artifact — update path references across all issues when a file moves on disk (admin only)

Relationships

• add_relationship — link two issues with DependsOn (with cycle detection) or RelatedTo (symmetric)
• remove_relationship — remove a relationship by kind
• list_relationships — list depends_on, blocks, and related_to for an issue

Resources

• issueboss://projects — list all accessible projects
• issueboss://issues/{slug} — read a single issue with its relationships (e.g. issueboss://issues/IB-5)

Pipeline

TriageNeeded → TriageInProgress → TriageReview → ResearchNeeded → ResearchInProgress → ResearchReview
                                               → SpecNeeded → SpecInProgress → SpecReview
                                               → PlanNeeded → PlanInProgress → PlanReview
                                               → DevNeeded → DevInProgress → DevReview → Done

Phases are a DAG — after any Review state you can jump directly to any later phase or Done. Backlog and Canceled are reachable from most states.

Gated transitions require artifacts to exist before they pass:

Transition	Required artifact
TriageInProgress → TriageReview	TriageResult
SpecInProgress → SpecReview	Spec
PlanInProgress → PlanReview	Plan
ResearchInProgress → ResearchReview	all ResearchTopics covered

Configuration

IssueBoss is configured via environment variables. Server variables use the ISSUEBOSS__ prefix (double underscore separator); CLI variables use a single underscore.

Server

Variable	Default	Description
ISSUEBOSS__DATABASE_URL	(required)	Database connection URL (e.g. `[REDACTED:DB Connection String]
ISSUEBOSS__HTTP_PORT	8080	HTTP/web port
ISSUEBOSS__MCP_PORT	8090	MCP server port
ISSUEBOSS__GRPC_PORT	9090	gRPC admin interface port

CLI

Variable	Default	Description
ISSUEBOSS_GRPC_HOST	http://localhost	gRPC server host (include scheme)
ISSUEBOSS_GRPC_PORT	9090	gRPC server port
ISSUEBOSS_API_KEY	(none)	API key sent as x-api-key on all admin gRPC requests

Bootstrap

After starting the server, create the initial super-admin account via the gRPC admin interface:

issueboss super-admin \
  --username admin \
  --full-name "Your Name" \
  --email admin@example.com \
  --password changeme