Metadata-Version: 2.4
Name: noru
Version: 0.1.1
Summary: Autonomous orchestrator for Claude Code — runs your task queue 24/7
Author: Louis
Keywords: claude,orchestrator,automation,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn[standard]
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: qrcode>=7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: license-file

<p align="center">
  <h1 align="center">🤖 Noru</h1>
  <p align="center">
    <strong>Ship while you sleep — autonomous Claude Code orchestration</strong>
  </p>
  <p align="center">
    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
    <a href="https://github.com/anthropics/claude-code"><img src="https://img.shields.io/badge/Claude-Code-blueviolet.svg" alt="Claude Code"></a>
    <a href="#-contributing"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
  </p>
</p>

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

<p align="center">
  <a href="https://youtu.be/JR6D9MSrjLs">
    <img src="https://img.youtube.com/vi/JR6D9MSrjLs/maxresdefault.jpg" alt="Noru Demo" width="720">
  </a>
  <br>
  <em>▶️ Watch the demo (2 min)</em>
</p>

---

## 📑 Table of Contents

- [📑 Table of Contents](#-table-of-contents)
- [✨ Features](#-features)
- [🚀 Quick Start](#-quick-start)
  - [1. Install](#1-install)
  - [2. Initialize a project](#2-initialize-a-project)
  - [3. Start the orchestrator](#3-start-the-orchestrator)
  - [Adding tasks manually](#adding-tasks-manually)
- [📊 Dashboard](#-dashboard)
  - [Tabs](#tabs)
- [⚙️ Configuration](#️-configuration)
  - [🛡️ Guardrails](#️-guardrails)
  - [🔍 Idle Review Jobs (16 built-in)](#-idle-review-jobs-16-built-in)
- [🔧 CLI Reference](#-cli-reference)
  - [Lifecycle](#lifecycle)
  - [Task Management](#task-management)
  - [Project Management](#project-management)
  - [Configuration](#configuration)
  - [Idle Reviews](#idle-reviews)
  - [Direct Execution](#direct-execution)
- [🔔 Integrations](#-integrations)
  - [Telegram](#telegram)
  - [Slack](#slack)
  - [Discord](#discord)
- [🌐 Tunnel (Remote Access)](#-tunnel-remote-access)
- [📡 API Reference](#-api-reference)
- [🏗️ Architecture](#️-architecture)
  - [Project Structure](#project-structure)
  - [Tech Stack](#tech-stack)
- [🤝 Contributing](#-contributing)
- [📄 License](#-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

**Prerequisites:** [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) and `tmux` installed.

```bash
# macOS
brew install tmux
```

### 1. Install

```bash
pip install noru
```

### 2. Initialize a project

```bash
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

```bash
noru start
```

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

```bash
# Open the dashboard in your browser
noru dashboard

# Check what's happening
noru status
```

### Adding tasks manually

```bash
# 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](docs/configuration.md)

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

```yaml
# 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:

```yaml
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 |

```bash
# 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](docs/integrations.md)

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

### Telegram

```yaml
# ~/.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

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

### Discord

```yaml
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](docs/tunnel.md)

Access your dashboard from anywhere — no port forwarding required.

```bash
# 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](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 |

```bash
# 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.

```bash
# 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.
