Timmy Time — Mission Control

A local-first, sovereign AI agent system. Talk to Timmy, watch his swarm, gate API access with Bitcoin Lightning — all from a browser, no cloud AI required.

Live Docs →

---

Quick Start

git clone https://github.com/AlexanderWhitestone/Timmy-time-dashboard.git
cd Timmy-time-dashboard
make install              # create venv + install deps
cp .env.example .env      # configure environment

ollama serve              # separate terminal
ollama pull llama3.1:8b-instruct  # Required for reliable tool calling

make dev                  # http://localhost:8000
make test                 # no Ollama needed

Note: llama3.1:8b-instruct is used instead of llama3.2 because it is specifically fine-tuned for reliable tool/function calling. llama3.2 (3B) was found to hallucinate tool output consistently in testing. Fallback: qwen2.5:14b if llama3.1:8b-instruct is not available.

---

What's Here

Subsystem	Description
Timmy Agent	Agno-powered agent (Ollama default, AirLLM optional for 70B/405B)
Mission Control	FastAPI + HTMX dashboard — chat, health, swarm, marketplace
Swarm	Multi-agent coordinator — spawn agents, post tasks, Lightning auctions
L402 / Lightning	Bitcoin Lightning payment gating for API access
Spark	Event capture, predictions, memory consolidation, advisory
Creative Studio	Multi-persona pipeline — image, music, video generation
Hands	6 autonomous scheduled agents — Oracle, Sentinel, Scout, Scribe, Ledger, Weaver
Self-Coding	Codebase-aware self-modification with git safety
Integrations	Telegram bridge, Siri Shortcuts, voice NLU, mobile layout

---

Commands

make dev            # start dashboard (http://localhost:8000)
make test           # run all tests
make test-cov       # tests + coverage report
make lint           # run ruff/flake8
make docker-up      # start via Docker
make help           # see all commands

CLI tools: timmy, timmy-serve, self-tdd, self-modify

---

Documentation

Document	Purpose
CLAUDE.md	AI assistant development guide
AGENTS.md	Multi-agent development standards
.env.example	Configuration reference
docs/	Architecture docs, ADRs, audits

---

Configuration

cp .env.example .env

Variable	Default	Purpose
OLLAMA_URL	http://localhost:11434	Ollama host
OLLAMA_MODEL	llama3.1:8b-instruct	Model for tool calling. Use llama3.1:8b-instruct for reliable tool use; fallback to qwen2.5:14b
DEBUG	false	Enable /docs and /redoc
TIMMY_MODEL_BACKEND	ollama	ollama | airllm | auto
AIRLLM_MODEL_SIZE	70b	8b | 70b | 405b
L402_HMAC_SECRET	(default — change in prod)	HMAC signing key for macaroons
L402_MACAROON_SECRET	(default — change in prod)	Macaroon secret
LIGHTNING_BACKEND	mock	mock (production-ready) | lnd (scaffolded, not yet functional)

---

Architecture

Browser / Phone
      │ HTTP + HTMX + WebSocket
      ▼
┌─────────────────────────────────────────┐
│             FastAPI (dashboard.app)      │
│  routes: agents, health, swarm,          │
│          marketplace, voice, mobile      │
└───┬─────────────┬──────────┬────────────┘
    │             │          │
    ▼             ▼          ▼
Jinja2        Timmy       Swarm
Templates     Agent       Coordinator
(HTMX)        │           ├─ Registry (SQLite)
              ├─ Ollama   ├─ AuctionManager (L402 bids)
              └─ AirLLM   ├─ SwarmComms (Redis / in-memory)
                          └─ SwarmManager (subprocess)
    │
    ├── Voice NLU + TTS (pyttsx3, local)
    ├── WebSocket live feed (ws_manager)
    ├── L402 Lightning proxy (macaroon + invoice)
    ├── Push notifications (local + macOS native)
    └── Siri Shortcuts API endpoints

Persistence: timmy.db (Agno memory), data/swarm.db (registry + tasks)
External:    Ollama :11434, optional Redis, optional LND gRPC

---

Project Layout

