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 action survives context resets
- Quick workflow:
chainlink quick creates, 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 next suggests what to work on based on priority and progress
- Tree view: Visualize issue hierarchy with
chainlink tree
- JSON output:
--json flag for structured, machine-readable output
- Quiet mode:
--quiet flag for minimal, pipe-friendly output
- Batch operations:
close-all with 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 / -q to 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