Timmy-time-dashboard/CLAUDE.md

CLAUDE.md — AI Assistant Guide for Timmy Time

Tech stack: Python 3.11+ · FastAPI · Jinja2 + HTMX · SQLite · Agno · Ollama · pydantic-settings · WebSockets · Docker

For agent roster and conventions, see AGENTS.md.

---

Architecture Patterns

Config access

from config import settings
url = settings.ollama_url   # never use os.environ.get() directly in app code

Singletons

from dashboard.store import message_log
from infrastructure.notifications.push import notifier
from infrastructure.ws_manager.handler import ws_manager
from swarm.coordinator import coordinator

HTMX response pattern

return templates.TemplateResponse(
    "partials/chat_message.html",
    {"request": request, "role": "user", "content": message}
)

Graceful degradation

Optional services (Ollama, Redis, AirLLM) degrade gracefully — log the error, return a fallback, never crash.

Route registration

New routes: src/dashboard/routes/<name>.py → register in src/dashboard/app.py.

---

Testing

make test               # Quick run (no Ollama needed)
make test-cov           # With coverage (term-missing + XML)

• Stubs in conftest: agno, airllm, pyttsx3, telegram, discord stubbed via sys.modules.setdefault() — tests run without those packages
• Test mode: TIMMY_TEST_MODE=1 set automatically in conftest
• FastAPI testing: Use the client fixture
• Async: asyncio_mode = "auto" — async tests detected automatically
• Coverage threshold: 60% (fail_under in pyproject.toml)

---

Key Conventions

1. Tests must stay green. Run make test before committing.
2. No cloud AI dependencies. All inference on localhost.
3. Keep the root directory clean. No new top-level files without purpose.
4. Follow existing patterns — singletons, graceful degradation, pydantic config.
5. Security defaults: Never hard-code secrets.
6. XSS prevention: Never use innerHTML with untrusted content.
7. Keep routes thin — business logic lives in the module, not the route.
8. Prefer editing existing files over creating new ones.
9. Use from config import settings for all env-var access.

---

Security-Sensitive Areas

• src/swarm/coordinator.py — requires review before changes
• src/timmy_serve/l402_proxy.py — Lightning payment gating
• src/lightning/ — payment backend abstraction
• Any file handling secrets or authentication tokens

---

Entry Points

Command	Module	Purpose
timmy	src/timmy/cli.py	Chat, think, status
timmy-serve	src/timmy_serve/cli.py	L402-gated API server (port 8402)
self-tdd	src/self_coding/self_tdd/watchdog.py	Continuous test watchdog
self-modify	src/self_coding/self_modify/cli.py	Self-modification CLI

---

Module Map (14 packages)

Package	Purpose
timmy/	Core agent, personas, agent interface, semantic memory
dashboard/	FastAPI web UI, routes, templates
swarm/	Multi-agent coordinator, task queue, work orders
self_coding/	Self-modification, test watchdog, upgrade queue
creative/	Media generation, MCP tools
infrastructure/	WebSocket, notifications, events, LLM router
integrations/	Discord, Telegram, Siri Shortcuts, voice NLU
lightning/	L402 payment gating (security-sensitive)
mcp/	MCP tool registry and discovery
spark/	Event capture and advisory engine
hands/	6 autonomous Hand agents
scripture/	Biblical text integration
timmy_serve/	L402-gated API server
config.py	Pydantic settings (foundation for all modules)