jots

Hierarchical task management for AI coding agents and humans.

Epic → Task → Subtask

Jots provides a simple CLI and library for managing work in a three-level hierarchy. Designed with AI agents in mind—commands like next and context give agents exactly what they need to stay on track.

Installation

npm install -g jots-ai

Quick Start

# Initialize in your project
jots init

# Add an epic (large initiative)
jots add epic "Build user authentication system" -p p1

# Add a task to the epic
jots add task "Implement JWT token validation" -e auth

# Add a subtask
jots add subtask "Write token expiry check" -e auth -t jwt

# Get the next thing to work on
jots next

# Mark it done when complete
jots done <id>

Commands

| Command | Description | |---------|-------------| | jots init | Initialize jots.json in current directory | | jots add <type> <content> | Add epic, task, or subtask | | jots list [type] | List items (epics, tasks, subtasks, all) | | jots next | Get highest-priority actionable item | | jots context | Get full state summary (for AI agents) | | jots done <id> | Mark item as completed | | jots remove <id> | Remove item (and its children) | | jots update <id> | Modify content, priority, or status | | jots validate | Check for schema and consistency issues |

All commands support --json for programmatic use.

For AI Agents

Jots is designed for AI coding assistants. Two commands are particularly useful:

jots next - Returns the single highest-priority item ready to work on:

$ jots next
Next: Write token expiry check [abc123]
  Priority: p1 | Status: pending
  Epic: Build user authentication system
  Task: Implement JWT token validation
  Queue: 3 pending, 1 in progress

jots context - Returns a structured summary of all work:

$ jots context --json
{
  "progress": { "epics": "1/3", "tasks": "4/12", "subtasks": "8/20" },
  "in_progress": [...],
  "blocked": [...],
  "next": {...}
}

Data Storage

Tasks are stored in jots.json—a human-readable file you can edit directly or commit to version control.

Documentation

• CLI Reference - Full command documentation
• API Reference - Library exports for programmatic use
• Data Model - Schema specification
• AI Integration - Claude Code hooks and agent workflows
• Workflows - Best practices and patterns

License

MIT