🤖 AI-Chain-CLI

A local-first issue tracker CLI built for AI-assisted development. Track tasks, manage sessions, and preserve context across AI assistant restarts — all from your terminal.

AI-Chain-CLI solves a real problem: when your AI assistant's context resets mid-session, you lose track of what was being worked on. AI-Chain-CLI keeps that memory alive with session handoff notes, breadcrumb actions, and a beautiful interactive TUI dashboard.

AI-Chain-CLI: The Missing Memory Layer for AI-Assisted Development

🤔 What is AI-Chain-CLI?

AI-Chain-CLI is a simple command-line tool that tracks your issues, tasks, and progress — all stored locally in a SQLite database. No cloud, no accounts, no syncing headaches.

It was designed specifically for developers who work with AI coding assistants (like Claude, GPT, Cursor, etc.). When your AI assistant's context window resets or gets compressed, AI-Chain-CLI preserves the memory of:

What you were working on (session + active issue)
What you just did (breadcrumb actions)
What to do next (handoff notes for the next session)
Overall project state (all open issues, priorities, blockers)

Think of it as a sticky note system that your AI assistant can read.

✨ Key Features

🖥️ Interactive TUI Dashboard

Launch a full-screen terminal interface with ai-chain tui — a dark-themed, keyboard-driven dashboard with 4 tabs (Dashboard, Issues, Milestones, Session), live search, priority-colored issues, timer widgets, and popup dialogs for creating/managing issues.

📦 Local-First Storage

All data lives in .chainlink/issues.db (SQLite). No servers, no network requests, no accounts. Your data stays on your machine.

🧠 AI Context Preservation

Sessions — Start/end work sessions with handoff notes
Breadcrumb Actions — Record what you're doing so your AI assistant can catch up after a context reset
Auto-stale detection — Sessions idle >4 hours are automatically ended

📝 Full Issue Management

Create, update, close, reopen, and delete issues
Priorities — low, medium, high, critical
Labels — Tag issues with any label (bug, feature, docs, etc.)
Subissues — Break big tasks into smaller trackable pieces
Dependencies — Track which issues block each other
Related Issues — Link related issues for context
Comments — Add notes and updates to issues
Templates — Quick-start with bug, feature, refactor, research, audit templates

🎯 Project Organization

Milestones — Group issues into releases or epics
Tree View — See your issue hierarchy at a glance
Smart Recommendations — ai-chain next suggests what to work on based on priority and progress
Archiving — Move old closed issues out of the way

⏱️ Time Tracking

Start and stop timers on issues to track how long you spend on each task.

📤 Export & Import

Backup your issues to JSON and restore them anytime.

🤖 AI Integration

Built-in Claude Code hooks for behavioral guardrails
Context provider script works with any AI assistant (Cursor, Aider, GPT, etc.)
JSON output mode for machine-readable data

📥 Installation

From crates.io (Recommended)

cargo install ai-chain-cli

After installation, the ai-chain command will be available in your terminal.

Build from Source

# Clone the repository
git clone https://github.com/brainRottedCoder/AI-chain-CLI.git
cd AI-chain-CLI/chainlink

# Option 1: Install globally
cargo install --path .

# Option 2: Build without installing
cargo build --release
# Binary will be at target/release/ai-chain

Requirements

Rust 1.70+ (for building)
Python 3.6+ (optional, only needed for Claude Code hooks)

🚀 Quick Start (Get Running in 60 Seconds)

Step 1: Initialize AI-Chain-CLI in your project

cd your-project
ai-chain init

This creates a .chainlink/ folder with the SQLite database and configuration files.

Step 2: Create some issues

# Simple issue
ai-chain create "Fix login bug"

# Issue with priority and label
ai-chain create "Fix login bug" -p high -l bug

# Issue with a description
ai-chain create "Add dark mode" -d "Support light/dark theme toggle"

# Quick create + label + start working on it (all in one command)
ai-chain quick "Fix token refresh" -p high -l bug

# Create from a template (auto-fills description structure)
ai-chain create "Login fails on refresh" --template bug

Step 3: Start a work session

# Begin a session
ai-chain session start

# Tell AI-Chain-CLI which issue you're working on
ai-chain session work 1

# Record what you're doing (breadcrumbs survive context resets)
ai-chain session action "Investigating token refresh logic"

