Show only sparse issues (need more context, fewer than 25 tokens)
--dense
Show only dense issues (may need splitting, over 2000 tokens)
Examples:
Copy
# All open issuestk list# Only bugstk list -t bug# High priority only (P0-P1)tk list -p 1# In-progress issuestk list -s in_progress# Issues needing more contexttk list --sparse
Check if a stack is ready for merging. Returns exit code 0 for valid, 1 for invalid.
Copy
tk stacks validate <stack-id>
Validation checks:
All non-tip issues in the stack are closed
Tip issue has no external blockers (outside the stack)
All issues in the stack exist
Sample output (valid):
Copy
✓ Stack Validation: stack-1 PASS Stack is ready for merge! All 3 issues are in valid state for merging. Issues: ✓ tk-abc [closed] (root) - Auth: Base service setup ✓ tk-def [closed] - Auth: Login endpoint ✓ tk-ghi [open] (tip) - Auth: Frontend integration
Sample output (invalid):
Copy
✗ Stack Validation: stack-1 FAIL Stack is NOT ready for merge. Issues: ✓ tk-abc [closed] (root) - Auth: Base service setup ✗ tk-def [open] - Auth: Login endpoint → expected closed but is open ✓ tk-ghi [open] (tip) - Auth: Frontend integration Fix To fix: - Close these issues: tk-def
Sync issues with Claude Code tasks (bidirectional).
Copy
tk claude sync [OPTIONS]
Options:
Option
Description
--pull
Pull tasks from Claude to tk (one-way)
--push
Push issues from tk to Claude (one-way)
--dry-run
Preview changes without syncing
--state <STATE>
Only sync issues in this state: open, closed, all (default: open)
Examples:
Copy
# Bidirectional sync (default)tk claude sync# Preview what would changetk claude sync --dry-run# Only push local issues to Claudetk claude sync --push# Only pull Claude tasks to localtk claude sync --pull
Auto-detects current Claude Code session from ~/.claude/tasks/. Maintains claude_task_id field for sync tracking.
Create tutorial-style demo issues that teach tk interactively.
Copy
tk demo [OPTIONS]
Options:
Option
Description
--clear
Clear existing demo issues first
What it creates:The demo creates 7 tutorial issues that guide you through tk’s core features:
tk-001 — Learn tk list to see all issues
tk-002 — Learn tk ready to find unblocked work
tk-003 — Learn tk claim to start working (P0 priority, start here!)
tk-004 — Learn tk close to complete work (blocked by tk-003)
tk-005 — Learn tk priority for PageRank recommendations
tk-006 — Learn tk triage mega-command (blocked until basics learned)
tk-007 — Learn tk create to add new issues
The dependency graph creates a natural learning progression — complete tk-003 first to unblock tk-004.Example:
Copy
# Create demo issuestk demo# Output:# 🎭 Creating demo issues...## ✓ tk-001 [task] P1 - Run 'tk list' to see all issues# ✓ tk-002 [task] P1 - Try 'tk ready' to find unblocked work# ✓ tk-003 [task] P0 - Start work with 'tk claim tk-003'# ✓ tk-004 [task] P1 - Complete work with 'tk close'# ✓ tk-005 [task] P2 - Get recommendations with 'tk priority'# ✓ tk-006 [feature] P2 - Use 'tk triage' for full analysis# ✓ tk-007 [task] P3 - Create issues with 'tk create'## Follow the tutorial:# tk list - See all issues (start here!)# tk ready - Find work ready to start# tk claim tk-003 - Start working on an issue# tk close tk-003 - Complete an issue# tk priority - Get PageRank recommendations# tk triage - Full AI triage report# tk create "My task" - Create a new issue# Clean up demo issuestk demo --clear
Each demo issue contains instructions in its description. Use tk show tk-001 to read the full tutorial for any step.
Output format: compact, table, or json (default: compact)
--no-cache
Skip cache and compute fresh results (analytics commands only)
-h, --help
Print help
-V, --version
Print version
The --no-cache flag bypasses the analytics cache on commands like triage, ready, priority, plan, next, and insights. Use this when you want to force fresh computation or debug cache issues.
# Run all testscargo test# Run specific test suitecargo test --lib # Unit testscargo test --test '*' # Integration testscargo test cli::helpers # Helper tests
Typical performance on a repository with 68 issues:
Command
Cached
Rebuild
No Cache
tk ready
7ms
10ms
83ms
tk triage
14ms
15ms
850ms
tk plan
7ms
10ms
820ms
tk priority
7ms
10ms
890ms
tk stats
7ms
10ms
85ms
The cache uses filesystem mtime for instant freshness checks (2 stat calls) instead of computing SHA-256 hashes of all files. This makes cache validation essentially free.
# Check cache statustk cache info# Force rebuild if neededtk cache rebuild# Or bypass cache for debuggingtk triage --no-cache
Cache invalidation triggers on file creation/deletion, not just content changes. This is by design - most workflows (creating issues, resolving issues) naturally invalidate the cache at the right time.
# Always use JSON format for parsingtk -f json list | jq '.[] | .id'# Check exit codesif tk validate; then echo "All valid"fi# Use quotes for titles with spacestk create "Multi word title"