Fanta

Fanta

A multi-agent system on Claude Code that runs my studio and most of my life. Each agent has its own identity, memory, and heartbeat, and the whole thing is operated from a phone.

note

Status: semi-retired. Fanta is the previous generation of this idea. I now run the same role-separation-by-chat through Hermes, Nous Research’s agent framework, so this is no longer the live system. It is not a clean one-to-one port, but the shape carried over almost entirely. The repo stays private because it is full of personal context I have no interest in publishing, so this page is the architecture, not the code.

Fanta is the system that grew up around the realization that running a one-person software studio and a full life from a phone needed more than a single Claude Code session and a Telegram bridge. It needed agents that could keep state, run on their own clock, talk to each other, and only ping me when there was something worth saying.

The structure was not invented from scratch. I took the spirit of OpenClaw’s agent layout to bootstrap the first version, ran it for a couple of days, and found it did not quite light me up, so I started building my own thing on top of Patchbay Relay instead. What I ended up with turned out to be strikingly close to what Hermes offers today, which is a big part of why moving the live system over to Hermes felt more like coming home than starting over.

This page covers what the system looked like, why each agent existed, and the design principles that held it together.

Agents, Not Assistants

Every Fanta agent follows the same identity stack pattern. Five markdown files and one Python script per agent:

  • SOUL.md for personality boundaries and communication style
  • IDENTITY.md for name and role
  • AGENTS.md for the operating manual, job description, and workflows
  • MEMORY.md for curated long-term memory, capped at 150 lines and enforced by a hook
  • HEARTBEAT.md for the scheduled task definitions
  • heartbeat.py for the scheduler entry point, auto-discovered by the runner

A unified scheduler runs every 15 minutes via launchd. It calls every agent’s heartbeat.py unconditionally. Each agent then decides for itself whether to act based on time of day, day of week, inbox state, or custom logic. The scheduler does not interpret. It only fires.

Unified Scheduler (every 15 min)
  -> Buddy        Email triage
  -> Lighthouse   Job search
  -> Feathers     Rare bird alerts
  -> Ernest       Strategy and portfolio
  -> Iron Temple  Strength coaching
  -> Fuel Desk    Meal planning
  -> Stevie       Attention manager
  -> Banana       Infrastructure monitor
  -> Library      Knowledge curator
  -> Sentinel     Config compliance

Outbound channels for any agent: Telegram for things that need eyes now, Cobalt (my Obsidian vault) for written reports and reply blocks, and Apple Reminders or Calendar when an event needs to land in my day.

Selected Agents

Buddy. Email triage and morning digest. Runs hourly from 7am to 10pm. Classifies inbound mail, routes job alerts to Lighthouse, surfaces urgent items to Telegram, and carries forward unanswered items across digests so nothing falls through.

Ernest. Strategy, prioritization, and portfolio analysis. Daily survey of every repo. Scans for open issues, stale branches, and unanswered reply blocks across the system.

Lighthouse. Job search. Daily scans of company career pages and aggregator feeds, scoring and clustering openings against a target profile, drafting cover letters as needed, and tracking the application pipeline.

Feathers. Ornithology advocate. Daily eBird API scan for rare bird sightings near my location. Cross-references against a life list, auto-creates calendar events for lifer opportunities within driving range.

Stevie. Attention manager and outbound comms router. Cross-agent reply audit on every scheduler tick. Scans every agent’s Cobalt output for unanswered reply blocks and pulls them into a single attention queue.

Banana. Infrastructure monitoring. Watches launchd state, TCC permissions, HTTP endpoints, and disk space on every tick. Weekly security sweep. Self-heals before alerting whenever it can.

Library. Knowledge curator and podcast archivist. Daily ingestion of podcast feeds and YouTube transcripts into ChromaDB collections for retrieval-augmented search.

Iron Temple. Strength training coach. Weekly check-in via the Hevy API. Tracks progressive overload, monitors injury rehab protocols, and builds periodized routines.

Fuel Desk. Sports nutritionist. Daily food-supply horizon estimation, alerts when prepared food is running low, and a recipe library that integrates with grocery logistics across multiple stores.

Sentinel. Config compliance. Validates agent bootstrap files and system configuration on every commit and on a schedule.

Inter-Agent Communication

The primary channel is Agent Mail, a JSON-RPC 2.0 HTTP server running locally. Every heartbeat calls check_agent_mail() at the start of a tick to fetch unread messages and send_agent_mail() to dispatch new ones. A legacy file-based inbox (markdown files in each agent’s inbox/ directory) is kept as a fallback for cases where Agent Mail is down.

The point of the message bus is that agents do not need to know how other agents work. Buddy classifies a job alert and sends it to Lighthouse. Lighthouse picks it up on its next tick. Buddy never reaches into Lighthouse’s storage. The bus is the contract.

Hardening

The system runs autonomously for hours and days at a time, which means small failures compound if not caught. Several hardening layers, all behind feature flags so they can be disabled per agent during debugging:

  • Typed models. Every JSON state file loads through validated dataclasses. Unknown keys are rejected at parse time so a malformed write cannot silently corrupt state.
  • Bootstrap validator. Checks that every agent has its required identity stack files before any heartbeat runs.
  • Circuit breaker. Tracks consecutive failures per agent. Auto-disables an agent at a threshold so a broken agent cannot keep paging me with the same crash.
  • Safehouse. Sandboxes each heartbeat to its own directory through filesystem isolation, so a misbehaving agent cannot stomp on another agent’s state.
  • Audit log. JSONL record of every scheduler invocation for forensic analysis when something goes wrong.

Design Principles

Four rules shape every agent in the system.

Proactive silence. Agents only notify when something needs attention. Empty output means no phone buzz. The cost of an unnecessary ping is much higher than the cost of a missed signal, because attention is finite and noise destroys trust in the channel.

Fly-by-Telegram. The entire system is operated from a phone. If a workflow requires a browser, a terminal, or a clipboard round-trip, it is a design flaw to be fixed. The agent does the work end-to-end and reports the result.

Memory-first. Every agent writes durable facts to disk the moment it learns them. Never batches state writes for end of session. The session could end at any moment. Anything that matters tomorrow has to be on disk today.

Agents do the work. Presenting me with a list of steps to follow is a failure mode. Agents execute the workflow themselves. Slash commands are reference docs that agents internalize, not interactive prompts I run by hand.

What Pairs With This

Fanta ran on the same Claude Code stack as the rest of the studio. Synodic Kit provided the safety layer through lifecycle hooks, Patchbay Relay was the bridge that delivered Telegram messages to whichever agent was on the other end, and the edit log captured every change every agent made across every project, so the recovery surface stayed rich when something went wrong.

The patterns outlived the implementation. They are what carried over to Hermes; the configuration was opinionated to one person and was never the interesting part anyway.