src/
  config.py           # pydantic-settings — all env vars live here
  timmy/              # Core agent (agent.py, backends.py, cli.py, prompts.py)
  hands/              # Autonomous scheduled agents (registry, scheduler, runner)
  dashboard/          # FastAPI app, routes, Jinja2 templates
  swarm/              # Multi-agent: coordinator, registry, bidder, tasks, comms
  timmy_serve/        # L402 proxy, payment handler, TTS, serve CLI
  spark/              # Intelligence engine — events, predictions, advisory
  creative/           # Creative director + video assembler pipeline
  tools/              # Git, image, music, video tools for persona agents
  lightning/          # Lightning backend abstraction (mock + LND)
  agent_core/         # Substrate-agnostic agent interface
  voice/              # NLU intent detection
  ws_manager/         # WebSocket connection manager
  notifications/      # Push notification store
  shortcuts/          # Siri Shortcuts endpoints
  telegram_bot/       # Telegram bridge
  self_tdd/           # Continuous test watchdog
hands/                # Hand manifests — oracle/, sentinel/, etc.
tests/                # one test file per module, all mocked
static/style.css      # Dark mission-control theme (JetBrains Mono)
docs/                 # GitHub Pages landing page
AGENTS.md             # AI agent development standards ← read this
.env.example          # Environment variable reference
Makefile              # Common dev commands

---

Mobile Access

The dashboard is fully mobile-optimized (iOS safe area, 44px touch targets, 16px input to prevent zoom, momentum scroll).

# Bind to your local network
uvicorn dashboard.app:app --host 0.0.0.0 --port 8000 --reload

# Find your IP
ipconfig getifaddr en0    # Wi-Fi on macOS

Open http://<your-ip>:8000 on your phone (same Wi-Fi network).

Mobile-specific routes:

• /mobile — single-column optimized layout
• /mobile-test — 21-scenario HITL test harness (layout, touch, scroll, notch)

---

Hands — Autonomous Agents

Hands are scheduled, autonomous agents that run on cron schedules. Each Hand has a HAND.toml manifest, SYSTEM.md prompt, and optional skills/ directory.

Built-in Hands:

Hand	Schedule	Purpose
Oracle	7am, 7pm UTC	Bitcoin intelligence — price, on-chain, macro analysis
Sentinel	Every 15 min	System health — dashboard, agents, database, resources
Scout	Every hour	OSINT monitoring — HN, Reddit, RSS for Bitcoin/sovereign AI
Scribe	Daily 9am	Content production — blog posts, docs, changelog
Ledger	Every 6 hours	Treasury tracking — Bitcoin/Lightning balances, payment audit
Weaver	Sunday 10am	Creative pipeline — orchestrates Pixel+Lyra+Reel for video

Dashboard: /hands — manage, trigger, approve actions

Example HAND.toml:

[hand]
name = "oracle"
schedule = "0 7,19 * * *"  # Twice daily
enabled = true

[tools]
required = ["mempool_fetch", "price_fetch"]

[approval_gates]
broadcast = { action = "broadcast", description = "Post to dashboard" }

[output]
dashboard = true
channel = "telegram"

---

AirLLM — Big Brain Backend

Run 70B or 405B models locally with no GPU, using AirLLM's layer-by-layer loading. Apple Silicon uses MLX automatically.

pip install ".[bigbrain]"
pip install "airllm[mlx]"   # Apple Silicon only

timmy chat "Explain self-custody" --backend airllm --model-size 70b

Or set once in .env:

TIMMY_MODEL_BACKEND=auto
AIRLLM_MODEL_SIZE=70b

Flag	Parameters	RAM needed
8b	8 billion	~16 GB
70b	70 billion	~140 GB
405b	405 billion	~810 GB

---

CLI

timmy chat "What is sovereignty?"
timmy think "Bitcoin and self-custody"
timmy status

timmy-serve start          # L402-gated API server (port 8402)
timmy-serve invoice        # generate a Lightning invoice
timmy-serve status

Or with the bootstrap script (creates venv, tests, watchdog, server in one shot):

bash scripts/activate_self_tdd.sh
bash scripts/activate_self_tdd.sh --big-brain   # also installs AirLLM

---

Troubleshooting

• ollama: command not found — brew install ollama or ollama.com
• connection refused — run ollama serve first
• ModuleNotFoundError — source .venv/bin/activate && make install
• Health panel shows DOWN — Ollama isn't running; chat returns offline message

---

Roadmap

Version	Name	Status
1.0	Genesis	Complete — Agno + Ollama + SQLite + Dashboard
2.0	Exodus	In progress — Swarm + L402 + Voice + Marketplace + Hands
3.0	Revelation	Planned — Lightning treasury + single .app bundle