Transform CLI agents from task executors into autonomous project partners
Claude North Star is a goal-oriented development framework for CLI agents like Claude Code and OpenCode. Instead of giving your AI agent task after task, you share a vision and it works autonomously toward it.
You: "Create the user model"
Agent: "Done. What's next?"
You: "Add authentication"
Agent: "Done. What's next?"
You: "Write tests"
... (repeat forever)
You: "I want to build a fitness app with workout tracking and Watch sync"
North Star: Plans milestones → Works autonomously → Reports progress → Asks strategic questions only
npx claude-northstar init# Check status
npx claude-northstar status
# Uninstall
npx claude-northstar uninstallcurl -fsSL https://raw.githubusercontent.com/nisarg38/claude-northstar/main/install.sh | bash-
Install North Star in your project (see above)
-
Start Claude Code and share your vision:
I want to build a fitness app with workout tracking. Success looks like: users can log workouts on their phone and see progress over time. -
North Star will:
- Capture your vision in
north-star.md - Analyze your codebase
- Propose milestones
- Start working autonomously
- Capture your vision in
-
Resume anytime by saying
continue
The Claude Code session acts as a Tech Lead that:
- Understands your vision
- Plans milestones and priorities
- Coordinates a team of sub-agents
- Reports meaningful progress
- Asks only strategic questions
| Role | Purpose | When Used |
|---|---|---|
| Product Researcher | Market research, competitors | Early planning |
| Strategist | Architecture decisions | Technical crossroads |
| Developer | Implementation | Building features |
| QA | Testing, verification | After implementation |
| Reviewer | Code review | Before merging |
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ ANALYZE │ ──▶ │ PLAN │ ──▶ │ EXECUTE │ ──▶ │ EVALUATE│
│ state │ │ next │ │ work │ │ progress│
└─────────┘ └─────────┘ └─────────┘ └─────────┘
▲ │
└───────────────────────────────────────────────┘
After installation, you'll have:
.claude/harness/
├── north-star.md # Your project vision (THE source of truth)
├── project-state.json # Current state, milestones, progress
├── decisions.md # Architecture decisions log
├── progress-log.md # Session-by-session progress
└── prompts/ # Sub-agent prompt templates
├── product-researcher.md
├── strategist.md
├── developer.md
├── qa.md
└── reviewer.md
The vision document. Define what you're building and what success looks like:
# Project North Star
## Vision
Build a fitness app with workout tracking and Apple Watch sync.
## Success Criteria
- [ ] User can log workouts on iPhone
- [ ] Workouts sync to Apple Watch
- [ ] Clean, intuitive UI
## Constraints
- iOS 17+ only
- SwiftUI preferredTracks progress across sessions:
{
"milestones": [
{"id": "m1", "title": "Core models", "status": "done"},
{"id": "m2", "title": "Workout UI", "status": "in_progress", "progress": 0.6}
],
"currentFocus": "m2",
"gaps": ["Missing HealthKit integration"]
}| Behavior | Description |
|---|---|
| Goal-Oriented | Refers to north-star.md constantly |
| Self-Directing | Figures out what to do, doesn't wait for tasks |
| Progress Tracking | Tracks milestones, not individual tasks |
| Strategic Questions | Asks only for major decisions |
| Session Continuity | State persists, say "continue" to resume |
| Quality Pipeline | Dev → QA → Review → Merge |
North Star will only interrupt for:
- Major architecture decisions: "Should we use PostgreSQL or SQLite?"
- Ambiguous requirements: "Should workout history be editable?"
- Milestone reviews: "Milestone 1 complete. Here's what I built. Review?"
It will NOT ask for:
- Every task completion
- Minor implementation choices
- Routine progress updates
For better workspace isolation during parallel work:
# Install jj
brew install jj
# Initialize in your repo
jj git init --colocateNorth Star works with plain git, but jj enables:
- Isolated workspaces for parallel tasks
- Conflicts as data (operations never fail)
- Easy rollback via operation log
North Star adds a section to your CLAUDE.md (or creates one) explaining how to use it. This gives Claude Code the context it needs.
You: "I want to build a CLI tool for managing dotfiles.
It should support multiple machines, git sync, and templating."
North Star: "I'll capture this vision. Here's my proposed milestone plan:
M1: Core dotfile linking
M2: Git sync integration
M3: Multi-machine profiles
M4: Template system
Does this align with your vision?"
You: "Yes, start with M1"
North Star: [Works for 30 minutes]
"M1 complete. Created symlink manager with conflict detection.
Tests passing. Ready for M2?"
You: "continue"
North Star: "Last session: Completed M1 (dotfile linking).
Current: M2 (git sync) at 40%.
Continuing with git sync integration..."
North Star: "For git sync, I can either:
A) Use libgit2 - faster, but adds dependency
B) Shell out to git - simpler, requires git installed
Given your goal of easy installation, which approach?"
You: "B, keep it simple"
North Star: "Noted in decisions.md. Continuing..."
rm -rf .claude/harness
# Optionally remove the North Star section from CLAUDE.mdContributions welcome! Areas of interest:
- More sub-agent prompts (security auditor, documentation writer)
- Better milestone planning heuristics
- Integration with more CLI agents
- Headless mode for extended operation
MIT
North Star thinks about what to do, not just does what it's told.