attic documentation

A single self-hosted system where independent modules plug into a shared kernel and expose themselves through one JSON API, which several out-of-process clients share: a terminal TUI and command line, a web app (also packaged as a Mac app), and an Android app. One SQLite file, zero kernel changes to add a module.

attic

What it is

Attic is a personal productivity workspace assembled from small, self-contained modules: Todo, Wiki, Chat, Stocks, RSS, Habits, Shopping, Calendar, Remotes, Flows, Documents, Thoughts, Status, Dashboard, Applets, Cards and Layouts, plus Bots (your crew, built on Chat). Each module owns its data and logic; the kernel only provides shared plumbing (database, configuration, an event bus, a scheduler, and notifications).

Because every module follows the same contract, all of them automatically appear under /api/<module>, without touching the kernel or any other module. Each client then decides how to show it: the web app as a card, the phone as an app on its rail. The TUI is deliberately narrower: the crew (Chat and your bots) plus Todo and Wiki, all driven from one prompt.

core/ is headless: it exposes only that JSON API (plus a background scheduler and event loop), and there is no in-process web UI. The browser front door onto the API is a standalone React SPA in webapp/. It, the terminal TUI, and the Android companion app are all out-of-process clients of the same service layer, talking to it over HTTP. The server itself has a small command of its own, cellar, for status, models, logs and updates.

The browser and phone clients share one look, called attic: paper cards on an ink desk, with the server shown as "your cellar". On the web you arrange cards in spaces; on the phone a rail of apps runs along the bottom.

At a glance

Aspect	Choice
Language / runtime	Python 3.12+, managed with uv
API	FastAPI JSON API (/api/<module>, interactive docs at /docs): headless, no server-side UI
Web UI	React SPA (webapp/): spaces of cards, Cmd+K launcher; Vite + TypeScript + Tailwind v4 + shadcn/ui + TanStack Query
Terminal UI	Rust/Ratatui (one prompt over the crew, Todo and Wiki): standalone tui/ crate, a client of the running server's JSON API
Command line	The same attic binary with arguments: quick capture, the crew and scripting from a shell (--json, stdin, non-zero exit on failure)
Mac app	The web app in its own window (desktop/, Tauri 2), with a global launcher shortcut
Server CLI	cellar (uv run cellar from core/): serve, status, models, logs, update
Storage	One SQLite file (hub.db) in WAL mode
Background work	APScheduler in the core process
Config / secrets	cellar.toml (gitignored, copied from cellar.toml.example) + secrets.toml (gitignored)
Access	Your network first; an optional cellar token (secrets.toml [server] token) that every client can send, off until set