Atom: a local-first AI agent with guardrails

I run client work, several products, a YouTube channel, and self-hosted infrastructure. Atom is the personal dashboard and agent I built to watch all of it and act on it. It runs on a local model on my own GPU, uses tools under explicit limits, and escalates to Claude only when a task needs it.

Architecture

Decisions and why

• The local model does the tool calling. Routine questions, data lookups, and tool use stay on the local model: no per-call cost, and personal data stays on the machine. Each response records which provider was requested and which was used.
• Claude where it adds quality. Two separate paths: an opt-in mode where Claude only writes the final answer from context the local model already gathered, and an escalation tool that hands complex multi-file tasks to Claude Code under a lock so only one runs at a time.
• Tools under explicit limits. File tools are scoped to allowed paths, command-line tools check an allowlist and a denylist, and server-side tools need a per-session approval.
• Memory loaded on demand. Long-term memory is split into topic files with keyword triggers, and the agent loads only the topics a question needs. Historical data points are embedded in pgvector for semantic search.
• Collectors behind one interface. Each of the 30+ sources implements the same collect and health-check methods, is registered once, and runs on a schedule, so adding a source doesn't touch the agent.
• Testable by construction. The clock, subprocess runners, and model providers are injected, so the agent logic can be tested without a real model or a running Claude session. The project has more than 1,300 tests.