GitHub - SentioLabs/arc: Arc AI Tickets

Arc AI Issue Tracker

Acentral issue tracking server for AI-assisted coding workflows This is heavily inspired by the amazing work over at beads

Key Differences:

no per-repo daemons
no git sync or integration
uses a REST API + CLI.
embeded svelte web ui

Features

Central Server: Single server managing multiple projects
Web UI: Svelte client app embedded in Go server
REST API: Clean JSON API for all operations
Projects: First-class project management (replaces per-repo concept)
Full Issue Tracking: Create, update, close, dependencies, labels, comments
Plans: Inline plans on issues, shared plans linkable to multiple issues
Ready Work: Find issues with no blockers
Agent Teams: Coordinate multi-agent workflows with teammate:* labels and team context
Statistics: Aggregate metrics per project

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/sentiolabs/arc/main/scripts/install.sh | bash

The bootstrap script verifies the release checksum. If Arc is already installed, use arc self update. The script still accepts --force and --tag=vX.Y.Z for reinstalls and updates from older Arc binaries.

Linux Packages

Download .deb, .rpm, or .pkg.tar.zst (Arch) from the latest release.

# Debian/Ubuntu
sudo dpkg -i arc_*_linux_amd64.deb

# Fedora/RHEL
sudo rpm -i arc_*_linux_amd64.rpm

# Arch Linux
sudo pacman -U arc_*_linux_amd64.pkg.tar.zst

Prerequisites

mise — provisions the toolchain (Go, bun, task, linters)
Docker — required only for integration and Playwright E2E tests

Install the toolchain and make sure mise is activated in your shell:

mise install

If mise is not activated in your shell (see the mise docs for your shell), tools pinned in mise.toml will not be on your PATH and commands like task build and task release will fail.

From Source

git clone https://github.com/sentiolabs/arc
cd arc
task build
# Binary at ./bin/arc

Quick Start

Start the Server

# Start the daemon (background)
arc server start

# Or run in foreground
arc server start --foreground

# Custom options
arc server start --foreground --port 8080 --db /path/to/data.db

The server stores data in ~/.arc/data.db by default.

CLI Usage

Getting Started

# Initialize arc in your project directory (creates project + config)
cd your-project
arc init                        # Uses directory name as project
arc init my-project             # Custom project name
arc init --prefix mp            # Custom issue prefix (e.g., mp-a3f2)

# Check which project is active
arc which

Day-to-Day Workflow

# Find available work
arc ready                       # Issues with no blockers
arc blocked                     # Issues waiting on dependencies

# Create issues
arc create "Implement feature X" -p 1 -t feature
arc create "Fix bug Y" -p 0 -t bug --label=bug
arc create "Refactor auth" --label=backend --label=tech-debt

# View and update issues
arc show mp-abc123
arc list                        # All issues
arc list --status open --type bug
arc list --parent mp-abc123     # List children of an epic
arc update mp-abc123 --status in_progress
arc update mp-abc123 --label-add=urgent --label-remove=backlog

# Close issues
arc close mp-abc123 --reason "Fixed in commit abc"

# View statistics
arc stats

Dependencies

# Add a blocker: def456 depends on abc123
arc dep add mp-def456 mp-abc123

# Other dependency types
arc dep add child parent --type parent-child
arc dep add issue-a issue-b --type related
arc dep add side-quest origin --type discovered-from

Epic & Subtask Patterns

# Create an epic with child issues
arc create "Auth overhaul" -t epic
arc create "JWT tokens" -t task --parent mp-abc123
arc create "OAuth provider" -t task --parent mp-abc123

Labels

# Manage global labels
arc label list                              # List all labels
arc label create bug --color="#ff0000"       # Create a label
arc label create feature --color="#00ff00" --description="New feature"
arc label update bug --description="Something is broken"
arc label delete stale                      # Delete a label