Step 4: When you're done

# End your session with notes for next time
ai-chain session end --notes "Fixed auth bug, dark mode is next"

Step 5: Next time you start working

ai-chain session start
# → Shows you the handoff notes from last session!
# → "Fixed auth bug, dark mode is next"

🖥️ Interactive TUI Dashboard

Launch the full interactive dashboard:

ai-chain tui

What You'll See

The TUI has 4 tabs with a dark Catppuccin-inspired color scheme:

Tab	What It Shows
Dashboard	Session status card, priority breakdown bar chart, active timer, "Next Up" recommendation, ready issues list, project stats
Issues	Filterable/searchable issue table with detail panel showing description, subissues, comments, labels, blockers, time tracked
Milestones	Milestone list with progress percentages and issue breakdown
Session	Current session info, previous session handoff notes, quick hints

Keyboard Shortcuts

Key	Action
`Tab` / `Shift+Tab`	Switch between tabs
`1` `2` `3` `4`	Jump directly to a tab
`j` / `k` or `↑` / `↓`	Navigate up/down in lists
`Enter`	Open/close issue detail panel
`Esc`	Close panel / cancel
`/`	Search issues (live filtering)
`f`	Cycle filter: open → closed → all
`n`	Create a new issue (popup dialog)
`c`	Close the selected issue
`r`	Reopen the selected issue
`d`	Delete issue (with confirmation)
`l`	Add a label to the selected issue
`t`	Start/stop timer on the selected issue
`s`	Start/end session (on Session tab)
`?`	Show full help overlay
`q`	Quit the TUI

TUI Features in Detail

Live search: Press / in the Issues tab, start typing, and the list filters in real-time
Priority colors: Critical (red), High (orange), Medium (yellow), Low (green)
Spinner animation: The timer widget shows a live spinner when running
Issue detail panel: Press Enter on any issue to see its full description, subissues (with completion checkmarks), comments, blockers, related issues, labels, and time tracked
Create issue popup: Press n to open a dialog — type a title, press Enter, add a description, press Tab to cycle priority, press Enter to create
Status bar: Always shows your current mode (NORMAL/SEARCH/INSERT), active session info, timer, and help hint

📖 All CLI Commands

Issue Management

