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

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

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

Security-Sensitive Areas

src/timmy_serve/ — API server, payment configuration
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`	API server (port 8402)

Module Map (8 packages)

Package	Purpose
`timmy/`	Core agent, personas, agent interface, semantic memory
`dashboard/`	FastAPI web UI, routes, templates
`infrastructure/`	WebSocket, notifications, events, LLM router
`integrations/`	Discord, Telegram, Siri Shortcuts, voice NLU
`spark/`	Event capture and advisory engine
`brain/`	Identity system, memory interface
`timmy_serve/`	API server
`config.py`	Pydantic settings (foundation for all modules)

3.0 KiB Raw Blame History