Claude North Star

Transform CLI agents from task executors into autonomous project partners

What is this?

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.

Before (Task-Based)

You: "Create the user model"
Agent: "Done. What's next?"
You: "Add authentication"
Agent: "Done. What's next?"
You: "Write tests"
... (repeat forever)

After (Goal-Oriented)

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

One command (recommended)

npx claude-northstar init

Other options

# Check status
npx claude-northstar status

# Uninstall
npx claude-northstar uninstall

Alternative: curl

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 north-star.md
   • Analyze your codebase
   • Propose milestones
   • Start working autonomously

4. Resume anytime by saying continue

How It Works

The Main Agent as Tech Lead

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

The Team (Sub-Agents)

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

The Autonomous Work Loop

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│ 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

north-star.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 preferred

project-state.json

Tracks 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"]
}

Key Behaviors

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

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

With Jujutsu (jj)

For better workspace isolation during parallel work:

# Install jj
brew install jj

# Initialize 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

CLAUDE.md

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.

Examples

Starting a New Project

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?"

Resuming Work

You: "continue"

North Star: "Last session: Completed M1 (dotfile linking).
         Current: M2 (git sync) at 40%.
         Continuing with git sync integration..."

Strategic Question

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

rm -rf .claude/harness
# Optionally remove the North Star section from CLAUDE.md

Contributing

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

License

MIT

---

North Star thinks about what to do, not just does what it's told.