Command	What It Does
`ai-chain create <title>`	Create a new issue
`ai-chain create <title> -p high`	Create with priority (low / medium / high / critical)
`ai-chain create <title> -d "description"`	Create with a description
`ai-chain create <title> --template bug`	Create from template (bug / feature / refactor / research / audit / investigation / continuation)
`ai-chain create <title> --work -l bug`	Create, label, and immediately start working on it
`ai-chain quick <title> [-p high] [-l label]`	Shorthand: create + label + set as active work item
`ai-chain subissue <parent_id> <title>`	Create a sub-task under a parent issue
`ai-chain subissue <parent_id> <title> -p high`	Sub-task with priority
`ai-chain list`	List all open issues
`ai-chain list -s all`	List all issues (open + closed)
`ai-chain list -s closed`	List only closed issues
`ai-chain list -l bug`	Filter by label
`ai-chain list -p high`	Filter by priority
`ai-chain show <id>`	Show full details of an issue
`ai-chain show <id> --json`	Show issue details as JSON
`ai-chain search "query"`	Search issues by text (titles, descriptions, comments)
`ai-chain update <id> --title "New Title"`	Update an issue's title
`ai-chain update <id> -d "new description"`	Update description
`ai-chain update <id> -p critical`	Change priority
`ai-chain close <id>`	Close an issue
`ai-chain close <id> --no-changelog`	Close without adding a changelog entry
`ai-chain close-all`	Close all open issues
`ai-chain close-all -l bug`	Close all issues with a specific label
`ai-chain close-all -p low`	Close all issues with a specific priority
`ai-chain reopen <id>`	Reopen a closed issue
`ai-chain delete <id>`	Delete an issue (asks for confirmation)
`ai-chain 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	What It Does
`ai-chain comment <id> "text"`	Add a comment to an issue
`ai-chain label <id> <label>`	Add a label to an issue
`ai-chain unlabel <id> <label>`	Remove a label from an issue

Dependencies (Blocking Relationships)

Dependencies let you say "issue A can't be done until issue B is finished."

Command	What It Does
`ai-chain block <id> <blocker_id>`	Mark an issue as blocked by another
`ai-chain unblock <id> <blocker_id>`	Remove a blocking relationship
`ai-chain blocked`	Show all currently blocked issues
`ai-chain ready`	Show issues ready to work on (no open blockers)

Example:

# Issue #3 can't start until issue #1 is done
ai-chain block 3 1

# Now #3 won't show up in "ready" until #1 is closed
ai-chain ready
# → Only shows issues with no blockers

# Once you close #1, issue #3 becomes ready
ai-chain close 1
ai-chain ready
# → Now #3 appears!

Related Issues

Link issues that are related but don't block each other.

Command	What It Does
`ai-chain relate <id1> <id2>`	Link two related issues
`ai-chain unrelate <id1> <id2>`	Remove relationship

Milestones

Group issues into milestones (like sprints, releases, or epics).

Command	What It Does
`ai-chain milestone create <name>`	Create a new milestone
`ai-chain milestone create <name> -d "description"`	Create with description
`ai-chain milestone list`	List all milestones
`ai-chain milestone show <id>`	Show milestone details and progress
`ai-chain milestone add <milestone_id> <issue_id>`	Add an issue to a milestone
`ai-chain milestone remove <milestone_id> <issue_id>`	Remove an issue from a milestone
`ai-chain milestone close <id>`	Close a milestone
`ai-chain milestone delete <id>`	Delete a milestone

Example:

# Create a milestone for v1.0 release
ai-chain milestone create "v1.0 Release" -d "First public release"

# Add issues to it
ai-chain milestone add 1 3
ai-chain milestone add 1 4
ai-chain milestone add 1 5

# Check progress
ai-chain milestone show 1
# → Shows 0/3 issues closed, with issue list

Archiving

Move old closed issues out of the way to keep your active list clean.

Command	What It Does
`ai-chain archive add <id>`	Archive a closed issue
`ai-chain archive remove <id>`	Restore an archived issue
`ai-chain archive list`	List all archived issues
`ai-chain archive older <days>`	Archive all issues closed more than N days ago

Example:

# Archive everything closed more than 30 days ago
ai-chain archive older 30

# View archived issues
ai-chain archive list

# Restore one if needed
ai-chain archive remove 5

Smart Navigation

Command	What It Does
`ai-chain next`	Recommends the best issue to work on next (based on priority + progress)
`ai-chain tree`	Show all issues in a tree hierarchy (parent/subissue relationships)
`ai-chain tree -s open`	Show only open issues in tree view

ai-chain next uses a scoring algorithm:

Critical = 400 points, High = 300, Medium = 200, Low = 100
+50 bonus for partially-complete issues (finish what you started!)
Skips subissues (recommends parent issues instead)

Time Tracking

Track how long you spend on each issue.

Command	What It Does
`ai-chain start <id>`	Start a timer for an issue
`ai-chain stop`	Stop the current timer
`ai-chain timer`	Show current timer status

The TUI dashboard also shows a live timer widget — press t to start/stop.

Session Management

Sessions are AI-Chain-CLI's killer feature. They preserve context across AI assistant restarts.

Command	What It Does
`ai-chain session start`	Start a new session (shows previous handoff notes)
`ai-chain session work <id>`	Set which issue you're currently working on
`ai-chain session action "text"`	Record a breadcrumb (survives AI context compression)
`ai-chain session status`	Show current session info and duration
`ai-chain session end`	End the current session
`ai-chain session end --notes "text"`	End with handoff notes for the next session
`ai-chain session last-handoff`	View handoff notes from the previous session

How sessions help with AI assistants:

Start of session → AI reads your last handoff notes and picks up where you left off
During work → session action leaves breadcrumbs that survive context compression
End of session → Handoff notes capture what's done and what's next
Stale detection → Sessions idle >4 hours are auto-ended on next startup

Export & Import

Command	What It Does
`ai-chain export`	Export all issues to JSON (prints to screen)
`ai-chain export -o backup.json`	Export to a file
`ai-chain export -f markdown`	Export as markdown
`ai-chain import backup.json`	Import issues from a JSON file

Code Clone Detection (CPITD)

Scan your codebase for duplicated code and auto-create issues.

Command	What It Does
`ai-chain cpitd scan [paths]`	Scan for code clones and create issues
`ai-chain cpitd status`	Show current clone detection status
`ai-chain cpitd clear`	Clear all clone detection data

Interactive TUI

Command	What It Does
`ai-chain tui`	Launch the full interactive terminal dashboard

See the TUI Dashboard section for details and keyboard shortcuts.

Daemon (Optional)

The daemon auto-flushes session state every 30 seconds in the background.

Command	What It Does
`ai-chain daemon start`	Start background daemon
`ai-chain daemon status`	Check if daemon is running
`ai-chain daemon stop`	Stop the daemon

Utility Commands

Command	What It Does
`ai-chain tested`	Mark tests as run (resets test reminder)
`ai-chain init`	Initialize ai-chain in current directory
`ai-chain init --force`	Re-initialize (resets hooks and rules to defaults)

🔄 Workflow Example

Here's what a typical workflow looks like:

# Morning: Start a new session
$ ai-chain 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
$ ai-chain 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)
$ ai-chain session action "Found root cause in refresh_token()"

# Add a comment with your findings
$ ai-chain comment 3 "Fixed the token refresh issue"

# Close the issue when done
$ ai-chain close 3
Closed issue #3

# See what's next
$ ai-chain ready
Ready issues (no blockers):
  #2    medium   Add dark mode

# End session with notes for tomorrow
$ ai-chain session end --notes "Closed auth bug #3. Dark mode is next."
Session #5 ended.
Handoff notes saved.

Or skip the CLI workflow entirely and use the interactive TUI:

$ ai-chain tui
# → Full dashboard with all your issues, sessions, timers, and more!

💾 Storage & Data

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

Database tables: issues, comments, sessions, dependencies, relations, labels, time_entries, milestones, milestone_issues.

To back up your data:

ai-chain export -o backup.json

To restore:

ai-chain import backup.json

🤖 Claude Code Hooks

AI-Chain-CLI includes behavioral hooks for Claude Code that inject best practice reminders into AI sessions.

Requirement: Python 3.6+ must be installed for hooks to work.

What the Hooks Do

Hook	Trigger	Purpose
`prompt-guard.py`	Every prompt	Injects language-specific best practices
`post-edit-check.py`	After file edits	Debounced linting reminder
`work-check.py`	Before write/edit	Enforces issue tracking
`session-start.py`	Session start/resume	Loads context, detects stale sessions

Behavioral Guardrails

The hooks enforce:

No Stubs — Complete, working code only (no placeholders or TODOs)
No Dead Code — Identify and remove unused code
Full Features — Implement features completely
Error Handling — Proper error handling everywhere
Security — Input validation, parameterized queries

Language Detection

The hooks auto-detect your project language and inject relevant best practices for: Rust, Python, JavaScript/TypeScript, Go, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, Zig, Odin, and Elixir.

Tracking Modes

Configure in .chainlink/hook-config.json:

{
  "tracking_mode": "strict"
}

Mode	Behavior
`strict`	Blocks code edits without an active issue
`normal`	Reminds gently but allows proceeding
`relaxed`	No enforcement — only blocks git mutations

Customizable Rules

Edit markdown files in .chainlink/rules/ to customize:

File	Purpose
`global.md`	Security, correctness, and style rules
`project.md`	Your project-specific rules
`tracking-strict.md`	Strict mode instructions
`tracking-normal.md`	Normal mode instructions
`tracking-relaxed.md`	Relaxed mode instructions
`rust.md`, `python.md`, etc.	Language-specific best practices

To reset rules to defaults: ai-chain init --force

🔌 Using AI-Chain-CLI with Any AI Agent

The context provider script (context-provider.py) generates context that can be injected into any AI assistant's prompt.

Quick Setup (Shell Aliases)

Bash/Zsh — add to ~/.bashrc or ~/.zshrc:

# Generic AI wrapper - prepends ai-chain context to any prompt
ai() {
    local ctx=$(python ~/.chainlink/integrations/context-provider.py 2>/dev/null)
    echo -e "$ctx\n\n---\nUser: $*" | your-llm-cli
}

# Copy context to clipboard for pasting into web UIs
ai-chain-ctx() {
    python ~/.chainlink/integrations/context-provider.py --clipboard
}

PowerShell:

function ai {
    $ctx = python "$env:USERPROFILE\.chainlink\integrations\context-provider.py" 2>$null
    "$ctx`n`n---`nUser: $($args -join ' ')" | your-llm-cli
}

