Files

Claude 6045077144 refactor: Phase 1/4/6 — doc cleanup, config fix, token optimization

Phase 1 — Documentation cleanup:
- Slim README 303→93 lines (remove duplicated architecture, config tables)
- Slim CLAUDE.md 267→80 lines (remove project layout, env vars, CI section)
- Slim AGENTS.md 342→72 lines (remove duplicated patterns, running locally)
- Delete MEMORY.md, WORKSET_PLAN.md, WORKSET_PLAN_PHASE2.md (session docs)
- Archive PLAN.md, IMPLEMENTATION_SUMMARY.md to docs/
- Move QUALITY_ANALYSIS.md, QUALITY_REVIEW_REPORT.md to docs/
- Move apply_security_fixes.py, activate_self_tdd.sh to scripts/

Phase 4 — Config & build cleanup:
- Fix wheel build: add 11 missing modules to pyproject.toml include list
- Add pytest markers (unit, integration, dashboard, swarm, slow)
- Add data/self_modify_reports/ and .handoff/ to .gitignore

Phase 6 — Token optimization:
- Add docstrings to 15 __init__.py files that were empty
- Create __init__.py for events/, memory/, upgrades/ modules

Root markdown: 87KB → ~18KB (79% reduction)

https://claude.ai/code/session_019oMFNvD8uSGSSmBMGkBfQN

2026-02-26 21:03:15 +00:00

2.8 KiB

Raw Blame History

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 notifications.push import notifier
from 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

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/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_tdd/watchdog.py`	Continuous test watchdog
`self-modify`	`src/self_modify/cli.py`	Self-modification CLI

2.8 KiB Raw Blame History