CLI companion for GitHub Spec Kit - track progress on spec-driven development tasks
npm install speckit-status




A CLI companion for GitHub's Spec Kit that visualizes and tracks progress on spec-driven development tasks.
---
When working with AI coding agents using the Spec-Driven Development workflow, Spec Kit generates tasks.md files containing phased implementation plans. This CLI tool parses those files to give you:
- Progress tracking with visual progress bars
- Phase status at a glance with completion counts
- Dependency awareness showing which phases are blocked or available
- Smart suggestions for what to work on next
- JSON export for CI/CD pipelines and automation
- Parses Spec Kit's tasks.md format (phases, task IDs, checkboxes)
- Understands [P] parallel markers and phase dependencies
- Auto-detects spec folder from git branch name
- Beautiful colored terminal output
- Machine-readable JSON output
- Zero runtime dependencies
- Works as both CLI and Node.js library
``bashnpm
npm install -g speckit-status
Quick Start
`bash
In a project with specs/ directory and matching git branch
speckit-statusOr specify the spec folder directly
speckit-status -s ./specs/001-my-feature
`Usage
`
speckit-status [OPTIONS]OPTIONS:
-s, --spec-folder Override spec folder (instead of git branch detection)
-j, --json Output as JSON
-a, --all Show all tasks (including completed)
-p, --phase Show only specific phase
-n, --next Output only next phase number (for scripts)
-h, --help Show help message
-v, --version Show version
`$3
`bash
Auto-detect spec from git branch name
speckit-statusShow specific phase details
speckit-status -p 2Export progress as JSON
speckit-status -j > progress.jsonGet next phase number for scripting
NEXT=$(speckit-status -n)
echo "Next phase: $NEXT"Show all tasks including completed ones
speckit-status -a -p 1
`Integration with Spec Kit
This tool is designed to work with GitHub's Spec Kit workflow:
`
/speckit.specify → spec.md
/speckit.plan → plan.md
/speckit.tasks → tasks.md ← parsed by this CLI
/speckit.implement
`$3
Spec Kit creates specs in a structured directory:
`
specs/
└── 001-my-feature/
├── spec.md
├── plan.md
├── tasks.md # This is what gets parsed
└── ...
`$3
The CLI auto-detects the spec folder from your git branch name:
- Branch
001-my-feature → looks for specs/001-my-feature/
- Branch feature/001-my-feature → extracts 001-my-featureProgrammatic Usage
Use as a library in your Node.js projects:
`typescript
import {
parseTasksFile,
formatOutput,
formatJSON,
getCurrentBranch,
getSpecFolderFromBranch,
} from 'speckit-status';
import { readFileSync } from 'fs';// Parse a tasks.md file
const content = readFileSync('./specs/001-feature/tasks.md', 'utf-8');
const result = parseTasksFile(content, './specs/001-feature');
console.log(
Progress: ${result.completedTasks}/${result.totalTasks});
console.log(Next phase: ${result.nextPhase?.number});
console.log(Available phases: ${result.availablePhases.map(p => p.number).join(', ')});// Access phase details
for (const phase of result.phases) {
console.log(
Phase ${phase.number}: ${phase.title});
console.log( Tasks: ${phase.completedCount}/${phase.totalCount});
console.log( Complete: ${phase.isComplete}); if (phase.dependency) {
console.log(
Depends on: ${phase.dependency.dependsOn.join(', ')});
console.log( Blocks: ${phase.dependency.blocks.join(', ')});
}
}
`$3
`typescript
interface Task {
id: string; // T001, T002, etc.
completed: boolean;
title: string;
}interface Phase {
number: number;
title: string;
priority?: string; // P1, P2, etc.
tasks: Task[];
completedCount: number;
totalCount: number;
isComplete: boolean;
dependency?: PhaseDependency;
}
interface PhaseDependency {
shortName: string;
dependsOn: number[];
blocks: number[];
canRunParallelWith: number[];
parallelTasks: string[];
description: string;
}
interface ParseResult {
specFolder: string;
specName: string;
phases: Phase[];
totalTasks: number;
completedTasks: number;
nextPhase?: Phase;
availablePhases: Phase[];
}
`AI-Assisted Development
This project embraces the future. I welcome pull requests whether you wrote every line by hand, pair-programmed with an AI, or let Claude/GPT/Copilot do the heavy lifting while you sipped coffee.
The deal is simple:
- You hit the submit button, you own the code
- Review what you're submitting like it's going to production (because it is)
- Tests pass? Types check? Linting clean? Ship it
- If it breaks, it's on you - not your AI buddy
I don't gatekeep how code gets written. I care that it works, it's readable, and it doesn't break things. The future of development is hybrid - let's build it together.
Contributing
Contributions are welcome! Please read our Contributing Guide for details on how to submit pull requests, report issues, and contribute to the project.
$3
`bash
Install dependencies
npm installBuild
npm run buildRun type checking
npm run typecheckRun linting
npm run lintTest locally
./dist/cli.js --help
``See CHANGELOG.md for a list of changes and version history.
MIT License - see the LICENSE file for details.
---
Built for the Spec-Driven Development workflow.