Chainlink
A simple, lean issue tracker CLI designed for AI-assisted development. Track tasks across sessions with context preservation.
Features
- Local-first: All data stored in SQLite (
.chainlink/issues.db) - Session management: Preserve context across Claude/AI sessions with handoff notes
- Context compression resilience: Breadcrumb tracking via
session actionsurvives context resets - Quick workflow:
chainlink quickcreates, labels, and starts work in one command - Issue templates: Built-in templates for bugs, features, audits, investigations, and more
- Subissues: Break large tasks into smaller, trackable pieces
- Dependencies: Track blocking relationships between issues
- Related issues: Link related issues together for context
- Labels & priorities: Organize issues with labels and priority levels
- Milestones: Group issues into milestones/epics for release planning
- Time tracking: Start/stop timers to track time spent on issues
- Smart recommendations:
chainlink nextsuggests what to work on based on priority and progress - Tree view: Visualize issue hierarchy with
chainlink tree - JSON output:
--jsonflag for structured, machine-readable output - Quiet mode:
--quietflag for minimal, pipe-friendly output - Batch operations:
close-allwith label/priority filtering - Export/Import: Backup and restore issues in JSON format
- Issue archiving: Archive old closed issues to keep the active list clean
- Claude Code hooks: Behavioral guardrails that inject best practices into AI sessions
- Stale session detection: Auto-ends sessions idle >4 hours on next startup
- Customizable rules: Override default rules via
.chainlink/rules/markdown files - No sync complexity: No git hooks, no auto-push, just simple local storage
Installation
# Install from crates.io
cargo install chainlink-tracker
The binary is named chainlink and will be available in your PATH after install.
Build from Source
git clone https://github.com/dollspace-gay/chainlink.git
cd chainlink/chainlink
cargo install --path .
# The binary will be at ~/.cargo/bin
# Or build without installing
cargo build --release
# The binary will be at target/release/chainlink
Quick Start
# Initialize in any project
chainlink init
# Start a session when you begin work
chainlink session start
# Create issues
chainlink create "Fix login bug" -p high
chainlink create "Add dark mode" -d "Support light/dark theme toggle"
# Quick create + label + start working in one command
chainlink quick "Fix login bug" -p high -l bug
# Use a template for structured issues
chainlink create "Login fails on refresh" --template bug
# Set what you're working on
chainlink session work 1
# Record breadcrumbs before context compression
chainlink session action "Investigating token refresh logic"
# End session with handoff notes
chainlink session end --notes "Fixed auth bug, dark mode is next"
Commands
Issue Management
| Command | Description |
|---------|-------------|
| chainlink create <title> | Create a new issue |
| chainlink create <title> -p high | Create with priority (low/medium/high/critical) |
| chainlink create <title> -d "desc" | Create with description |
| chainlink create <title> --template bug | Create from template (bug/feature/refactor/research/audit/continuation/investigation) |
| chainlink create <title> --work -l bug | Create, label, and start working on it |
| chainlink quick <title> [-p high] [-l label] | Shorthand: create + label + set as active work item |
| chainlink subissue <parent_id> <title> | Create a subissue under a parent |
| chainlink subissue <parent_id> <title> -p high | Subissue with priority |
| chainlink list | List open issues |
| chainlink list -s all | List all issues |
| chainlink list -s closed | List closed issues |
| chainlink list -l bug | Filter by label |
| chainlink list -p high | Filter by priority |
| chainlink show <id> | Show issue details |
| chainlink show <id> --json | Show issue details as JSON |
| chainlink update <id> --title "New" | Update title |
| chainlink update <id> -d "desc" | Update description |
| chainlink update <id> -p critical | Update priority |
| chainlink close <id> | Close an issue |
| chainlink close <id> --no-changelog | Close without adding a changelog entry (e.g. internal scaffolding subissues) |
| chainlink close-all | Close all open issues |
| chainlink close-all --no-changelog | Close all without changelog entries (e.g. internal scaffolding subissues) |
| chainlink close-all -l bug | Close all issues with a specific label |
| chainlink close-all -p low | Close all issues with a specific priority |
| chainlink reopen <id> | Reopen a closed issue |
| chainlink delete <id> | Delete an issue (with confirmation) |
| chainlink delete <id> -f | Delete without confirmation |
Tip: Add
--quiet/-qto any command for minimal output (just the ID), useful for scripting and piping.
Comments & Labels
| Command | Description |
|---------|-------------|
| chainlink comment <id> "text" | Add a comment to an issue |
| chainlink label <id> <label> | Add a label to an issue |
| chainlink unlabel <id> <label> | Remove a label from an issue |
Dependencies
| Command | Description |
|---------|-------------|
| chainlink block <id> <blocker_id> | Mark issue as blocked by another |
| chainlink unblock <id> <blocker_id> | Remove blocking relationship |
| chainlink blocked | List all blocked issues |
| chainlink ready | List issues ready to work on (no blockers) |
Related Issues
| Command | Description |
|---------|-------------|
| chainlink relate <id1> <id2> | Link two related issues together |
| chainlink unrelate <id1> <id2> | Remove relationship between issues |
Milestones
| Command | Description |
|---------|-------------|
| chainlink milestone create <name> | Create a new milestone |
| chainlink milestone create <name> -d "desc" | Create with description |
| chainlink milestone list | List all milestones |
| chainlink milestone show <id> | Show milestone details and progress |
| chainlink milestone add <milestone_id> <issue_id> | Add an issue to a milestone |
| chainlink milestone remove <milestone_id> <issue_id> | Remove an issue from a milestone |
| chainlink milestone close <id> | Close a milestone |
| chainlink milestone reopen <id> | Reopen a closed milestone |
Archiving
| Command | Description |
|---------|-------------|
| chainlink archive <id> | Archive a closed issue |
| chainlink unarchive <id> | Restore an archived issue |
| chainlink archived | List all archived issues |
| chainlink archive-older <days> | Archive issues closed more than N days ago |
Export/Import
| Command | Description |
|---------|-------------|
| chainlink export | Export all issues to JSON (stdout) |
| chainlink export -o backup.json | Export to a file |
| chainlink import backup.json | Import issues from JSON file |
| chainlink import backup.json --merge | Merge with existing issues |
Smart Navigation
| Command | Description |
|---------|-------------|
| chainlink next | Recommend the next issue to work on (by priority/progress) |
| chainlink tree | Show all issues in a tree hierarchy |
| chainlink tree -s open | Show only open issues in tree view |
Time Tracking
| Command | Description |
|---------|-------------|
| chainlink start <id> | Start a timer for an issue |
| chainlink stop | Stop the current timer |
| chainlink timer | Show current timer status |
Session Management
Sessions preserve context across AI assistant restarts. Stale sessions (idle >4 hours) are auto-ended on the next startup.
| Command | Description |
|---------|-------------|
| chainlink session start | Start a session, shows previous handoff notes |
| chainlink session work <id> | Set the issue you're currently working on |
| chainlink session action "..." | Record a breadcrumb (survives context compression) |
| chainlink session status | Show current session info and last action |
| chainlink session end | End the current session |
| chainlink session end --notes "..." | End with handoff notes for next session |
| chainlink session last-handoff | Retrieve handoff notes from the previous session |
Daemon (Optional)
The daemon auto-flushes session state every 30 seconds.
| Command | Description |
|---------|-------------|
| chainlink daemon start | Start background daemon |
| chainlink daemon status | Check if daemon is running |
| chainlink daemon stop | Stop the daemon |
Workflow Example
$ chainlink session start
Previous session ended: 2026-01-15 09:00
Handoff notes:
Working on auth bug. Found issue in token refresh.
Session #5 started.
# Quick create + label + start working in one step
$ chainlink quick "Fix token refresh" -p high -l bug
Created issue #3
Now working on: #3 Fix token refresh
# Record breadcrumbs as you work (survives context compression)
$ chainlink session action "Found root cause in refresh_token()"
$ chainlink comment 3 "Fixed the token refresh issue"
Added comment to issue #3
$ chainlink close 3
Closed issue #3
$ chainlink ready
Ready issues (no blockers):
#2 medium Add dark m