🤖 Noru

Ship while you sleep — autonomous Claude Code orchestration

Get the most out of your Claude Max subscription. Paying for Max5 or Max20 but only using Claude a few hours a day? Noru runs Claude Code autonomously when you're away — executing tasks, reviewing code for security issues, finding bugs, and more. Your tokens work while you don't.

▶️ Watch the demo (2 min)

• 📑 Table of Contents
• ✨ Features
• 🚀 Quick Start
  • 1. Install
  • 2. Initialize a project
  • 3. Start the orchestrator
  • Adding tasks manually
• 📊 Dashboard
  • Tabs
• ⚙️ Configuration
  • 🛡️ Guardrails
  • 🔍 Idle Review Jobs (16 built-in)
• 🔧 CLI Reference
  • Lifecycle
  • Task Management
  • Project Management
  • Configuration
  • Idle Reviews
  • Direct Execution
• 🔔 Integrations
  • Telegram
  • Slack
  • Discord
• 🌐 Tunnel (Remote Access)
• 📡 API Reference
• 🏗️ Architecture
  • Project Structure
  • Tech Stack
• 🤝 Contributing
• 📄 License

Prerequisites: Claude Code CLI and tmux installed.

# macOS
brew install tmux

pip install noru

cd ~/your-project
noru init

💡 Tip: noru init scans your project and suggests initial tasks based on TODOs, open issues, and code quality signals.

noru start

That's it. Noru is now running tasks and serving the dashboard at http://localhost:7777.

# Open the dashboard in your browser
noru dashboard

# Check what's happening
noru status

# Add a task
noru task add --project my-app --title "Fix authentication bug" --priority 1

# Promote it to the queue
noru task ready 1

# Watch it get picked up automatically
noru status

Noru ships with a single-file HTML dashboard — no build step, no node_modules. Just open http://localhost:7777.

📱 Mobile friendly. The dashboard is fully responsive — check on your tasks from your phone while you're out.

Full reference: docs/configuration.md

Config lives at ~/.noru/config.yaml. Created automatically on first run, or customize it:

# Core settings
loop_interval_seconds: 60
port: 7777
claude_cli: claude

# Token budget — 5-hour rolling window
max20_window_tokens: 220000
window_duration_hours: 5

# Weekly budget
weekly:
  seed_limit: 1500000
  developer_reserve_pct: 0.35    # 35% reserved for your interactive sessions
  reset_day: monday

# Guardrails — injected into all prompts
guardrails:
  - "NEVER change database schema or migrations"
  - "NEVER re-architect the project layout"

# Watermark refill — trigger idle scans when ready tasks drop below threshold
watermark:
  low_watermark: 2
  scan_cooldown_seconds: 60

# Idle review jobs (run when ready tasks < watermark)
idle_jobs:
  max_tasks_per_run: 3
  jobs:
    - id: security-scan
      enabled: true
    - id: bug-detection
      enabled: true
    - id: test-coverage
      enabled: true
    # ... see full list below

💡 Tip: You can also edit configuration from the dashboard's admin panel.

User-defined rules injected into every prompt noru sends to Claude Code. Use them to set hard boundaries on what noru is allowed to do:

guardrails:
  - "NEVER change database schema or migrations"
  - "NEVER re-architect the project layout"
  - "NEVER modify CI/CD pipelines"

When ready tasks drop below the watermark threshold, noru triggers a scan that creates review tasks automatically. This is stateless — no phases, no state machine. Just: ready_tasks < low_watermark triggers a scan, then cooldown.

# Enable/disable review jobs
noru idle enable perf-audit
noru idle disable docs-update
noru idle list

Full reference: docs/integrations.md

Noru supports event hooks for notifications when tasks complete, fail, or when the queue empties.

# ~/.noru/config.yaml
hooks:
  telegram:
    enabled: true
    bot_token: "your-bot-token"
    chat_id: "your-chat-id"
    events: [task_completed, task_failed, queue_empty]

hooks:
  slack:
    enabled: true
    webhook_url: "https://hooks.slack.com/services/..."
    events: [task_completed, task_failed]

hooks:
  discord:
    enabled: true
    webhook_url: "https://discord.com/api/webhooks/..."
    events: [task_completed, task_failed]

💡 Tip: You can combine multiple integrations. All hooks fire independently.

Full reference: docs/tunnel.md

Access your dashboard from anywhere — no port forwarding required.

# Start a tunnel (auto-detects cloudflared or ngrok)
noru tunnel start

# Displays a public URL + QR code for mobile access
# Example: https://abc123.trycloudflare.com

⚠️ Warning: The tunnel exposes your dashboard to the internet. Use it on trusted networks or add authentication.

Full reference: docs/api.md

Noru exposes a full REST API at http://localhost:7777/api. Everything the dashboard does, your scripts can do too.

Key endpoints:

# Example: list tasks via curl
curl http://localhost:7777/api/tasks | python3 -m json.tool

# Example: add a task via API
curl -X POST http://localhost:7777/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"project_id": "my-app", "title": "Fix login bug", "priority": 1}'

noru start
  └── Python process (single PID)
       ├── Main thread: uvicorn (FastAPI on :7777)
       └── Daemon thread: OrchestratorLoop
            ├── Fetches usage via tmux /usage command (HTTP API fallback)
            ├── Picks highest-priority eligible task
            ├── Dispatches to Claude Code via tmux sessions (session-id continuity)
            ├── Detects 429 rate-limit errors and backs off reactively
            └── Records results to SQLite (WAL mode)

Every loop cycle (default 60s) — scheduler picks one of 4 actions:

1. dispatch — evaluate token budgets, pick highest-priority task, send to Claude Code
2. sleep — budget exhausted, wait for token window to refill
3. idle — queue empty + ready tasks below watermark, trigger scan to create review tasks
4. create_only — budget too low for execution, only create/plan tasks

src/noru/
├── core/           # Models, database, config, constants (zero external deps)
├── engine/         # Token monitor, weekly tracker, queue, scheduler
├── executor/       # WorkerBackend protocol, Claude CLI, dispatcher, idle reviewer
├── interface/      # Orchestrator loop, Click CLI, FastAPI server, dashboard
└── integrations/   # Hooks (Telegram, Slack, Discord), superpowers, agency-agent

• Python 3.11+ — threaded orchestrator, zero JS build step
• SQLite (WAL mode) — fast concurrent reads, zero config
• FastAPI — REST API + dashboard serving
• Click — CLI framework
• Alpine.js + Chart.js — dashboard UI (single HTML file)

The WorkerBackend protocol abstracts CLI execution. The default TmuxWorker manages persistent Claude Code tmux sessions with session-id continuity per project. You can implement your own backend for other LLM CLIs.

Contributions are welcome! Noru is built with a test-first approach.

# Clone and install
git clone https://github.com/pxson2903/noru.git
cd noru
pip install -e ".[dev]"

# Run tests
pytest

# Run a specific test file
pytest tests/core/test_database.py -v

Guidelines:

• Write tests first, then implement (TDD)
• Use frozen dataclasses for models
• All DB queries go in core/database.py as named methods
• Follow the WorkerBackend protocol for execution backends
• Keep core/ free of external dependencies

MIT — use it, fork it, ship with it.