Goal-oriented development framework for Claude Code - transform CLI agents into autonomous project partners
npm install claude-northstar> 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)
$3
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
Installation
$3
bash
npx claude-northstar init
`$3
bash
Check status
npx claude-northstar statusUninstall
npx claude-northstar uninstall
`$3
bash
curl -fsSL https://raw.githubusercontent.com/nisarg38/claude-northstar/main/install.sh | bash
`Quick Start
1. Install North Star in your project (see above)
2. 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.
3. North Star will:
- Capture your vision in
- Analyze your codebase
- Propose milestones
- Start working autonomously4. Resume anytime by saying
How It Works
$3
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
$3
| 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 |
$3
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ ANALYZE │ ──▶ │ PLAN │ ──▶ │ EXECUTE │ ──▶ │ EVALUATE│
│ state │ │ next │ │ work │ │ progress│
└─────────┘ └─────────┘ └─────────┘ └─────────┘
▲ │
└───────────────────────────────────────────────┘
North Star Files
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
$3
The vision document. Define what you're building and what success looks like:
markdown
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 UIConstraints
- iOS 17+ only
- SwiftUI preferred
`$3
Tracks progress across sessions:
json
{
"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"]
}
`Key Behaviors
| Behavior | Description |
|----------|-------------|
| Goal-Oriented | Refers to
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 |When North Star Asks You
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
Recommended Setup
$3
For better workspace isolation during parallel work:
`bash
Install jj
brew install jjInitialize in your repo
jj git init --colocate
`North Star works with plain git, but jj enables:
- Isolated workspaces for parallel tasks
- Conflicts as data (operations never fail)
- Easy rollback via operation log
$3
North Star adds a section to your
(or creates one) explaining how to use it. This gives Claude Code the context it needs.Examples
$3
`
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?"
$3
You: "continue"North Star: "Last session: Completed M1 (dotfile linking).
Current: M2 (git sync) at 40%.
Continuing with git sync integration..."
$3
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..."
Uninstalling
bash
rm -rf .claude/harness
Optionally remove the North Star section from CLAUDE.md
``Contributions 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.