chainlink-safe-fetch

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

Tip: Add --quiet / -q to any command for minimal output (just the ID), useful for scripting and piping.

Comments & Labels

Dependencies

Related Issues

Milestones

Archiving

Export/Import

Smart Navigation

Time Tracking

Session Management

Sessions preserve context across AI assistant restarts. Stale sessions (idle >4 hours) are auto-ended on the next startup.

Daemon (Optional)

The daemon auto-flushes session state every 30 seconds.

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:

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