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

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.

---

Development Environments (tox)

tox is the single source of truth for all Python environments. Never run poetry run directly — always go through tox. All environment config (deps, markers, flags) lives in tox.ini. The Makefile and CI both delegate to tox.

Quick reference

tox -e unit             # Fast unit tests (default pre-commit gate)
tox -e ci               # Full CI suite with coverage + JUnit XML
tox -e lint             # black --check + isort --check + bandit
tox -e format           # Auto-format (black + isort)
tox -e dev              # Start dashboard with auto-reload

All tox environments

Environment	Purpose
lint	Check formatting + imports + security
format	Auto-format code
typecheck	mypy static analysis
unit	Fast unit tests, parallel
integration	Integration tests, parallel
functional	Functional tests, sequential
e2e	End-to-end tests
fast	unit + integration combined
ollama	Live LLM tests (requires Ollama)
ci	Coverage + JUnit XML (mirrors GitHub Actions)
coverage	Coverage terminal + XML
coverage-html	Coverage HTML report
pre-push	Lint + full CI suite (mirrors GitHub Actions exactly)
dev	uvicorn with auto-reload
all	All tests, parallel

Testing notes

• 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: 73% (fail_under in pyproject.toml)

---

Key Conventions

1. Tests must stay green. Run tox -e unit before committing. Run tox -e pre-push before pushing (mirrors CI exactly).
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.
10. Use tox for everything. Never run poetry run directly — use tox -e <env>.

---

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)