Context Provider Options

# Full context (session + issues + rules + structure)
python context-provider.py

# Specific sections only
python context-provider.py --session      # Session state
python context-provider.py --issues       # Issues only
python context-provider.py --rules        # Coding rules
python context-provider.py --structure    # Project tree

# Output formats
python context-provider.py --format xml   # XML (default, best for LLMs)
python context-provider.py --format md    # Markdown (human readable)
python context-provider.py --format json  # JSON (programmatic)

# Helpers
python context-provider.py --clipboard   # Copy to clipboard
python context-provider.py --env         # Output as env vars

Agent-Specific Integration

Agent	How to Integrate
Cursor	`python context-provider.py --format md --rules > .cursorrules`
Aider	`python context-provider.py --format md > context.md && aider --read context.md`
Continue.dev	Add exec context provider in `.continue/config.json`
Web UIs	`python context-provider.py --clipboard` then paste
OpenAI/Anthropic API	Include output as system message

🔵 VS Code Extension

AI-Chain-CLI is also available as a VS Code extension:

Install: Search "AI-Chain Issue Tracker" in VS Code Extensions.

Features:

Commands accessible from Command Palette (Ctrl+Shift+P)
Status bar indicator for daemon status
Auto-starts daemon when .chainlink project detected
Works on Windows, Linux, and macOS