# Apply labels when creating or updating issues
arc create "Fix login" --label=bug --label=urgent
arc update mp-abc123 --label-add=critical --label-remove=backlog

Agent Teams

# Label tasks for team members
arc update mp-def456 --label-add=teammate:backend
arc update mp-ghi789 --label-add=teammate:frontend

# View team context (issues grouped by role)
arc team context mp-abc123      # For a specific epic
arc team context                # All teammate-labeled issues

# Prime context for a specific role
arc prime --role backend        # Filtered context for backend agent

Plans

# Register a plan for review (from a markdown file)
arc plan create --file docs/plans/2026-03-14-auth-system.md

# View plan content, status, and comments
arc plan show <plan-id>

# Review workflow
arc plan approve <plan-id>
arc plan reject <plan-id>
arc plan comments <plan-id>

Documentation & Help

arc docs                        # Overview of all topics
arc docs search "dependencies"  # Fuzzy search across all docs
arc docs plans                  # Full topic on plans
arc quickstart                  # Quick start guide
arc self update                 # Update to latest version

Advanced: Project Management

# For multi-project setups or manual project control
arc project create my-project
arc project use my-project      # Set default project
arc project list
arc project delete ws-abc123

Claude Code Integration

For AI-assisted workflows, arc provides a Claude Code plugin with hooks, skills, and agents.

Option A: Install Plugin (Recommended)

# In Claude Code, first add the marketplace
/plugin marketplace add sentiolabs/arc

# Then install the plugin
/plugin install arc

# Restart Claude Code

What the Plugin Provides:

Component	Benefit
SessionStart Hook	Auto-runs `arc prime` on session start
PreCompact Hook	Preserves context before compaction
Prompt Config	Reminds Claude to run `arc onboard`
Skills (9)	Guided workflows (see below)
Agents (2)	Issue tracker + code reviewer

Planning Workflow (Skills):

The plugin includes 9 skills that guide Claude through a structured development lifecycle:

brainstorm → plan → implement → review → finish
                        ↓           ↓
                      debug       verify

Skill	Purpose
`brainstorm`	Socratic design discovery — explores requirements, proposes approaches, saves design to arc
`plan`	Breaks approved designs into self-contained implementation tasks with exact file paths
`implement`	Dispatches `arc-implementer` subagents per task (TDD: red → green → refactor)
`review`	Dispatches `arc-reviewer` subagent to review code changes against task spec
`debug`	Root cause analysis when tests fail or implementations get stuck
`verify`	Fresh verification before claiming work is complete
`finish`	Session completion — updates arc issues, commits, pushes
`arc`	General arc CLI reference and workflow context
`arc-team-deploy`	Multi-agent team deployment with `teammate:*` label routing

Typical Setup:

# 1. Start the server (if not running)
arc server start

# 2. Initialize project in your directory
cd your-project
arc init

# 3. Install Claude integration
/plugin marketplace add sentiolabs/arc && /plugin install arc

API Examples

# Health check
curl http://localhost:7432/health

# Create project
curl -X POST http://localhost:7432/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "prefix": "mp"}'

# List issues
curl http://localhost:7432/api/v1/projects/ws-abc123/issues

# Create issue
curl -X POST http://localhost:7432/api/v1/projects/ws-abc123/issues \
  -H "Content-Type: application/json" \
  -d '{"title": "New feature", "priority": 1, "issue_type": "feature"}'

# Get ready work
curl http://localhost:7432/api/v1/projects/ws-abc123/ready

Architecture

flowchart TB
    subgraph server["Central Server"]
        subgraph projects["Projects"]
            ws1["Project A"]
            ws2["Project B"]
            ws3["Project C"]
        end
        db[("SQLite DB<br/>~/.arc/data.db")]
        projects --> db
    end

    api{{"REST API<br/>localhost:7432"}}
    server --> api

    subgraph clients["CLI Clients"]
        cli1["arc CLI<br/>(project-1)"]
        cli2["arc CLI<br/>(project-2)"]
        cli3["arc CLI<br/>(project-3)"]
    end

    api --> cli1
    api --> cli2
    api --> cli3

