Issue Cards is an AI-optimized command-line issue tracking tool designed for both AI coding agents and human developers. (But primarily for keeping your coding agent on-task)
** Caveat Emptor: Pretty much every part of this was built using Claude Code, but I have actually used it for a couple of projects and it seems to do a good job of keeping the coding agent on task. **
I owe a blog post about how to use it. -Jesse, April 2025
- Simple File-Based Storage: All issues are stored as markdown files directly in your project
- Linear Task Sequencing: Tasks are presented in a clear, sequential order
- Tag-Based Task Expansion: Apply common patterns like testing requirements with simple tags
- Context-Rich Display: Each task shows all the context needed to implement it
- Git Integration: Automatically stages issue updates when using git
- AI Integration: Built-in MCP server for direct AI assistant integration
- AI-Friendly Output: Standardized command output format for easy parsing by AI agents
- Configurable: Customize directories and behavior through environment variables
# Install globally
npm install -g issue-cards
# Or use with npx
npx issue-cards <command># Initialize issue tracking in your project
issue-cards init
# Create a new feature issue
issue-cards create feature --title "Add search functionality"
# View your current task
issue-cards current
# Mark the current task as complete when done
issue-cards complete-task
# List all open issues
issue-cards listHere are the most essential commands to get started:
# Setup and issue creation
issue-cards init # Initialize issue tracking
issue-cards create feature --title "..." # Create a new feature issue
# Task workflow
issue-cards current # View current task with context
issue-cards complete-task # Mark task complete & show next
issue-cards add-task "New task" # Add a new task
# Issue management
issue-cards list # List all open issues
issue-cards show 1 # Show issue detailsFor detailed help on any command or topic:
# Get help on any command
issue-cards <command> --help
# View environment variables reference
issue-cards help env
# Browse all documentation
issue-cards helpEach issue contains:
- Title and issue number
- Problem description
- Planned approach
- Failed approaches (for logging attempts that didn't work)
- Questions to resolve
- Task list with sequential steps
- Instructions for implementation
- Next steps (optional preview of upcoming work)
issue-cards can be customized with environment variables and command-line options:
# Use a custom directory for issues
export ISSUE_CARDS_DIR=/path/to/custom/issues
# Get machine-parseable JSON output
issue-cards list --json
# Quiet mode for scripts
issue-cards complete-task --quietFor complete configuration references use built-in help:
# Environment variables reference
issue-cards help env
# Commands reference
issue-cards --helpIssue Cards provides a Model-Code-Prompt (MCP) API for AI assistant integration:
To use Issue Cards with Claude Code, add one of the following to your configuration:
# Using NPX (installs on-demand)
issue-cards: npx issue-cards-mcp-server@latest
# Using globally installed version (if installed with npm install -g issue-cards)
issue-cards: issue-cards-mcp-server
This will automatically set up the MCP server for seamless integration with Claude Code.
You can also start the server manually:
# Start the MCP server
issue-cards serve
# With authentication (recommended for production)
issue-cards serve --token your-secret-tokenEnables AI assistants to:
- Create and manage issues
- Complete tasks and track progress
- Document approaches and solutions
- Add context through notes and questions
Documentation:
# Issue 0001: Implement user authentication
## Problem to be solved
Users need to be able to securely log into the application.
## Planned approach
Use JWT tokens with secure cookie storage and implement proper password hashing.
## Failed approaches
- Tried using localStorage for token storage but found security vulnerabilities
## Questions to resolve
- What is the token expiration time?
## Tasks
- [ ] Create user model with password field #unit-test
- [ ] Implement password hashing and verification
- [ ] Create login endpoint #e2e-test
- [ ] Add JWT token generation
- [ ] Implement authentication middleware #unit-test
## Instructions
Follow the project's security guidelines when implementing authentication.
The JWT should include the user's role permissions.
## Next steps
Once authentication is complete, we'll implement:
- Authorization middleware for protected routes
- User profile managementTasks can be tagged to automatically expand with standardized steps:
# Add a task with testing tags
issue-cards add-task "Implement login form #unit-test #e2e-test"When viewing the task, it expands to show all required steps:
- Write unit tests, implement feature, verify tests pass
- Follow consistent workflows for different task types
Learn more with issue-cards help tags.
When working in a Git repository, issue-cards automatically stages changes to issue files when you:
- Complete tasks
- Add notes or questions
- Log failed approaches
issue-cards includes a comprehensive documentation system accessible both from the CLI and in markdown files:
Access help directly from the command line:
# Browse all documentation categories
issue-cards help
# View a specific documentation topic
issue-cards help tutorials/basic-workflow
# Get detailed help for a command
issue-cards create --helpThe documentation has been streamlined for clarity:
- Quick Start Guide - Essential setup and first issue workflow
- Common Workflows - Practical examples of using Issue Cards
- AI Integration Guide - How to use with AI assistants
- Contributing Guide - Information for project contributors
For additional help, run:
issue-cards helpContributions are welcome! Please see CONTRIBUTING.md for details.