spectre-agent

<div align="center">

<img src="docs/media/banner.png" alt="Spectre Agent — it's your assistant. Haunt your own machine." width="760">

<img src="docs/media/home.png" alt="Spectre Agent — a living 3D home with your modules in orbit" width="760">

**A self-hosted AI agent you build into exactly what you need.**

**Spectre Agent** is a self-hosted AI agent with a 3D interface, where every capability is a *module you can write yourself*. I built it to fight my own ADHD — it remembers what matters, runs recurring tasks on its own, and is built to help me start things rather than stall on them. I made it extensible so it can become whatever *you* need. Your hardware, your models, your keys.

[![CI](https://github.com/EliasT5/spectre-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/EliasT5/spectre-agent/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-5965e0.svg)](LICENSE)
[![Self-hosted](https://img.shields.io/badge/self--hosted-docker%20compose-1a1a2e.svg)](#quick-install)
[![Bring your own model](https://img.shields.io/badge/brain-bring%20your%20own%20model-7a5cff.svg)](#what-it-can-do)
[![Status: early development](https://img.shields.io/badge/status-early%20development-f59e0b.svg)](#)

**[Quick install](#quick-install)** · **[Build a module](docs/MODULES.md)** · **[Roadmap](ROADMAP.md)**

</div>

---

> ## ⚠️ Recently opened — read the code before you run it
>
> The core went public sooner than planned, and the latest commit hasn't been through a full clean-room test yet. This is early-stage software that runs with shell access — read the files and verify it yourself before you run anything on your machine. Don't take my word that it's safe.

---

**What makes it different**

- 🧩 **You build it out** — every capability is a module. Add your own two ways: a JSON description (no code) or your own code. It grows the way *you* want, instead of waiting on a feature-request queue.
- 🧠 **Built for executive dysfunction** — it came out of my own ADHD: it remembers across conversations, runs recurring tasks on its own, and is meant to help you *start* and stay focused, not add one more thing to manage.
- 🏠 **A 3D interface, not a chat box** — your modules laid out as clickable orbs; or skip the UI and run it headless over Telegram, WhatsApp, Discord or HTTP.
- 🔑 **Entirely yours** — self-hosted on your hardware, your models, your keys; bring an API key or run a local model with no cloud account at all.

---

## The first ten minutes

One install command, then you open `http://127.0.0.1:3100` and hit a dark lock screen — *Secure Access. Enter your PIN.* Nothing reaches the agent until you're past it.

Then the home screen loads: a 3D scene with an animated central blob, ringed by one orb per module — Chat, Memory, Monitor, Settings, and whatever else your install includes. A clock sits overhead with a greeting that changes by time of day. Drag to rotate the view, scroll to zoom, click an orb to open that tab. There's no setup wizard or tour.

Start in Chat. Type a message, leave the model on Auto or pick one, and the reply streams in. When the agent calls a tool — shell, files, a screenshot — the call shows inline as a chip you can expand, and anything sensitive pauses for an Approve / Deny prompt before it runs. Turns run on the server, so you can close the tab mid-answer and it finishes without you. Follow-up messages queue behind the one in progress.

That covers the core idea: an interface you can see, tool calls you can watch, and nothing sensitive running without your approval.

---

> **🚧 Early development.** Spectre Agent is young and moving fast — expect rough edges, breaking changes, and features that aren't finished yet. Kick the tires, file issues, and help shape it; just don't trust it with anything critical for now.

_On the name: **Spectre Agent** runs on your own machine and answers only to you. It has no relation to the [Spectre CPU vulnerability](https://en.wikipedia.org/wiki/Spectre_%28security_vulnerability%29); the name is about the ghost, not the exploit._

## Quick Install

**Linux / macOS**

```bash
curl -fsSL https://elias-teubner.dev/install.sh | sh
```

**Windows (PowerShell)**

```powershell
irm https://elias-teubner.dev/install.ps1 | iex
```

One line. The installer brings everything else, and if git, Docker or Node are missing it offers to install them too. Then it asks three questions:

- **Which database.** A bundled local one (default, no cloud account anywhere) or your own Supabase project.
- **Which model.** Local Ollama by default, zero API keys. Or any provider through the gateway.
- **How much Spectre Agent:**

| Install profile | What you get |
|---|---|
| **Headless** | The agent with no web UI. Runs on a server, talks through Telegram, WhatsApp, Discord or raw HTTP. |
| **Standard** | The web app plus the essentials: chat, memory, monitor, settings. The default. |
| **Full** | Everything: the web app, Tempus time tracking, an

... (truncated)