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 mode

$ chainlink session end --notes "Closed auth bug #3. Dark mode is next."
Session #5 ended.
Handoff notes saved.

Storage

All data is stored locally in .chainlink/issues.db (SQLite). No external services, no network requests.

Claude Code Hooks

Chainlink includes behavioral hooks for Claude Code that inject best practice reminders into AI sessions. These hooks help ensure Claude follows coding standards without requiring manual prompting.

Requirement: Python 3.6+ must be installed and available in your PATH for hooks to work. The VS Code extension will warn you if Python is not detected.

What the Hooks Do

The hooks are located in .claude/hooks/ and configured in .claude/settings.json:

Hook	Trigger	Purpose
prompt-guard.py	Every prompt	Injects language-specific best practices (condensed after first prompt)
post-edit-check.py	After file edits	Debounced linting reminder to verify changes compile
work-check.py	Before write/edit	Enforces issue tracking (configurable: strict/normal/relaxed) and blocks git mutations
session-start.py	Session start/resume	Loads context, detects stale sessions, restores breadcrumbs after context compression

Behavioral Guardrails

The hooks enforce these principles:

1. No Stubs: Implement complete, working code - no placeholder functions or TODO comments
2. No Dead Code: Identify incomplete features and complete them, or remove truly dead code
3. Full Features: Implement complete features as requested, don't stop partway
4. Error Handling: Proper error handling everywhere, no panics on bad input
5. Security: Validate input, use parameterized queries, no command injection

Large Task Management

When code will exceed 500 lines, the hooks guide Claude to: 1. Create a parent issue for the feature 2. Break it into subissues for trackable components 3. Inform the user about the multi-part implementation 4. Work on one subissue at a time

Language Detection

The hooks auto-detect the project language(s) and inject relevant best practices: - Rust: Use ? operator, clippy, parameterized SQL, avoid .unwrap() - Python: Type hints, proper exceptions, pathlib, context managers - JavaScript/TypeScript: const/let, async/await, strict mode, input validation - Go: Check errors, use context.Context, defer for cleanup - Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, Zig, Odin, Elixir: Language-specific best practices

Configuring Hook Behavior

Hook behavior is controlled by .chainlink/hook-config.json:

{
  "tracking_mode": "strict",
  "blocked_git_commands": ["git push", "git commit", "..."],
  "allowed_bash_prefixes": ["chainlink ", "git status", "..."]
}

Tracking Mode

Controls how aggressively chainlink enforces issue creation before code changes:

Mode	Hook Behavior	Prompt Language	Best For
strict	Blocks Write/Edit/Bash without an active issue	ALL CAPS MANDATORY, "ABSOLUTE RULE"	Teams that want every change tracked
normal	Reminds but allows proceeding without an issue	Soft "should" language, gentle nudges	Balanced — tracks most work, doesn't block quick fixes
relaxed	No enforcement — only git mutation blocks apply	Minimal — just mentions chainlink is available	Users who want tracking opt-in only

Each mode loads its instructions from .chainlink/rules/tracking-{mode}.md, so you can edit the wording per-mode.

Blocked Git Commands

Git mutation commands (push, commit, merge, rebase, etc.) are permanently blocked in all modes — these are human-only operations. You can customize the list in hook-config.json.

Read-only git commands (status, diff, log, show, branch) are always allowed.

Allowed Bash Prefixes

Commands that bypass the issue-required check