hoot

# 🦉 Hoot — The AI That Never Sleeps

[![npm version](https://img.shields.io/npm/v/hoot.svg)](https://www.npmjs.com/package/hoot)
[![CI](https://github.com/DUBSOpenHub/hoot/actions/workflows/ci.yml/badge.svg)](https://github.com/DUBSOpenHub/hoot/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Node.js ≥18](https://img.shields.io/badge/node-%E2%89%A518-232F3E.svg)
![Default backend: Copilot SDK](https://img.shields.io/badge/default%20backend-Copilot%20SDK-000000.svg)
[![Superpowers from awesome-copilot](https://img.shields.io/github/directory-file-count/github/awesome-copilot/skills?type=dir&label=superpowers&color=brightgreen)](https://github.com/github/awesome-copilot/tree/main/skills)

<img width="503" height="257" alt="Screenshot 2026-03-23 at 10 49 23 AM" src="https://github.com/user-attachments/assets/a7cfa818-0e37-468a-b969-be46d298d146" />

**Your personal AI daemon — it runs 24/7 in the background, remembers your preferences, handles tasks while you sleep, and reaches you on Telegram or your terminal.** Ships with [GitHub Copilot SDK](https://github.com/github/copilot-sdk) as the default backend; swap in Ollama, Anthropic, or OpenAI via the `AIProvider` interface.

> **🧩 Powered by [awesome-copilot](https://github.com/github/awesome-copilot)** — Hoot ships with every skill, tool, and agent from the community catalog and syncs new ones daily. Code generation, testing, DevOps, docs, AI agents, cloud automation — all built in from day one.

> **🤖 Built by over 100 AI agents across 10 models in 12 hours.**
> Hoot was designed, implemented, tested, and hardened by a swarm of AI agents orchestrated through the GitHub Copilot CLI, spanning Claude Opus, Sonnet, GPT-5.x, and Gemini. 233 tests. Zero human-written source code.

### 📊 [**Learn more about Hoot here**](https://dubsopenhub.github.io/hoot/)

> ### ⚡ Three Commands. Done.
>
> **Never used Node.js before? No problem.** Here's how to get Hoot running:
>
> **1. Open your terminal**
> - 🍎 **Mac:** Press `⌘ + Space`, type **Terminal**, hit Enter
> - 🪟 **Windows:** Press `Win + X`, choose **Terminal** or **PowerShell**
> - 🐧 **Linux:** Press `Ctrl + Alt + T`
>
> **2. Install Hoot:**
> ```bash
> curl -fsSL https://raw.githubusercontent.com/DUBSOpenHub/hoot/main/install.sh | bash
> ```
>
> **3. Start it:**
> ```bash
> hoot setup && hoot start
> ```
>
> That's it — Hoot is watching! 🦉
>
> *Requires [Node.js ≥18](https://nodejs.org) and an active [Copilot subscription](https://github.com/features/copilot/plans).*

---

## 🦉 What Is Hoot?

Hoot is like having a developer friend who never goes home. It runs on your computer 24/7, remembers your preferences, handles tasks while you're away, and reaches you on your phone via Telegram.

**The before and after:**

| Without Hoot | With Hoot 🦉 |
|---|---|
| Open ChatGPT → paste context → wait → copy answer → paste → repeat | Tell Hoot from your phone → walk away → get notified when done |
| Forget what you asked yesterday | Hoot remembers across 5 memory categories |
| One tab, one conversation | Same brain on Telegram, terminal, and HTTP — pick up where you left off |

---

## 🧠 What Makes It Different

Most AI tools are ephemeral — they forget you the moment the session ends. Hoot is a **daemon**: a persistent background process that runs 24/7 on your machine.

| Capability | Hoot 🦉 |
|-----------|---------|
| Always-on daemon | ✅ Runs 24/7 in the background |
| Long-term memory | ✅ Across 5 categories |
| Multi-channel (mobile + terminal) | ✅ Telegram + TUI + HTTP |
| Background agents | ✅ Up to 5 concurrent |
| Proactive notifications | ✅ Pushes to you |
| Model routing (fast/standard/premium) | ✅ Auto-classifies |
| Local-first, private | ✅ All data on your machine |

**What makes Hoot special:**

- 🧠 **Ambient Awareness** — Hoot remembers what you asked 3 hours ago. Preferences, facts, projects, people, routines — all persisted in local SQLite.
- ⚡ **Background Agency** — Say "refactor the auth module" from Telegram and walk away. Hoot spawns an agent, does the job, and notifies you when it's done.
- 📱 **Channel Convergence** — Same brain serves Telegram (mobile), TUI (terminal), and HTTP API. One daemon, many interfaces, zero context loss.

---

## 🚀 Quick Start

### Step 1: Install

```bash
npm install -g hoot
```

> **What's npm?** It's the Node.js package manager — it comes with [Node.js](https://nodejs.org). Download Node.js ≥18 and npm is included.

### Step 2: Setup

```bash
hoot setup
```

This creates `~/.hoot/` — the Hoot config directory. It stores your config, database, skills, and plugins.

### Step 3: Install the Copilot CLI

```bash
copilot login
```

> **What's the Copilot CLI?** It's the default AI backend Hoot ships with. Hoot's `AIProvider` interface supports pluggable backends — Copilot SDK is the default, but you can swap in Ollama, Anthropic, or OpenAI. For the default setup, you need an active [Copilot subscription](https://github.com/features/copilot/plans).

### Step 4: Start the daemon

```bash
hoot start
```

> **What's a daemon?** A background process that keeps running even when you close the terminal. Like a server, but personal.

### Step 5: Connect via TUI

```bash
hoot tui
```

> **What's a TUI?** A terminal user interface — a chat window inside your terminal.

---

## 💬 Talk to Hoot

From Telegram or the TUI, just type naturally. Here's what it feels like:

```
You: Start working on the auth bug in ~/dev/myapp
🦉: I'll create an agent session for that. Working directory: ~/dev/myapp.
    Spawned agent 'auth-fix' — I'll notify you when it's done.

You: What sessions are running?
🦉: 1 active agent:
    • auth-fix (~/dev/myapp) — running for 2m 30s

You: Remember that I prefer TypeScript over JavaScript
🦉: Got it! Saved to preferences: "Prefers TypeScript over JavaScript"

You: Check on the auth-fix session
🦉: Agent 'auth-fix' completed! Here's what I did:
    - Fixed the JWT expiration check in src/auth/validate.ts
    - Added missing error handling for expired refresh tokens
    - Updated 3 test files to match
```

---

## 🔧 Commands

### CLI Commands

| Command | Description |
|---------|-------------|
| `hoot start` | Start the daemon (background process) |
| `hoot tui` | Connect to the daemon via terminal UI |
| `hoot setup` | Interactive first-run configuration |
| `hoot update` | Check for and install updates |
| `hoot help` | Show available commands |
| `hoot start --self-edit` | Allow Hoot to modify its own source |

### TUI Commands

| Command | Description |
|---------|-------------|
| `/model [name]` | Show or switch the current model |
| `/memory` | Show stored memories |
| `/skills` | List installed skills |
| `/agents` | List active agent sessions |
| `/copy` | Copy last response to clipboard |
| `/status` | Daemon health check |
| `/restart` | Restart the daemon |
| `/cancel` | Cancel in-flight message |
| `/clear` | Clear the screen |
| `/quit` | Exit the TUI |

---

## 🏗️ Architecture

Here's what happens when you send Hoot a message: your input arrives through one of three channels (Telegram, TUI, or HTTP API), gets routed through the Message Bus to the Orchestrator (Hoot's persistent brain), which classifies the message complexity, selects the right AI model, and either responds directly or spawns a background agent for heavy tasks. Everything is backed by SQLite for memory, a Circuit Breaker for resilience, and structured logging for observability.

```
╔═══════════════════════════════════════════════════════════════╗
║                        CHANNELS                               ║
║   ┌──────────┐   ┌──────────┐   ┌──────────┐                ║
║   │ Telegram │   │   TUI    │   │ HTTP API │                ║
║   │ (mobile) │   │(terminal)│   │ (:7777)  │                ║
║   └────┬─────┘   └────┬─────┘   └────┬─────┘                ║
╠════════╪══════════════╪══════════════╪════════════════════════╣
║        └──────────────┼─

[truncated…]