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.