Data Model

Project

ID (e.g., "ws-a1b2")
Name, description
Prefix for issue IDs

Issue

ID (e.g., "mp-abc123")
Title, description
Status: open, in_progress, blocked, deferred, closed
Priority: 0 (critical) - 4 (backlog)
Type: bug, feature, task, epic, chore
External reference

Dependency Types

blocks: Issue A blocks issue B (affects ready work)
parent-child: Hierarchical relationship (affects ready work)
related: Loose association
discovered-from: Discovered during work on another issue

Label

Name, color, description
Global scope (shared across projects)

Comment

Text with author
Type: comment (regular) or plan (inline plan)

Event

Audit trail entries (status changes, field updates, etc.)

Plan (Shared)

ID (e.g., "plan.xxxxx"), title, content
Scoped to project, linkable to multiple issues

Configuration

Arc uses three configuration layers (highest priority wins):

CLI config (~/.arc/cli-config.json) — server URL, default project
Project config (~/.arc/projects/<path>/config.json) — per-directory project binding

{
  "server_url": "http://localhost:7432",
  "default_project": "ws-abc123"
}

Resolution priority: CLI flag > project config > CLI config defaults.

Development

# Build everything (frontend + binaries)
task build

# Build binaries only (faster)
task build:quick

# Run tests
task test

# Generate code (sqlc, OpenAPI, TypeScript)
task gen

# Docker
task docker:build
task docker:up

Commands run via go-task. Run task --list to see every available task. make <target> still works — the Makefile is a thin wrapper that forwards to task.

API Reference

Projects

GET /api/v1/projects - List projects
POST /api/v1/projects - Create project
GET /api/v1/projects/:id - Get project
PUT /api/v1/projects/:id - Update project
DELETE /api/v1/projects/:id - Delete project
GET /api/v1/projects/:id/stats - Get statistics

Workspaces (Directory Paths)

GET /api/v1/projects/:id/workspaces - List workspace paths
POST /api/v1/projects/:id/workspaces - Add workspace path
DELETE /api/v1/projects/:id/workspaces/:wid - Remove workspace path

Issues

GET /api/v1/projects/:id/issues - List issues
POST /api/v1/projects/:id/issues - Create issue
GET /api/v1/projects/:id/issues/:iid - Get issue
PUT /api/v1/projects/:id/issues/:iid - Update issue
DELETE /api/v1/projects/:id/issues/:iid - Delete issue
POST /api/v1/projects/:id/issues/:iid/close - Close issue
POST /api/v1/projects/:id/issues/:iid/reopen - Reopen issue

Ready Work & Blocked

GET /api/v1/projects/:id/ready - Ready issues
GET /api/v1/projects/:id/blocked - Blocked issues

Team Context

GET /api/v1/projects/:id/team-context - Issues grouped by teammate:* labels
GET /api/v1/projects/:id/team-context?epic_id=ID - Scoped to epic children

Dependencies

GET /api/v1/projects/:id/issues/:iid/deps - Get dependencies
POST /api/v1/projects/:id/issues/:iid/deps - Add dependency
DELETE /api/v1/projects/:id/issues/:iid/deps/:dep - Remove dependency

Labels (Global)

GET /api/v1/labels - List labels
POST /api/v1/labels - Create label
PUT /api/v1/labels/:name - Update label
DELETE /api/v1/labels/:name - Delete label

Issue Labels

POST /api/v1/projects/:id/issues/:iid/labels - Add label to issue
DELETE /api/v1/projects/:id/issues/:iid/labels/:label - Remove label

Comments

