Comprehensive reference covering project structure, architecture patterns,
testing conventions, development workflows, and key configuration for AI
assistants working in this repository.
https://claude.ai/code/session_01Y77ZMumHHk5t9wT8ASrpwZ
Add complete production deployment stack so Timmy can be deployed to any
cloud provider (DigitalOcean, AWS, Hetzner, etc.) with a single command.
New files:
- docker-compose.prod.yml: production stack (Caddy auto-HTTPS, Ollama LLM,
Dashboard, Timmy agent, Watchtower auto-updates)
- deploy/Caddyfile: reverse proxy with security headers and WebSocket support
- deploy/setup.sh: interactive one-click setup script for any Ubuntu/Debian server
- deploy/cloud-init.yaml: paste as User Data when creating a cloud VM
- deploy/timmy.service: systemd unit for auto-start on boot
- deploy/digitalocean/create-droplet.sh: create a DO droplet via doctl CLI
Updated:
- Dockerfile: non-root user, healthcheck, missing deps (GitPython, moviepy, redis)
- Makefile: cloud-deploy, cloud-up/down/logs/status/update/scale targets
- .env.example: DOMAIN setting for HTTPS
- .dockerignore: exclude deploy configs from image
https://claude.ai/code/session_018CduUZoEJzFynBwMsxaP8T
Incorporates findings from deep-dive audits of all 5 subsystems:
- Swarm auction timing bug (sleep(0) instead of 15s)
- Docker agent HTTP API partially wired
- L402 macaroons are HMAC-only (no caveats/delegation)
- Agent sats are bid-only, no settlement occurs
- CLI test coverage gap (2 tests for 3 commands)
- agent_core persist_memory/communicate are stubs
https://claude.ai/code/session_01SZTwAkTg6v4ybv8g9NLxqN
- Fix /serve/chat AttributeError: split Request and ChatRequest params
so auth headers are read from HTTP request, not Pydantic body
- Add regression tests for the serve_chat endpoint bug
- Add agent_core and lightning to pyproject.toml wheel includes
- Replace Apache 2.0 LICENSE with MIT to match pyproject.toml
- Update test count from "228" to "600+" across README, docs, AGENTS.md
- Add 5 missing subsystems to README table (Spark, Creative, Tools,
Telegram, agent_core/lightning)
- Update AGENTS.md project structure with 6 missing modules
- Mark completed v2 roadmap items (personas, MCP tools) in AGENTS.md
https://claude.ai/code/session_01GMiccXbo77GkV3TA69x6KS
Update GitHub URLs, clone commands, CI badge links, GitHub Pages URL,
agent team name, and hardcoded macOS paths in handoff scripts to reflect
the new GitHub username. Handoff scripts now use relative paths instead
of hardcoded /Users/apayne paths.
https://claude.ai/code/session_01GMiccXbo77GkV3TA69x6KS
Build real PNG, WAV, and MP4 fixtures (no AI models) and exercise the
full assembler and Creative Director pipeline end-to-end. Fix MoviePy v2
crossfade API (vfx.CrossFadeIn) and font resolution (DejaVu-Sans).
14 new integration tests — 638 total, all passing.
https://claude.ai/code/session_01KJm6jQkNi3aA3yoQJn636c
Adds 3 new personas (Pixel, Lyra, Reel) and 5 new tool modules:
- Git/DevOps tools (GitPython): clone, status, diff, log, blame, branch,
add, commit, push, pull, stash — wired to Forge and Helm personas
- Image generation (FLUX via diffusers): text-to-image, storyboards,
variations — Pixel persona
- Music generation (ACE-Step 1.5): full songs with vocals+instrumentals,
instrumental tracks, vocal-only tracks — Lyra persona
- Video generation (Wan 2.1 via diffusers): text-to-video, image-to-video
clips — Reel persona
- Creative Director pipeline: multi-step orchestration that chains
storyboard → music → video → assembly into 3+ minute final videos
- Video assembler (MoviePy + FFmpeg): stitch clips, overlay audio,
title cards, subtitles, final export
Also includes:
- Spark Intelligence tool-level + creative pipeline event capture
- Creative Studio dashboard page (/creative/ui) with 4 tabs
- Config settings for all new models and output directories
- pyproject.toml creative optional extra for GPU dependencies
- 107 new tests covering all modules (624 total, all passing)
https://claude.ai/code/session_01KJm6jQkNi3aA3yoQJn636c
Add full pytest-cov configuration with fail_under=60% threshold,
HTML/XML report targets, and proper exclude_lines. Fix websocket
history test to use public broadcast() API instead of manually
manipulating internals. Audit confirmed 491 tests at 71.2% coverage.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add bootstrap.sh and checkpoint files for 2-hour handoff cycles:
- CONTINUE.md - Quick start guide
- CHECKPOINT.md - Current state (updated by Kimi)
- TODO.md - Remaining tasks
- bootstrap.sh - One-command status check
Introduce a feedback loop where task outcomes (win/loss, success/failure)
feed back into agent bidding strategy. Borrows the "learn from outcomes"
concept from Spark Intelligence but builds it natively on Timmy's existing
SQLite + swarm architecture.
New module: src/swarm/learner.py
- Records every bid outcome with task description context
- Computes per-agent metrics: win rate, success rate, keyword performance
- suggest_bid() adjusts bids based on historical performance
- learned_keywords() discovers what task types agents actually excel at
Changes:
- persona_node: _compute_bid() now consults learner for adaptive adjustments
- coordinator: complete_task/fail_task feed results into learner
- coordinator: run_auction_and_assign records all bid outcomes
- routes/swarm: add /swarm/insights and /swarm/insights/{agent_id} endpoints
- routes/swarm: add POST /swarm/tasks/{task_id}/fail endpoint
All 413 tests pass (23 new + 390 existing).
https://claude.ai/code/session_01E5jhTCwSUnJk9p9zrTMVUJ
Assess practical usefulness of spark.vibeship.co as an
integration into Timmy's agent system. Conclusion: low value
due to fundamental purpose mismatch (developer meta-tool vs
autonomous agent system), redundant persistence/orchestration
layers, and non-trivial integration effort for unclear benefit.
https://claude.ai/code/session_01E5jhTCwSUnJk9p9zrTMVUJ
Add infrastructure for running swarm agents as isolated Docker
containers with HTTP-based coordination, startup recovery, and
enhanced dashboard UI for agent management.
- Dockerfile and docker-compose.yml for multi-service orchestration
- DockerAgentRunner for programmatic container lifecycle management
- Internal HTTP API for container agents to poll tasks and submit bids
- Startup recovery system to reconcile orphaned tasks and stale agents
- Enhanced UI partials for agent panels, chat, and task assignment
- Timmy docker entry point with heartbeat and task polling
- New Makefile targets for Docker workflows
- Tests for swarm recovery
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Bridges Telegram messages to Timmy via python-telegram-bot (optional
dependency). The bot token can be supplied through the TELEGRAM_TOKEN
env var or at runtime via the new POST /telegram/setup dashboard
endpoint, which (re)starts the bot without a restart.
Changes:
- src/telegram_bot/bot.py — TelegramBot singleton: token persistence
(telegram_state.json), lifecycle (start/stop), /start command and
message handler that forwards to Timmy
- src/dashboard/routes/telegram.py — /telegram/setup and /telegram/status
FastAPI routes
- src/dashboard/app.py — register telegram router; auto-start/stop bot
in lifespan hook
- src/config.py — TELEGRAM_TOKEN setting (pydantic-settings)
- pyproject.toml — [telegram] optional extra (python-telegram-bot>=21),
telegram_bot wheel include
- .env.example — TELEGRAM_TOKEN section
- .gitignore — exclude telegram_state.json (contains token)
- tests/conftest.py — stub telegram/telegram.ext for offline test runs
- tests/test_telegram_bot.py — 16 tests covering token helpers,
lifecycle, and all dashboard routes (370 total, all passing)
https://claude.ai/code/session_01CNBm3ZLobtx3Z1YogHq8ZS
overflow: hidden creates a WebKit scroll container that absorbs trackpad
events before they reach scrollable children (.chat-log, .mc-sidebar).
Changed .mc-main and .mc-chat-panel > .card to overflow: clip, which
clips visually but does not create a scroll container, so trackpad events
propagate correctly to the nearest scrollable descendant.
Added min-height: 0 to .mc-sidebar so the flex item can shrink below its
content size and overflow-y: auto actually triggers scrolling.
Added `make ip` target that prints local network URLs the phone can
reach. The server already runs on 0.0.0.0 with --reload, so Python and
template changes auto-reload; CSS/static changes need a manual refresh.
https://claude.ai/code/session_01WFuf8fzKSWjH8ztF6E9jbj
agno's Ollama backend requires both the `ollama` and `openai` packages
(it uses the OpenAI-compatible wire format under the hood), but neither
was declared as a project dependency.
Ran a full import walk of all src modules in a fresh venv to confirm
zero missing imports after this change.
https://claude.ai/code/session_01W8jeKbHYNS75mPhGLYJxVq
agno ships sqlalchemy as an optional dependency under its `sqlite` extra.
Installing bare `agno` (without the extra) left sqlalchemy absent, causing
`ModuleNotFoundError: No module named 'sqlalchemy'` on `make dev`.
Changing the dependency spec from `agno>=1.4.0` to `agno[sqlite]>=1.4.0`
ensures sqlalchemy is installed automatically by `make install`.
Also added a troubleshooting entry to README.md for this error.
https://claude.ai/code/session_01W8jeKbHYNS75mPhGLYJxVq
Implements the Morning Briefing and Approval Queue feature — the first step
from tool to companion. Timmy now shows up before the owner asks.
New modules
-----------
• src/timmy/approvals.py — ApprovalItem dataclass, GOLDEN_TIMMY governance
constant, full SQLite CRUD (create / list / approve / reject / expire).
Items auto-expire after 7 days if not actioned.
• src/timmy/briefing.py — BriefingEngine that queries swarm activity and
chat history, calls Timmy's Agno agent for a prose summary, and caches
the result in SQLite (~/.timmy/briefings.db). get_or_generate() skips
regeneration if a fresh briefing (< 30 min) already exists.
New routes (src/dashboard/routes/briefing.py)
----------------------------------------------
GET /briefing — full briefing page
GET /briefing/approvals — HTMX partial: pending approval cards
POST /briefing/approvals/{id}/approve — approve via HTMX (no page reload)
POST /briefing/approvals/{id}/reject — reject via HTMX (no page reload)
New templates
-------------
• briefing.html — clean, mobile-first prose layout (max 680px)
• partials/approval_cards.html — list of approval cards
• partials/approval_card_single.html — single approval card with
Approve/Reject HTMX buttons
App wiring (src/dashboard/app.py)
----------------------------------
• Added asynccontextmanager lifespan with _briefing_scheduler background task.
Generates a briefing at startup and every 6 hours; skips if fresh.
Push notification hook (src/notifications/push.py)
---------------------------------------------------
• notify_briefing_ready(briefing) — logs + triggers local notifier.
Placeholder for APNs/Pushover wiring later.
Navigation
----------
• Added BRIEFING link to the header nav in base.html.
Tests
-----
• tests/test_approvals.py — 17 tests: GOLDEN_TIMMY, CRUD, expiry, ordering
• tests/test_briefing.py — 22 tests: dataclass, freshness, cache round-trip,
generate/get_or_generate, push notification hook
354 tests, 354 passing.
https://claude.ai/code/session_01D7p5w91KX3grBeioGiiGy8
v2.0.0 Exodus — three roadmap items implemented in one PR:
**1. Agent Personas (Echo, Mace, Helm, Seer, Forge, Quill)**
- src/swarm/personas.py — PERSONAS dict with role, description, capabilities,
rate_sats, bid_base/jitter, and preferred_keywords for each of the 6 agents
- src/swarm/persona_node.py — PersonaNode extends SwarmNode with capability-
aware bidding: bids lower when the task description contains a preferred
keyword (specialist advantage), higher otherwise (off-spec inflation)
- SwarmCoordinator.spawn_persona(persona_id) — registers the persona in the
SQLite registry with its full capabilities string and wires it into the
shared AuctionManager via comms subscription
**2. Bid History Persistence (prerequisite for marketplace stats)**
- src/swarm/stats.py — bid_history table in data/swarm.db:
record_bid(), mark_winner(), get_agent_stats(), get_all_agent_stats()
- coordinator.run_auction_and_assign() now calls swarm_stats.mark_winner()
when a winner is chosen, so tasks_won/total_earned survive restarts
- spawn_persona() records each bid for stats tracking
**3. Marketplace Frontend wired to real data**
- /marketplace/ui — new HTML route renders marketplace.html with live
registry status (idle/busy/offline/planned) and cumulative bid stats
- /marketplace JSON endpoint enriched with same registry+stats data
- marketplace.html — fixed field names (rate_sats, tasks_completed,
total_earned), added role subtitle, comma-split capabilities string,
FREE label for Timmy, "planned_count" display
- base.html — added MARKET nav link pointing to /marketplace/ui
Tests: 315 passed (87 new) covering personas, persona_node, stats CRUD,
marketplace UI route, and enriched catalog data.
https://claude.ai/code/session_013CPPgLc589wfdS8LDNuarL
- payment_handler.py: warn when L402_HMAC_SECRET uses default value
- l402_proxy.py: warn when L402_MACAROON_SECRET uses default value
- .env.example: document L402_HMAC_SECRET, L402_MACAROON_SECRET, and
LIGHTNING_BACKEND with generation instructions
These warnings ensure operators are alerted before deploying with
insecure default secrets.
- Add 8 tests for timmy_serve/cli.py (start, invoice, status commands)
covering default args, custom args, and output validation
- Add 8 tests for voice_enhanced route covering all intent types
(status, help, swarm, voice, chat fallback) plus error handling
- Add 17 tests for websocket/handler.py covering broadcast to
multiple clients, dead connection cleanup, history trimming,
connect/disconnect, and all convenience broadcast methods
- Add 4 tests for the new GET /swarm/live page route
Total new tests: 37
- Fix swarm_live.html WebSocket URL from /swarm/ws to /swarm/live
(matching the actual endpoint in swarm_ws.py)
- Update handleMessage() to process individual swarm events
(agent_joined, task_posted, bid_submitted, task_assigned, etc.)
in addition to bulk state snapshots
- Add refreshStats() helper that fetches /swarm REST endpoint to
update stat counters after each event
- Add GET /swarm/live page route to render the swarm_live.html template
- Add SWARM and MOBILE navigation links to base.html header
(fixes UX-01: /mobile route not in desktop nav)
- Add spawn_in_process_agent() to SwarmCoordinator: creates lightweight
SwarmNode instances that share the coordinator's comms layer and
AuctionManager, enabling synchronous bid submission
- Fix post_task() to open the auction BEFORE announcing via comms so
in-process agent callbacks can submit bids into an open auction
- Fix run_auction_and_assign() to close an already-open auction instead
of re-opening (which would discard bids)
- Add POST /swarm/tasks/auction route for atomic task+auction flow
- Add 7 integration tests (TDD) covering the full lifecycle:
spawn → post → auction → assign → complete
