noru 0.1.0

Autonomous orchestrator for Claude Code — runs your task queue 24/7

🤖 Noru

Ship while you sleep — autonomous Claude Code orchestration

Your AI developer that never sleeps. Noru is a Python CLI + web dashboard that runs Claude Code tasks autonomously 24/7 — managing priorities, token budgets, and idle code reviews so your codebase improves around the clock.

▶️ Watch the demo (2 min)

---

📑 Table of Contents

• 📑 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

---

✨ Features

Feature	Description
🎯 Autonomous Task Queue	Priority-based scheduling with weight classes (light/medium/heavy)
📊 Real-Time Dashboard	Kanban board, stats, charts — desktop + mobile responsive
📊 Token Budget Management	5-hour session windows + weekly limits with auto-pause
🔍 Idle Code Reviews	16 built-in review types run via watermark refill when ready tasks drop below threshold
⏸️ Pause / Resume	Pause the agent from the CLI or API — server stays up, dispatch stops
🌍 Language Config	Claude responds in your language — 13 supported languages
📜 Activity Log	Persistent event timeline for every dispatch, pause, and state change
🛡️ Guardrails	User-defined rules injected into all prompts to prevent noru from overstepping
🔌 Plugin Notifications	Telegram, Slack, Discord — know when tasks complete
🌐 Remote Access	Built-in tunnel support (cloudflared/ngrok) with QR code
🔧 Full REST API	Everything the dashboard can do, your scripts can too
📋 Event Hooks	Custom notifications on task start, complete, fail
⚡ Zero Build Step	No npm, no webpack, no framework overhead — just Python
🛡️ SQLite + WAL	Fast, reliable, zero-config database

---

🚀 Quick Start

Get Noru running in under 2 minutes:

1. Install

pip install noru

2. Initialize a project

cd ~/your-project
noru init

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

3. Start the orchestrator

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

Adding tasks manually

# 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

---

📊 Dashboard

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

Tabs

Tab	What it shows
📈 Overview	Metric cards, token window bar, weekly budget bar, agent controls, recent activity
📋 Kanban	4-column board (Todo → Doing → Review → Done) with project filters
📁 Projects	Project cards with status and task counts
📝 Tasks	Searchable, filterable table with all tasks
📊 Stats	Token usage charts, completion rates, cost tracking

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

---

⚙️ Configuration

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.

🛡️ Guardrails

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"

🔍 Idle Review Jobs (16 built-in)

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.

Job	Default	Focus
security-scan	✅ ON	XSS, injection, secrets, OWASP Top 10
bug-detection	✅ ON	Test failures, type errors, edge cases
logic-review	✅ ON	Business logic, missing validations
test-coverage	✅ ON	Untested functions, generate tests
code-quality	✅ ON	Dead code, unused imports, TODOs
refactor	⬜ OFF	Extract functions, reduce duplication
ui-bug-scan	⬜ OFF	Visual regressions, broken layouts
ux-review	⬜ OFF	Accessibility, navigation, UX patterns
ui-polish	⬜ OFF	Spacing, alignment, consistency
perf-audit	⬜ OFF	N+1 queries, memory leaks
docs-update	⬜ OFF	Missing docstrings, README gaps
dependency-check	⬜ OFF	Outdated packages, CVEs
api-review	⬜ OFF	Endpoint consistency, validation
type-safety	⬜ OFF	Missing type hints
error-handling	⬜ OFF	Missing try/catch, error propagation
pr-review	⬜ OFF	Review open PRs on GitHub

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

---

🔧 CLI Reference

Lifecycle

Command	Description
noru start	Start orchestrator + dashboard server
noru stop	Graceful stop (finishes current task)
noru stop --force	Immediate stop
noru restart	Stop then start
noru pause	Pause dispatch — server stays up, no tasks run
noru status	Current state, queue depth, active task
noru status --json	Machine-readable status output
noru dashboard	Open dashboard in browser
noru logs	Tail orchestrator logs

Task Management

Command	Description
noru task add --project ID --title "..." --priority N	Add a task
noru task ready ID	Promote task to the active queue
noru task list	List all tasks
noru task list --status todo --project my-app	Filter tasks
noru task done ID	Mark task done manually
noru task skip ID	Skip task (lower priority)

Project Management

Command	Description
noru project add --id my-app --name "My App" --repo-path ~/dev/my-app	Register a project
noru project list	List all projects
noru project pause ID	Pause a project (skip its tasks)
noru project resume ID	Resume a paused project
noru init	Scan current directory and propose tasks

Configuration

Command	Description
noru config show	View current configuration
noru config set KEY VALUE	Set a config value (dot notation)
noru config reset	Reset config to defaults

Idle Reviews

Command	Description
noru idle list	Show all review jobs with on/off status
noru idle enable JOB	Enable a review job
noru idle disable JOB	Disable a review job

Direct Execution

Command	Description
noru run	Run one task now (bypasses scheduler)
noru run --task ID	Run a specific task
noru run --dry-run	Show the prompt without executing

---

🔔 Integrations

Full reference: docs/integrations.md

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

Telegram

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

Slack

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

Discord

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.

---

🌐 Tunnel (Remote Access)

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

Provider	Setup
cloudflared (recommended)	brew install cloudflared — no account needed
ngrok	brew install ngrok — free account required

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

---

📡 API Reference

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:

Method	Endpoint	Description
GET	/api/status	Orchestrator state and queue info
GET	/api/tasks	List all tasks (supports filters)
POST	/api/tasks	Create a new task
PATCH	/api/tasks/:id	Update task status or priority
GET	/api/projects	List all projects
GET	/api/budget	Token budget status
GET	/api/stats	Usage statistics and charts data
POST	/api/agent/start	Start the orchestrator
POST	/api/agent/stop	Stop the orchestrator

# 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}'

---

🏗️ Architecture

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

Project Structure

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

Tech Stack

• 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.

---

🤝 Contributing

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

---

📄 License

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