GET /api/v1/projects/:id/issues/:iid/comments - Get comments
POST /api/v1/projects/:id/issues/:iid/comments - Add comment
PUT /api/v1/projects/:id/issues/:iid/comments/:cid - Update comment
DELETE /api/v1/projects/:id/issues/:iid/comments/:cid - Delete comment

Inline Plans

POST /api/v1/projects/:id/issues/:iid/plan - Set inline plan
GET /api/v1/projects/:id/issues/:iid/plan - Get inline plan
GET /api/v1/projects/:id/issues/:iid/plan/history - Get plan history

Shared Plans

GET /api/v1/projects/:id/plans - List shared plans
POST /api/v1/projects/:id/plans - Create shared plan
GET /api/v1/projects/:id/plans/:pid - Get shared plan
PUT /api/v1/projects/:id/plans/:pid - Update shared plan
DELETE /api/v1/projects/:id/plans/:pid - Delete shared plan
POST /api/v1/projects/:id/plans/:pid/link - Link issues to plan
DELETE /api/v1/projects/:id/plans/:pid/link/:iid - Unlink issue from plan

Events

GET /api/v1/projects/:id/issues/:iid/events - Get audit events

Releasing

Release candidates and nightlies

Tag release candidates on main with the next version and a dotted counter: v0.16.0-rc.1, v0.16.0-rc.2. Arc also compares legacy counters numerically: rc9 sorts below rc10, and rc10 compares equal to rc.10. The original release tag is preserved for downloads. Older Arc binaries may need a one-time arc self update --force when switching from undotted to dotted RC tags.

arc self update asks for confirmation before installing. Pass -y or --yes to skip the prompt in scripts. Updates use selfupdate-go v0.2.1 to download and verify the release archive, then atomically replace the current executable. No shell installer, curl, or wget is needed for self-updates. A running local server is stopped only after verification and restarted using the installed binary; a stopped server stays stopped. Major/minor updates retain the pre-update database backup.

Package-managed binaries (including Homebrew, system packages, and Nix) must be updated with their package manager. Native updates refuse managed paths and unwritable installation directories instead of moving Arc to another location. On macOS, the native installer also performs ad-hoc signing. If the server fails to restart after a successful update, the command reports that the binary was updated and instructs you to retry arc server start.

Nightlies are tagged automatically as v<next patch>-nightly.<date>. The next patch, not the released version, is what makes a nightly sort above the current release. The update channel logic always prefers a newer stable release.

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
api		api
cmd/arc		cmd/arc
docs/plans		docs/plans
internal		internal
scripts		scripts
taskfiles		taskfiles
tests/integration		tests/integration
web		web
.air.toml		.air.toml
.dockerignore		.dockerignore
.gitignore		.gitignore
.golangci.yaml		.golangci.yaml
.goreleaser.yaml		.goreleaser.yaml
.mockery.yaml		.mockery.yaml
.release-please-manifest.json		.release-please-manifest.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
Dockerfile.integration		Dockerfile.integration
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
Taskfile.yml		Taskfile.yml
docker-compose.test.yml		docker-compose.test.yml
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
mise.toml		mise.toml
release-please-config.json		release-please-config.json
sqlc.yaml		sqlc.yaml

Latest commit

History

Folders and files

Repository files navigation

Features

Installation

Quick Install (Recommended)

Linux Packages

Prerequisites

From Source

Quick Start

Start the Server

CLI Usage

Getting Started

Day-to-Day Workflow

Dependencies

Epic & Subtask Patterns

Labels

Agent Teams

Plans

Documentation & Help

Advanced: Project Management

Claude Code Integration

API Examples

Architecture

Data Model

Project

Issue

Dependency Types

Label

Comment

Event

Plan (Shared)

Configuration

Development

API Reference

Projects

Workspaces (Directory Paths)

Issues

Ready Work & Blocked

Team Context

Dependencies

Labels (Global)

Issue Labels

Comments

Inline Plans

Shared Plans

Events

Releasing

Release candidates and nightlies

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages