juno-kanban 1.36.0

A shell-based kanban task manager with NDJSON storage and high-performance search

Juno Kanban - Dead Simple Shell Task Manager

A minimal, fast, and shell-friendly kanban task manager built for developers and LLM workflows. Store tasks in NDJSON format with high-performance search capabilities.

Quick Start

# Install in development mode
pip install -e .

# Create your first task
juno-kanban create "Implement user authentication" --tags backend security

# Optional title + body composition
juno-kanban create --title "Auth" --body "Implement OAuth callback handling"

# List recent tasks
juno-kanban list --limit 5
juno-kanban list --status backlog,in_progress --sort asc   # preserve explicit status order

# Search and filter
juno-kanban search --status todo --tags backend
juno-kanban search --status todo --format json             # command-level --format is supported

# Aggregate tag usage (optionally by workflow status)
juno-kanban tags --status todo,in_progress --format table

# Mark task progress with response (ID can be positional or flag)
juno-kanban mark in_progress ABC123 --response "Started OAuth integration"

# Complete with commit hash
juno-kanban mark done --id ABC123 --response "Auth completed" --commit abc123def

# Declare dependencies between tasks
juno-kanban create "Deploy to staging" --blocked-by ABC123

# Find tasks ready to work on (all blockers resolved)
juno-kanban ready
juno-kanban ready --sort asc   # oldest ready tasks first by last_modified
# ready now includes list-like summary counters (Displayed/Total + status breakdown)

# Get safe execution order respecting dependencies
juno-kanban order --scores

Installation

PyPI (Recommended)

pip install juno-kanban

After installation, all three commands are available:

• juno-kanban - Main command name
• juno-feedback - Alias (same functionality)
• kanban-juno - Alternative naming

Development Mode

git clone https://github.com/askbudi/juno-mono.git
cd juno-mono/juno_kanban
pip install -e .

Requirements

• Python 3.8+
• No external dependencies (uses Python stdlib only)
• Optional: ripgrep for 10-50x faster search performance

Shell Completion (Tab Autocomplete)

juno-kanban ships a native completion script generator:

# One-time test in current shell
source <(juno-kanban completion bash)

# Persist for bash
echo 'source <(juno-kanban completion bash)' >> ~/.bashrc

# Persist for zsh
echo 'source <(juno-kanban completion zsh)' >> ~/.zshrc

# Fish
juno-kanban completion fish > ~/.config/fish/completions/juno-kanban.fish

After reloading your shell, juno-kanban c<TAB><TAB> suggests commands like create/completion, and command-specific flags/choice values are also suggested (e.g. list --sort <TAB>).

Core Features

🗂️ NDJSON Storage

• Human-readable JSON format (one task per line)
• Supports code snippets, HTML, and special characters
• Easily parseable by shell tools and scripts

🔍 High-Performance Search

• Ripgrep integration for blazing-fast search across large files
• Multiple filter conditions (status, tags, commit hash, open tasks)
• Automatic fallback to Python for portability

🏷️ Flexible Organization

• Configurable status workflows (backlog → todo → done)
• Feature tags for categorization
• tags command for per-tag workload counts (supports status filtering + machine-readable formats)
• Commit hash linking for git integration

🔗 Task Dependencies

• Declare blockers with --blocked-by or body markup ([blocked_by]ID[/blocked_by])
• Declare non-blocking related references with [task_id]...[/task_id] or ## ID1 ID2 ##
• Cycle detection prevents circular dependencies
• ready command finds unblocked tasks for parallel execution
• order command returns topological sort for safe scheduling
• Priority scoring ranks tasks by how much downstream work they unblock

🤖 LLM & Shell Optimized

• jq-compatible output for automation
• Educational error messages with examples
• Context-aware help text
• Flexible task ID input (TASK_ID positional or --id/--ID on key commands)
• Agent-friendly create/deps parsing (--title, flag-only deps --id ... --blocked-by ..., trailing quoted body recovery)
• Clean, parseable formats

Usage Guide

Creating Tasks

# Basic task creation
juno-kanban create "Fix authentication bug"

# With tags and status
juno-kanban create "Add user profile page" --status todo --tags frontend ui

# Using --body flag (both formats work)
juno-kanban create --body "Implement OAuth" --tags security backend

# Optional title merged into body as: title:{title}\n\n{body}
juno-kanban create --title "OAuth" --body "Implement provider callback validation"

# Trailing quoted body after list flags is supported
juno-kanban create --status todo --related-tasks ABC123 "Add integration tests for callback flow"

Searching & Listing

# List recent tasks (sorted by last modified)
juno-kanban list --limit 10

# Search by status
juno-kanban search --status in_progress

# Search by tags
juno-kanban search --tags backend --tags security

# Aggregate tag counts across all tasks
juno-kanban tags

# Aggregate tag counts only for active work
juno-kanban tags --status todo,in_progress --format json
juno-kanban tags --status todo in_progress --format table

# Search open tasks (no agent response)
juno-kanban search --open

# Search recent tasks
juno-kanban search --recent --limit 5

# Control search sort order by last_modified
juno-kanban search --status todo --sort asc --limit 5

# Multiple conditions (AND logic)
juno-kanban search --status todo --tags backend --limit 3

--sort asc|desc uses one shared contract across list, search, and ready:

• asc = oldest last_modified first
• desc = newest last_modified first
• equal timestamps use task id as deterministic tie-breaker
• default list behavior preserves open-before-closed status priority (backlog/todo/in_progress before done/archive)
• when list or ready receives --status ..., task groups follow the provided status order, then --sort applies within each status group

Updating Tasks

# Update status (positional or --id both supported)
juno-kanban update ABC123 --status in_progress
juno-kanban update --id ABC123 --status in_progress

# Add agent response
juno-kanban update --id ABC123 --response "Working on OAuth flow"

# Set commit hash
juno-kanban update --id ABC123 --commit abc123def

# Update tags
juno-kanban update ABC123 --tags urgent backend security

Mark Command (Streamlined Workflow)

# Mark with required response
juno-kanban mark todo ABC123 --response "Ready to start"

# Mark as done with commit (recommended)
juno-kanban mark done --id ABC123 --response "Feature completed" --commit abc123

# Mark without commit (shows helpful reminder)
juno-kanban mark done ABC123 --response "Bug fixed"
# Output: Consider adding commit hash with --commit flag

Dependency Management

# Create a task that's blocked by another
juno-kanban create "Deploy to prod" --blocked-by ABC123

# Or declare blockers via body markup (auto-parsed)
juno-kanban create "Run integration tests [blocked_by]ABC123, DEF456[/blocked_by]"

# Add/remove dependencies after creation
juno-kanban deps add --id GHI789 --blocked-by ABC123 DEF456
juno-kanban deps remove --id GHI789 --blocked-by ABC123

# Shorthand add (action inferred when --blocked-by is present)
juno-kanban deps --id GHI789 --blocked-by ABC123 DEF456

# Query dependency info for a task
juno-kanban deps ABC123
juno-kanban deps --id ABC123
# Returns: blockers (met/unmet), dependents, priority score

# Find tasks ready to work on (all blockers resolved)
juno-kanban ready
juno-kanban ready --sort asc --limit 5                         # oldest ready tasks first
juno-kanban ready --status backlog,in_progress --sort desc     # backlog group first, then in_progress
juno-kanban ready --tag backend --sort desc                    # newest backend-ready tasks first

# Get safe execution order (topological sort)
juno-kanban order
juno-kanban order --scores  # includes priority scores

Body Markup for Dependencies

Dependencies and related tasks can be declared inline in the task body:

# Blockers (all synonyms are equivalent)
[blocked_by]ABC123[/blocked_by]
[block_by]ABC123[/block_by]
[block]ABC123[/block]
[parent_task]ABC123[/parent_task]

# Multiple blockers (comma or space separated)
[blocked_by]ABC123, DEF456[/blocked_by]

# Related tasks (non-blocking references)
[task_id]ABC123[/task_id]
## ABC123
##ABC123
## ABC123 DEF456 ##

# If a related ID is valid format but not found yet, it is kept as a
# forward reference and a warning is emitted.

Other Operations

# Get specific task(s) (includes dependency info)
juno-kanban get ABC123
juno-kanban get --id ABC123
juno-kanban get ABC123 DEF456 --format json   # ordered multi-ID lookup
juno-kanban show ABC123 DEF456 --format json  # alias

# Archive task (preserves data, sets status to archive)
juno-kanban archive ABC123
juno-kanban archive --id ABC123

# Merge task databases from multiple directories
juno-kanban merge /path/to/source/.juno_task --into ./.juno_task
juno-kanban merge --find-all --into ./.juno_task --dry-run

# Show help
juno-kanban --help
juno-kanban COMMAND --help

Output Formats

NDJSON (Default)

juno-kanban search --status todo

{"id": "ABC123", "status": "todo", "body": "Fix bug", "tags": ["backend"]}
{"id": "DEF456", "status": "todo", "body": "Add feature", "tags": ["frontend"]}

JSON (Structured)

juno-kanban search --status todo --format json
# also supported: juno-kanban --format json search --status todo

[
  {"id": "ABC123", "status": "todo", "body": "Fix bug", "tags": ["backend"]},
  {"id": "DEF456", "status": "todo", "body": "Add feature", "tags": ["frontend"]}
]

XML

juno-kanban search --status todo --format xml

Table (Human-readable)

juno-kanban search --status todo --format table

# tags command renders markdown table output in table mode
juno-kanban tags --status todo,in_progress --format table

Shell Integration

jq Compatibility

Perfect integration with jq for data processing:

# Extract task IDs
juno-kanban list | jq -r '.id'

# Filter by specific criteria
juno-kanban list | jq 'select(.status == "todo")'

# Count tasks by status
juno-kanban list | jq -r '.status' | sort | uniq -c

# Get tasks with specific tags
juno-kanban list | jq 'select(.feature_tags[]? == "backend")'

# Clean data output (suppress summary)
juno-kanban list 2>/dev/null | jq '.'

Automation Examples

# Daily standup - get your current work
juno-kanban search --status in_progress | jq -r '.body'

# Review completed work with commits
juno-kanban search --status done | jq -r '"✅ \(.body) (\(.commit_hash // "no commit"))"'

# Find urgent tasks
juno-kanban search --tags urgent | jq -r '"⚠️  \(.body)"'

# Git hook integration
git log -1 --format="%H" | xargs -I {} juno-kanban search --commit {}

Configuration

Configuration file: .juno_task/tasks/config.json

Status Workflow

{
  "status_values": ["backlog", "todo", "in_progress", "review", "done", "archive"],
  "default_status": "backlog",
  "enforce_transitions": true,
  "allowed_transitions": {
    "backlog": ["todo", "archive"],
    "todo": ["in_progress", "archive"],
    "in_progress": ["review", "done", "archive"],
    "review": ["todo", "done", "archive"],
    "done": ["archive"],
    "archive": []
  }
}

Tag Validation

{
  "tag_pattern": "^[a-zA-Z0-9_-]+$",
  "max_tags_per_task": 10,
  "allowed_tags": ["frontend", "backend", "security", "urgent", "bug", "feature"]
}

Search Settings

{
  "storage_file_pattern": "*.ndjson",
  "storage_base_path": ".juno_task/tasks",
  "default_limit": 5,
  "enable_ripgrep": true
}

Task Schema

Each task is stored as a JSON object with these fields:

Field	Type	Description
id	string	6-character alphanumeric ID (e.g., "A1b2C3")
status	string	Current status (configurable workflow)
body	string	Task description (supports multiline, code, HTML)
commit_hash	string|null	Git commit hash when completed
agent_response	string	AI/human response or notes
created_date	string	Creation timestamp (YYYY-MM-DD HH:MM:SS)
last_modified	string	Last modification timestamp
feature_tags	string[]	Categorization tags
blocked_by	string[]|null	Task IDs that must complete before this task
related_tasks	string[]|null	Non-blocking task references

Example Task

{
  "id": "A1b2C3",
  "status": "done",
  "body": "Implement OAuth2 authentication flow\n\n```python\[e-mail]('/auth')\ndef authenticate():\n    return oauth.redirect()\n```",
  "commit_hash": "abc123def456",
  "agent_response": "Implemented OAuth2 with Google provider. Added tests and documentation.",
  "created_date": "2025-10-22 14:30:00",
  "last_modified": "2025-10-22 16:45:30",
  "feature_tags": ["backend", "security", "oauth"],
  "blocked_by": ["X4y5Z6"],
  "related_tasks": ["D7e8F9"]
}

Error Handling

Educational Error Messages

# Invalid tag format
juno-kanban create "Task" --tags "frontend v1"

Validation error: Invalid tag format: 'frontend v1'

Tags can only contain letters, numbers, underscores (_), and hyphens (-).
Found: spaces (not allowed)

Correct format examples:
  --tags backend urgent fix-auth
  --tags frontend_v1 initial feature

Did you mean: 'frontend_v1'?

Status Transition Validation

# Invalid status transition
juno-kanban update ABC123 --status done  # (current: backlog)

Cannot transition from 'backlog' to 'done'.
Allowed transitions from 'backlog': todo, in_progress, archive

Use: juno-kanban update ABC123 --status todo

Performance

Benchmarks

Operation	Small (100 tasks)	Large (10,000 tasks)	Notes
Create task	~5ms	~5ms	Constant time
Search by ID	~10ms	~15ms	With ripgrep
Search by status	~20ms	~50ms	With ripgrep
List recent	~25ms	~100ms	Sorted by timestamp

Large File Handling

• Streaming: Memory-efficient reading of large files
• Ripgrep: 10-50x performance boost for search operations
• Split Files: Automatic discovery across multiple NDJSON files
• Indexing: Fast ID lookups even with thousands of tasks

Examples

Development Workflow

# Morning planning
juno-kanban create "Review pull requests" --tags review daily
juno-kanban create "Fix authentication bug" --tags backend urgent --status todo

# Start working
juno-kanban mark in_progress -ID ABC123 --response "Investigating auth issue"

# During development
juno-kanban update ABC123 --response "Found root cause in JWT validation"

# Complete work
juno-kanban mark done -ID ABC123 --response "Fixed JWT expiry handling" --commit abc123

# End of day review
juno-kanban search --status done | jq -r '"✅ \(.body)"'

Dependency-Aware Workflow

# Create a pipeline with dependencies
juno-kanban create "Write unit tests" --tags backend testing --status todo
# Returns ID: A1b2C3

juno-kanban create "Implement feature" --blocked-by A1b2C3 --tags backend
# Returns ID: D4e5F6

juno-kanban create "Deploy to staging" --blocked-by D4e5F6 --tags devops
# Returns ID: G7h8I9

# See what's ready to work on
juno-kanban ready --sort desc
# Only A1b2C3 shows — the others are blocked (newest ready tasks first)

# Get execution order with priority scores
juno-kanban order --scores
# A1b2C3 (score: 2) → D4e5F6 (score: 1) → G7h8I9 (score: 0)

# Complete first task, check what's unblocked
juno-kanban mark done -ID A1b2C3 --response "Tests written" --commit abc123
juno-kanban ready --sort asc
# Now D4e5F6 is ready (and asc sort keeps oldest ready tasks first)

Team Coordination

# See what teammates are working on
juno-kanban search --status in_progress | jq -r '"👤 \(.body) - \(.agent_response)"'

# Find tasks needing review
juno-kanban search --status review --tags urgent

# Weekly retrospective
juno-kanban search --status done | jq 'group_by(.commit_hash) | length'

Git Integration

# Link completed tasks to commits
git log --oneline | head -5 | while read commit message; do
  echo "🔗 $commit: $(juno-kanban search --commit $commit | jq -r '.body // "No task linked"')"
done

# Pre-commit hook: ensure task exists
if ! juno-kanban search --status in_progress | grep -q "$(git log -1 --format='%s')"; then
  echo "⚠️  No in-progress task found for this commit"
fi

Troubleshooting

Common Issues

Command not found after installation:

# Ensure pip installed to correct environment
which pip
pip show juno-kanban

# Try reinstalling
pip install -e . --force-reinstall

Slow search performance:

# Install ripgrep for better performance
brew install ripgrep  # macOS
apt install ripgrep   # Ubuntu/Debian

jq parsing errors:

# Ensure you're using recent version (v1.3.0+)
juno-kanban --version

# Use stderr redirection if needed
juno-kanban list 2>/dev/null | jq '.'

Configuration issues:

# Check config file location
ls -la .juno_task/tasks/config.json

# Validate JSON syntax
cat .juno_task/tasks/config.json | jq '.'

Getting Help

• CLI Help: juno-kanban --help or juno-kanban COMMAND --help
• Issues: GitHub Issues
• Examples: See .juno_task/specs/ directory for detailed examples

Contributing

This project is developed using AI-powered workflows with juno-task. To contribute:

