# 🤖 AI-Chain-CLI
[](https://crates.io/crates/ai-chain-cli)
[](https://crates.io/crates/ai-chain-cli)
[](LICENSE)
**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.
---
## 📋 Table of Contents
- [What is AI-Chain-CLI?](#-what-is-ai-chain-cli)
- [Key Features](#-key-features)
- [Installation](#-installation)
- [Quick Start](#-quick-start-get-running-in-60-seconds)
- [Interactive TUI Dashboard](#-interactive-tui-dashboard)
- [All CLI Commands](#-all-cli-commands)
- [Workflow Example](#-workflow-example)
- [Claude Code Hooks](#-claude-code-hooks)
- [Using with Any AI Agent](#-using-ai-chain-cli-with-any-ai-agent)
- [VS Code Extension](#-vs-code-extension)
- [Storage & Data](#-storage--data)
- [Development](#-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)
```bash
cargo install ai-chain-cli
```
After installation, the `ai-chain` command will be available in your terminal.
### Build from Source
```bash
# 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
```bash
cd your-project
ai-chain init
```
This creates a `.chainlink/` folder with the SQLite database and configuration
files.
### Step 2: Create some issues
```bash
# 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
```bash
# 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
```bash
# 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
```bash
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:
```bash
ai-chain tui
```
### What You'll See
The TUI has **4 tabs** with a dark Catppuccin-inspired color scheme:
| **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
| `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
| `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
| `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."
| `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:**
```bash
# 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.
| `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).
| `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:**
```bash
# 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.
| `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:**
```bash
# 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
| `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.
| `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.
| `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:**
1. **Start of session** → AI reads your last handoff notes and picks up where
you left off
2. **During work** → `session action` leaves breadcrumbs that survive context
compression
3. **End of session** → Handoff notes capture what's done and what's next
4. **Stale detection** → Sessions idle >4 hours are auto-ended on next startup
---
### Export & Import
| `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.
| `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
| `ai-chain tui` | Launch the full interactive terminal dashboard |
See the [TUI Dashboard section](#-interactive-tui-dashboard) for details and
keyboard shortcuts.
---
### Daemon (Optional)
The daemon auto-flushes session state every 30 seconds in the background.
| `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
| `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:
```bash
# 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:
```bash
$ 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:**
```bash
ai-chain export -o backup.json
```
**To restore:**
```bash
ai-chain import backup.json
```
---
## 🤖 Claude Code Hooks
AI-Chain-CLI includes behavioral hooks for
[Claude Code](https://claude.com/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
| `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:
1. **No Stubs** — Complete, working code only (no placeholders or TODOs)
2. **No Dead Code** — Identify and remove unused code
3. **Full Features** — Implement features completely
4. **Error Handling** — Proper error handling everywhere
5. **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`:
```json
{
"tracking_mode": "strict"
}
```
| `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:
| `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`:
```bash
# 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:**
```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
```bash
# 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
| **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
```bash
# 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