🛠️ Development

# Run all tests
cargo test

# Run with clippy linting
cargo clippy -- -D warnings

# Format code
cargo fmt

# Build for release
cargo build --release

Project Structure

AI-chain-CLI/
├── src/
│   ├── main.rs          # CLI entry point (clap commands)
│   ├── lib.rs           # Library exports
│   ├── db.rs            # SQLite database operations
│   ├── models.rs        # Data structures (Issue, Session, etc.)
│   ├── utils.rs         # Utilities
│   ├── daemon.rs        # Background daemon
│   ├── commands/        # Command handlers (one per file)
│   │   ├── create.rs, list.rs, show.rs, ...
│   │   └── mod.rs
│   └── tui/             # Interactive TUI dashboard
│       ├── mod.rs       # Terminal setup & event loop
│       ├── app.rs       # Application state & data loading
│       ├── theme.rs     # Color palette & styles
│       ├── handlers.rs  # Keyboard input handling
│       └── ui.rs        # Rendering (all 4 tabs + popups)
├── tests/
│   └── cli_integration.rs  # Integration tests
├── resources/           # Bundled hooks & rules
└── Cargo.toml

📄 License

MIT

ai-chain-cli 0.1.3

🤖 AI-Chain-CLI

📋 Table of Contents

🤔 What is AI-Chain-CLI?

✨ Key Features

🖥️ Interactive TUI Dashboard

📦 Local-First Storage

🧠 AI Context Preservation

📝 Full Issue Management

🎯 Project Organization

⏱️ Time Tracking

📤 Export & Import

🤖 AI Integration

📥 Installation

From crates.io (Recommended)

Build from Source

Requirements

🚀 Quick Start (Get Running in 60 Seconds)

Step 1: Initialize AI-Chain-CLI in your project

Step 2: Create some issues

Step 3: Start a work session

Step 4: When you're done

Step 5: Next time you start working

🖥️ Interactive TUI Dashboard

What You'll See

Keyboard Shortcuts

TUI Features in Detail

📖 All CLI Commands

Issue Management

Comments & Labels

Dependencies (Blocking Relationships)

Related Issues

Milestones

Archiving

Smart Navigation

Time Tracking

Session Management

Export & Import

Code Clone Detection (CPITD)

Interactive TUI

Daemon (Optional)

Utility Commands

🔄 Workflow Example

💾 Storage & Data

🤖 Claude Code Hooks

What the Hooks Do

Behavioral Guardrails

Language Detection

Tracking Modes

Customizable Rules

🔌 Using AI-Chain-CLI with Any AI Agent

Quick Setup (Shell Aliases)

Context Provider Options

Agent-Specific Integration

🔵 VS Code Extension

🛠️ Development

Project Structure

📄 License