1. Check .juno_task/USER_FEEDBACK.md for current issues
2. Use juno-task feedback to report bugs or suggestions
3. Review .juno_task/plan.md for development priorities

License

MIT License - see LICENSE file for details.

Changelog

v1.32.0 (2026-03-22)

• Added tags command for tag-level workload aggregation (juno-kanban tags) with --status filtering and output formats (json, table, xml, ndjson)
• Added explicit status-order contract for list and ready when --status is provided (e.g. --status backlog,in_progress preserves that group order)
• Added ready --status ... filter support to match list/search filtering workflows
• Added list/search parity summaries to ready (Displayed: X of Y + status breakdown; JSON summary object for --format json)
• Added shared deterministic sort helpers so list, search, and ready all follow one --sort asc|desc contract with stable ID tie-breaks

v1.31.0 (2026-03-21)

• Added search --sort asc|desc to control last_modified ordering in both ripgrep and Python fallback paths
• Added command-level search --format ... support (in addition to global --format) and list-like result summaries for search output
• Added multi-ID retrieval for get / show (juno-kanban get ID1 ID2 ...) with ordered JSON output
• Added native shell completion generator (juno-kanban completion [bash|zsh|fish]) with parser-driven command/option completions

v1.30.0 (2026-03-20)

• Added ## related-task markup parsing (##ID, ## ID, ## ID1 ID2 ##) alongside [task_id]...[/task_id]
• Preserved forward related-task references for valid-but-not-yet-existing IDs (with warning instead of silent drop)
• Hardened local development wrapper resolution so kanban.sh prefers working-tree src/ over stale site-packages
• Hardened scripts/bump_version.py to use max(local, PyPI) as baseline and avoid accidental version rollback bumps

v1.29.0 (2026-03-04)

• Added flexible task ID handling across key commands (get, update, archive, mark, deps)
  • Supports positional TASK_ID and flag form (--id / --ID)
• Added deps shorthand mode:
  • deps --id TASK_ID --blocked-by ID... defaults to add
  • deps --id TASK_ID defaults to dependency info (show)
• Improved create parser resilience for agent workflows:
  • trailing quoted body recovery after list flags like --related-tasks / --blocked-by
  • maintained strict validation for true no-body cases

v1.28.0 (2026-03-03)

• Added create --title support (title:{title}\n\n{body} merge format)
• Added support for title-only task creation

v1.27.0 (2026-03-03)

• Added --id/--ID task selection support for get/show
• Expanded integration test coverage for ID parsing and create flows

v1.26.0 (2026-02-19)

• Added task dependency system with blocked_by field and body markup parsing
• Added deps command for querying/managing task dependencies
• Added ready command for finding unblocked tasks (parallel execution support)
• Added order command for topological sort of open tasks
• Added dependency graph engine with cycle detection, priority scoring, and critical path analysis
• Added merge command for combining task databases across directories
• Added related_tasks field for non-blocking task references
• Enhanced get command with dependency info and related task details
• 350+ tests (pytest), 9 Python modules

v1.25.0 (2026-02-18)

• Migrated to juno-mono monorepo
• Added comprehensive pytest test suite (210 tests, 46% coverage)
• Cleaned git bloat (removed dist/, .venv_juno/, stale files)
• Updated all repository references from feedback-shell to juno-mono
• Fixed Python version badge and requirements to 3.8+

v1.3.0 (2025-10-23)

• 🔧 Fixed jq compatibility by redirecting summary to stderr
• 📝 Compacted documentation for better token efficiency
• ✅ All automation workflows now function correctly

v1.2.0 (2025-10-22)

• 📦 Added pip installation with dual entry points
• 🔧 Fixed empty search results messaging
• 📚 Consistent help across command names

v1.1.0 (2025-10-22)

• 🗃️ Replaced delete with archive (data preservation)
• ⚡ Added mark command for streamlined workflow
• 📅 Simplified datetime format

v1.0.1 (2025-10-22)

• ➕ Added missing CRUD operations
• 📖 Improved help text and documentation
• 🏷️ Enhanced tag validation with educational errors

v1.0.0 (2025-10-22)

• 🎉 Initial release with full kanban functionality
• 🔍 High-performance search with ripgrep
• 🏷️ Flexible tagging and status workflows

---

Built with ❤️ for developers who live in the terminal