Fast, deterministic CLI tool for spec workflow management.
Note: This tool will be published to the NPM registry when it reaches a more mature state. For now, install directly from GitHub.
spx scans your project's specs/ directory and provides instant status analysis of work items (capabilities, features, stories). It replaces slow, token-expensive LLM-based status checks with deterministic filesystem operations completing in under 100ms.
- Fast: Scan entire spec tree in <100ms vs 1-2 minutes with LLM
- Deterministic: Reliable DONE/IN PROGRESS/OPEN classification
- Zero token cost: No LLM calls for status checks
- Multiple formats: Text, JSON, Markdown, Table output
# Clone and install
git clone https://github.com/simonheimlicher/spx-cli.git
cd spx-cli
npm install
npm run build
npm link # Makes 'spx' available globally# Will be available when published
npm install -g spx# Get project status
spx status
# Get status as JSON (for scripts/agents)
spx status --json
# Choose output format
spx status --format markdown
spx status --format table
# Find next work item to work on
spx next$ spx status
capability-21_core-cli [IN PROGRESS]
├── feature-21_pattern-matching [DONE]
│ ├── story-21_parse-capability-names [DONE]
│ ├── story-32_parse-feature-names [DONE]
│ └── story-43_parse-story-names [DONE]
├── feature-32_directory-walking [IN PROGRESS]
│ ├── story-21_recursive-walk [DONE]
│ └── story-32_pattern-filter [OPEN]
└── feature-43_status-determination [OPEN]
Status is computed deterministically from the tests/ directory:
| Condition | Status |
|---|---|
No tests/ directory or empty |
OPEN |
tests/ has files but no DONE.md |
IN PROGRESS |
tests/DONE.md exists |
DONE |
Manage work sessions for agent handoffs and task queuing:
# Create a handoff session (reads content with frontmatter from stdin)
cat << 'EOF' | spx session handoff
---
priority: high
---
# Implement feature X
EOF
# Output:
# Created handoff session <HANDOFF_ID>2026-01-15_08-30-00</HANDOFF_ID>
# <SESSION_FILE>/path/to/.spx/sessions/todo/2026-01-15_08-30-00.md</SESSION_FILE>
# Or create empty session and edit the file directly
spx session handoff
# Then edit the <SESSION_FILE> path returned
# List all sessions
spx session list
# Claim the highest priority session
spx session pickup --auto
# Output: Claimed session <PICKUP_ID>2026-01-15_08-30-00</PICKUP_ID>
# Release session back to queue
spx session release
# Show session content
spx session show <session-id>
# Delete a session
spx session delete <session-id>Sessions are stored in .spx/sessions/ with priority-based ordering (high → medium → low) and FIFO within the same priority. Commands output parseable <PICKUP_ID>, <HANDOFF_ID>, and <SESSION_FILE> tags for automation.
See Session Recipes for detailed usage patterns.
spx expects work items in specs/doing/ following this pattern:
specs/doing/
└── capability-NN_{slug}/
├── {slug}.capability.md
└── feature-NN_{slug}/
├── {slug}.feature.md
└── story-NN_{slug}/
├── {slug}.story.md
└── tests/
└── DONE.md # Present when complete
Numbers use BSP (Binary Space Partitioning) for easy insertion: start with 21, 32, 43... and insert between existing items.
# Install dependencies
npm ci
# Run tests
npm test
# Run validation (required before commits)
npm run validate
# Build
npm run build
# Run locally
node bin/spx.js status- TypeScript - Type-safe implementation
- Commander.js - CLI framework
- Vitest - Testing framework
- tsup - Build tool
- ESLint 9 - Linting with flat config
src/
├── scanner/ # Directory walking, pattern matching
├── status/ # DONE/IN PROGRESS/OPEN state machine
├── reporter/ # Output formatting (text, json, md, table)
├── tree/ # Hierarchical tree building
└── commands/ # CLI command implementations
MIT