Howard OS

A local-first AI assistant that lives in a green phosphor CRT dashboard on your Mac — for developers and solo builders who want an always-on coding companion without sending a single token to the cloud.

100% local · Ollama · FastAPI · no cloud, no telemetry

Quick start

Requires Ollama installed and running, with at least one model pulled:

ollama pull gemma2:9b
git clone <this-repo> && cd howard-os
./Howard.command

Howard.command auto-detects a compatible Python (3.11–3.13), creates a .venv, installs dependencies, and starts the server at http://localhost:7777. First run walks you through picking a base model and generating Howard's Modelfile.

The optional Telegram bridge needs a bot token and your numeric chat ID — copy .env.example to .env and fill it in. Without it, Howard runs dashboard-only.

Architecture

flowchart LR
    Browser["Browser<br/>CRT dashboard"] <--> Server["FastAPI server<br/>(webapp/)"]
    Server <--> Engine["Brain / Engine<br/>(core/)"]
    Engine <--> Ollama["Ollama<br/>local models"]

    Server --> Forge["Persona forge"]
    Forge --> Builder["Modelfile builder"]
    Builder --> Ollama

    Server -.optional.-> Bridge["Telegram bridge<br/>(aiogram)"]
    Bridge <--> Engine

Loading

Features

• Persona forge — a branching questionnaire (role, tone, opinions) generates a full persona spec, converted into an Ollama Modelfile and grafted onto any local model.
• Vibe Mode — a guided 4-step protocol (product definition → UI → trade-offs → build synthesis) that turns a vague request into a validated build brief before any code is generated.
• Mini-app generator + launcher — generates self-contained app folders (mini_apps/YYYY-MM-DD_name/) and detects how to run them: CLI form, web server with iframe preview, or terminal fallback.
• CRT dashboard — a green phosphor terminal UI showing live conversation, active model, module status, and the mini-app catalog.
• Telegram bridge (optional) — chat with Howard from your phone; brainstorm sessions and mini-app runs stay in sync with the dashboard.
• RAM guard — live system snapshot (RAM/CPU, health score) to keep local inference from swapping out your Mac.

Stack

Python 3.11+ · FastAPI · Uvicorn · Ollama · aiogram (Telegram) · aiosqlite · Pydantic · Jinja2 · psutil

Roadmap

• Streaming responses for faster time-to-first-byte
• Voice input/output over the Telegram bridge
• Persona marketplace / sharing format
• Signed Mac installer

License

MIT — see LICENSE.