https://github.com/nisarg38/claude-northstar
Transform CLI agents from task executors into autonomous project partners. Share your vision, not your todo list.
https://github.com/nisarg38/claude-northstar
claude-code cli-agents
Last synced: 5 months ago
JSON representation
Transform CLI agents from task executors into autonomous project partners. Share your vision, not your todo list.
- Host: GitHub
- URL: https://github.com/nisarg38/claude-northstar
- Owner: Nisarg38
- License: mit
- Created: 2026-01-06T17:32:26.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-06T17:43:06.000Z (5 months ago)
- Last Synced: 2026-01-12T12:39:37.750Z (5 months ago)
- Topics: claude-code, cli-agents
- Language: Shell
- Homepage:
- Size: 28.3 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Claude North Star
> Transform CLI agents from task executors into autonomous project partners
[](https://www.npmjs.com/package/claude-northstar)
[](https://opensource.org/licenses/MIT)
## What is this?
**Claude North Star** is a goal-oriented development framework for CLI agents like [Claude Code](https://docs.anthropic.com/en/docs/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)
```bash
npx claude-northstar init
```
### Other options
```bash
# Check status
npx claude-northstar status
# Uninstall
npx claude-northstar uninstall
```
### Alternative: curl
```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 `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:
```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 UI
## Constraints
- iOS 17+ only
- SwiftUI preferred
```
### project-state.json
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 `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:
```bash
# 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
```bash
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.*