threads-cli

A conversational thread tracker for managing streams of activity through self-reported progress. Unlike traditional task managers, Threads tracks momentum and context rather than deadlines.

Installation

npm install -g threads-cli

Requires Node.js 20 or later.

Quick Start

# Create a new thread
threads new "API refactoring" -d "Modernize REST endpoints" -t hot -i 4

# List active threads
threads list --active

# Add progress to a thread
threads progress "API refactoring" "Completed authentication endpoints"

# View a specific thread
threads show "API refactoring"

Core Concepts

• Thread: A stream of activity with status, temperature (momentum), size (scope), and importance
• Progress: Timestamped notes you report to yourself about a thread
• Temperature: Indicates momentum (frozen, freezing, cold, tepid, warm, hot)
• Sub-threads: Threads can spawn children for breaking down work
• Groups: Organizational containers for related threads
• Dependencies: Links between threads with why/what/how/when context

Commands

Thread Management

threads new <name>              # Create a new thread
threads show <name>             # Display thread details
threads set <name> <property>   # Update thread properties
threads spawn <parent> <child>  # Create sub-thread
threads archive <name>          # Archive a thread
threads clone <name>            # Duplicate a thread
threads merge <source> <target> # Merge threads

Progress Tracking

threads progress <name> <note>  # Add progress entry
threads move-progress <s> <t>   # Move progress between threads
threads timeline         # View progress timeline
threads undo                    # Restore from backup

Listing and Filtering

threads list                    # List all threads (tree view)
threads list --active           # Show only active threads
threads list --hot              # Show hot threads
threads list -g <group>         # Filter by group
threads list --tag <tag>        # Filter by tag
threads list --flat             # Flat list instead of tree
threads search <query>          # Search threads

Organization

threads group new <name>        # Create a group
threads group add <thread> <g>  # Add thread to group
threads tag add <name> <tags>   # Add tags to thread
threads depend <from> <to>      # Create dependency

Views

threads overview                # High-level summary
threads agenda                  # Prioritized view
threads next                    # Suggest next thread to work on
threads details <name>          # View/manage detail snapshots

Batch Operations

threads batch set status=paused "Thread1" "Thread2"
threads batch tag add urgent "Thread1" "Thread2"

Thread Properties

Property	Values
status	active, paused, stopped, completed, archived
temperature	frozen, freezing, cold, tepid, warm, hot
size	tiny, small, medium, large, huge
importance	1-5

Data Storage

Data is stored locally at ~/.threads/threads.json. This file is managed entirely by the CLI.

Development

git clone https://github.com/joshuaramirez/threads-cli.git
cd threads-cli
npm install
npm run build
npm link  # Install locally for testing

Scripts

npm run build      # Compile TypeScript
npm run dev        # Run directly via tsx
npm test           # Run tests
npm run typecheck  # Type checking only

License

MIT