Architectural Explainer — How Helm Works

Your life.
One command center.

Helm is not a chatbot. It is not an app that wants your subscription. It is a personal command center that gives an AI assistant a real, persistent model of your world, so it can actually help you — not just answer questions.

9 First-class entities
4 Daily rituals
4 Email accounts in one view
2 AI models working together
Scroll to explore
01

What is Helm, actually?

Most AI assistants are stateless. Every conversation starts from zero. You explain your context every time. You re-tell the same story. The AI is smart, but it has no memory. That is a fundamental design problem, not a feature gap.

Helm solves that by giving the AI a persistent brain. Not a cloud account or a settings page, but an actual structured file system of your life: your projects, your priorities, your calendar, your inbox, your evidence, your decisions. Every time the AI wakes up, it reads these files first.

The result is an assistant that already knows your full situation. You do not brief it. It briefs you.

💡

The core idea: Instead of storing context inside an AI model (which forgets), store it in plain files (which last forever). The AI reads the files. You own the files. If the AI gets replaced or upgraded, the files survive.

⚙️

Two surfaces, one brain: Helm is a web app you open on your phone or laptop. Cowork is Claude running on your Mac. Both read from and write to the same data store. One updates, the other sees it instantly.

How it all connects — 10,000 ft view
Gmail
4 accounts
Google Calendar
all calendars
Claude (Cowork)
Mac daemon
Firestore
cloud database
Helm Web App
your phone / laptop
reads ↓                                   writes ↑                       reads + writes ↕
Git Repository
markdown files — the ground truth
context/  ·  projects/  ·  briefs/  ·  decisions/  ·  evidence/  ·  priorities
02

The three layers

Every piece of the system lives in exactly one layer. No duplication. No drift.

📂

Layer 1 — The Files

Markdown in Git

Plain text files, checked into a git repository. Readable by any editor, any AI, any person. These are the source of truth for everything that is narrative: context about your life, project notes, decisions, evidence, priorities, briefs.


You own them forever
Full git history (nothing is ever lost)
Works with any AI model, any tool
Zero vendor dependency

Layer 2 — The Cloud

Firestore Database

A real-time database in the cloud (Google Firebase). This is the sync layer for everything structured and fast-changing: tasks, priorities, briefs, ritual health. When you check off a task on your phone, it is gone on your Mac in under a second.


Real-time sync across all devices
Claude can read and write tasks directly
Gemini chat messages live here
Locked to your Google account only
💻

Layer 3 — The Surfaces

Helm App + Cowork

Two places where you actually do things. Helm is the web app (phone-friendly, always available). Cowork is Claude Code on your Mac (full power mode for deep work). Both read from the same database. Neither one owns the data.


Helm: Today view, inbox, calendar, chat
Cowork: write code, send emails, plan
Both update Firestore — always in sync
Helm hosted on Firebase (free tier)

How data flows — layer to layer

A change in any layer propagates outward in seconds.

01
You commit a file change
You update context/current-priorities.md and commit it. A git post-commit hook fires automatically. It reads the file and writes the new priority list to Firestore. No manual step. No Claude session needed.
02
Helm sees the update in real time
The Helm web app is listening to Firestore via a live connection. The moment the hook writes, Helm's Overview tab re-renders your new priorities. You do not need to refresh the page.
03
Claude picks it up next session
The file is in git. When Claude starts a new session, it reads the context files. Your priorities are already there. Claude does not need to be told what changed.
04
You add a task from your phone
Helm writes it to Firestore directly. Next time Claude is active, it reads the same task collection. Both surfaces stay in sync without any extra plumbing.
05
Claude surfaces something from your inbox
Claude reads 4 Gmail accounts, spots something urgent, and writes a task to Firestore directly. Your Helm Today tab shows it within seconds. You see it on your phone. No chat session needed.
03

The 9 things the system tracks

Not everything. Only what changes frequently or needs to be retrieved quickly. Each entity lives in exactly one home.

Entity Lives in What it is Status
Tasks Firestore Today / this week / ongoing items. Check them off in Helm or Cowork. Claude can add them automatically. Live
Priorities Firestore
synced from md
Ranked list of what matters right now. Edited as a plain markdown file; auto-published to Firestore on commit. Live
Projects Markdown One folder per project. Each has a README with status, next steps, and context. Claude reads these at session start. Live
Decisions Markdown Append-only log. Every meaningful choice gets a date, a decision, the reasoning, and the context. Never edited, only added to. Live
People Markdown Key contacts with roles and context. Legal case people, family, business team. Claude knows who everyone is without being told. Live
Briefs Markdown
+ Firestore
Morning / midday / evening / weekly summaries written by Claude automatically. The latest one shows inline in Helm. Live
Evidence Markdown Verbatim quotes, dates, source info for the legal case. Never paraphrased. Stored per-incident in its own folder. Live
References Markdown SOPs, examples, templates, style guides. Things that repeat. Build it once, reference forever. Live
Calendar + Inbox Live API Read directly from Google. Not stored, not cached. Always fresh. Gmail (4 accounts) and Calendar (all calendars). Live
04

Two AI models,
one clear division of labor

Claude thinks, plans, and acts. Gemini reads, retrieves, and chats quickly. They share the same context files. They never talk to each other directly.

Claude (Cowork)

The executor

Runs on your Mac as a Claude Code session. Has full write access to everything. This is where real work happens.

📝 Writes emails, drafts documents, edits code
📊 Runs morning briefs, midday triage, EOD reflection on a schedule
🍒 Reads all 4 Gmail accounts via MCP tools
📅 Pulls and filters Calendar events
📅 Writes tasks to Firestore directly
⚙️ Runs git operations, deploys, shell commands
🔐 Access to Stripe, Supabase, Vercel, Firebase MCPs
Gemini (Helm Chat)

The fast lookup

Runs as a background daemon on your Mac. Powers the inline chat in Helm. Read-only. Fast. Always available from your phone.

🔊 Answers quick questions about your projects, briefs, tasks
📄 Reads any file in the repo via read_file tool
🔍 Searches across all files via search_text tool
📋 Fetches today's tasks, calendar, priorities from Firestore
🚫 Cannot write files, send emails, or take destructive actions
Streams responses token-by-token (feels alive, not sluggish)
🔁 Falls back to Codex CLI or Gemini API if free quota is hit

The daily rituals

Claude runs four rituals automatically — no prompt, no manual trigger. They fire on a schedule, read your live context, write a brief to the file system, and push it to Firestore for Helm to display.

8:10
Morning Brief
Scans all 4 inboxes. Checks calendar. Surfaces urgent items. Writes a structured brief with today's focus.
13:01
Midday Triage
Light pass. Conditional output only if something urgent arrived since morning. Otherwise silent.
18:01
EOD Reflection
Reviews the day's tasks and briefs. Logs what moved, what stalled. Seeds tomorrow's context.
Sun 19:10
Weekly Review
Broader view. Project-level progress. Priorities check. Writes a weekly brief used to orient Monday morning.
⚠️

Why a daemon instead of a cloud function? The rituals need access to your Mac's local files, your authenticated Composio sessions for Gmail, and your service account credentials. A cloud function can't reach any of that. The daemon runs on your Mac, already authenticated, with access to everything. Simpler. More powerful. Zero cloud cost.


The chat responder — how it actually works

scripts/helm-chat-responder.mjs — runtime flow
// You type a message in Helm chat on your phone
Helm browser  →  writes message to Firestore helm_chats/{id}/messages

// The daemon is watching Firestore in real time
Daemon  →  listener fires on new message

// Daemon builds context from your files
Daemon  →  loads GEMINI.md (your context + rules + boundaries)
Daemon  →  loads conversation history from Firestore

// Sends everything to Gemini
Daemon  →  calls Gemini with: systemPrompt + history + message + tools

// Gemini may call tools before answering
Gemini  →  calls read_file('projects/legal-case-payments-canada/...')
Daemon  →  executes the tool, returns content to Gemini
Gemini  →  calls get_tasks({ section: 'today' })
Daemon  →  queries Firestore, returns tasks to Gemini

// Gemini streams the response back
Gemini  →  streams tokens to daemon
Daemon  →  updates Firestore message doc chunk by chunk (status: 'streaming')
Helm    →  renders tokens as they arrive — real-time

// Done
Daemon  →  marks message status: 'done', logs token count + cost
      
05

Why we built it
this way

Every choice has a reason. No defaults were accepted blindly.

Why plain markdown files instead of a "real" database for everything?
Databases are only useful if you can also read them with a text editor, copy-paste them into a chat, or hand them to a different AI model in five years. Markdown files are just text. You open them in Notepad. Git tracks every change with who, what, and when. No API needed. No vendor to call. The files are the database.

The rule is: structured + fast-changing → Firestore. Narrative + slow-changing → Markdown. Tasks change 10 times a day. Use Firestore. The legal evidence file changes once a week. Use Markdown.
Why Firebase and not Supabase, Airtable, or Notion?
Firebase bundles authentication, hosting, and real-time database into one product. That means one login, one bill (free tier), one place to configure security rules. Supabase is great for SQL workloads; this workload is not relational — it is document-based, real-time, and needs to lock down to one user. Firebase is the exact right shape.

The Helm web app is also hosted on Firebase Hosting. Zero servers to manage.
Why two AI models (Claude and Gemini) instead of just one?
These two models have different strengths and different cost profiles. Claude (via Claude Code subscription) is the right tool for doing things: writing, planning, running shell commands, composing emails, managing files. Gemini Flash (via free API or the Gemini CLI free tier) is fast and cheap — ideal for quick lookups and chat in a sidebar.

Crucially: Gemini reads, Claude writes. That boundary is enforced in the code and in Gemini's system prompt. If you ask Gemini to send an email, it tells you to go ask Claude instead. No accidents.
Why a git post-commit hook instead of a scheduled sync job?
A cron job runs on a timer and syncs regardless of whether anything changed. A git hook fires exactly when you commit — which is the moment state actually changed. It is faster, cheaper, and more correct. If the hook fails (network down, wrong credentials), the commit still completes. It is non-blocking. You can re-run it manually anytime.
Why a daemon on your Mac instead of a cloud function for the chat responder?
The chat responder needs access to local files (your markdown repo) and to authenticated sessions for Gmail (via Composio MCP, which is on your Mac). Cloud functions are isolated — they have no file system and no local auth context. Running a Node.js daemon via launchd (macOS's process manager) means it starts automatically on login, restarts on crash, and has the same access you do. No cloud cost. No latency overhead. The daemon just runs in the background like any other system process.
Why two machines (desktop and laptop) instead of picking one?
Different contexts require different setups. The desktop stays on and runs scheduled tasks. The laptop travels. Both have the full repo via git. The rule is: pull before you start, push when you finish. The scheduled rituals run only on the always-on desktop. If you forget to pull, you get a merge conflict on markdown files — that is easy to fix. No data loss. The Firestore tasks are always in sync regardless.
06

Where we are
and where we are going

Built in four stages. Each one adds a layer without breaking what is already there.

Stage 1 — Foundation Complete
The skeleton. Define what the system tracks, where each thing lives, and how Claude finds its context when it wakes up. Ship something real before over-engineering anything.
9 first-class entities defined and in their canonical locations
Hybrid storage model in place (Firestore + Markdown)
Helm web app built and deployed to Firebase Hosting
Firebase Auth (Google sign-in), Firestore task persistence
4 rituals scheduled (morning brief, midday triage, EOD, weekly)
Multi-account Gmail and Calendar in Helm
Full Firestore schema documented and version-controlled
Stage 2 — Sync + Helm UI In Progress
Make the system feel alive. Automate the sync so you never have to manually publish changes. Add the Helm chat panel. Surface briefs and project status inside the app.
Git post-commit hook auto-publishes priority changes to Firestore
Brief-driven Today view in Helm (today's brief inline)
Projects tab with card grid and README rendering
Ritual health monitoring (last-run timestamps visible in Helm)
Cowork dashboard artifact synced to Firestore (not hardcoded)
Helm inline chat backed by Gemini (daemon running, tools in progress)
Streaming chat responses (token-by-token render in Helm)
Gemini tool-calling: read files, search repo, fetch tasks + calendar
3
Stage 3 — Integrations Planned
Connect the tools Dan already uses. Pull real data instead of asking him to summarize it. The AI should see what he sees.
ClickUp integration — tasks from VA workspace visible in Helm
CheckCherry integration — GoBooth bookings as first-class events
Stripe integration — revenue and invoice visibility in Helm
Shopify integration — photoboothdecor.com order status
Full Cowork ⇄ Helm parity (both surfaces identical capability)
4
Stage 4 — Intelligence Planned
Search, notifications, and the evidence locker. The system becomes proactive — it surfaces what matters before you ask.
Full-text search across all entities (briefs, projects, evidence)
Evidence locker with full rendering in Helm
Push notifications (Helm → phone) for urgent signals
Decision capture flow (structured capture inside Helm)
Proactive alerts (upcoming deadlines, stale projects)
07

What is working
today

Live, tested, and in daily use. Not demos. Not mockups.

📋

Today View

Opens to today's brief inline. Shows tasks by section (today, this week, ongoing). Check off tasks from your phone. They disappear in Cowork in seconds.

💌

Filtered Inbox

All 4 Gmail accounts in one view. Newsletters auto-filtered out. Priority senders (Canada Life, CheckCherry, Hussain, Mireille's lawyer) highlighted automatically.

📅

Calendar

All calendars merged. GoBooth bookings, personal events, Calendly, CheckCherry imports. Live countdowns to today's events. The dgoneau@payments.ca calendar is deliberately excluded.

📁

Projects Tab

All active workstreams as cards. Tap a project to see its full README rendered inline. Legal case, GoBooth recovery, separation, Inner Pi — all visible in one place.

Ritual Health

Shows when each ritual last ran (morning brief, midday, EOD, weekly). If a ritual missed its window, the card flags it. No missed brief goes unnoticed.

💬

Inline Chat

Chat panel accessible from any brief item. Daemon running and connected to Gemini. Tool-calling and streaming responses in active development (Stage 2).


The stack at a glance

tech-stack.md
Frontend     Single-file SPA      public/index.html — no build step, no framework
Auth         Firebase Auth        Google sign-in, locked to goneau@gmail.com
Database     Firestore            Real-time, document-based, one collection per entity
Hosting      Firebase Hosting     helm-dashboard-293cd.web.app — free tier, global CDN
Inbox/Cal    Gmail + Calendar API Direct browser calls via OAuth token
AI (Cowork)  Claude Opus 4.7      via Claude Code subscription, Mac daemon
AI (Chat)    Gemini Flash         via free tier CLI, falls back to API
Source truth Git + Markdown       ~/Documents/Claude/Projects/Dan's Assistant/
Sync         git post-commit hook fires on commit, non-blocking
Daemon       Node.js + launchd   starts on login, restarts on crash
MCPs         Firebase, Gmail, Cal Composio for multi-account Gmail
      
08

How this compares
to the alternatives

Capability Notion AI ChatGPT Zapier Helm
Remembers your full context session to session
limited

memory feature, limited

full context in files
Reads your actual Gmail and Calendar live
with setup

4 accounts simultaneously
You own your data (no vendor lock-in)
in Notion's DB

OpenAI controls it

plain files in git
Works across phone + Mac without re-logging in
Firebase Auth
Runs automated rituals daily without your input
basic automations

4 scheduled rituals
Can write code, run terminal commands, deploy
with plugins

via Claude Code
Free to run (no per-query AI costs for daily use)
per-seat plan

per-seat plan

task-based pricing

Claude Code sub covers most; Gemini free tier for chat
Handles legal evidence with strict formatting rules
enforced via CLAUDE.md rules
09

The things we refuse to compromise on

The AI should know your world. Your world should not live inside the AI.

Data portability, always

Every piece of context is a plain text file. Open in any editor. Readable by any AI. If Claude gets replaced by a better model tomorrow, the files survive. The system improves with better AI, not because of it.

The AI gets smarter over time

Context files grow. Decisions accumulate. Patterns get documented as reference files. Every session adds to the body of knowledge. The assistant becomes more useful without any intentional "training" — just by doing the work.

Nothing is over-engineered

No build step for the frontend. No ORM for the database. No framework for the rituals. Each piece is the simplest thing that works. When complexity is needed, it earns its place with a decision log entry that explains why.

The right tool for the right job

Claude for deep work. Gemini for quick chat. Git for narrative history. Firestore for real-time sync. Firebase for hosting. No single tool does everything. Each one does one thing well, and they pass data between them cleanly.

External drafts, never auto-sends

Claude can write every email, draft every letter, compose every document. It never sends. Every outbound communication is surfaced for review first. Legal and HR correspondence is flagged for paper-trail awareness.

Boundaries are code, not trust

Gemini is read-only because the daemon is read-only — the file-writing tools simply do not exist. Firestore is locked to one Google account because the security rules enforce it server-side. You do not rely on the AI to "remember" its limits. The limits are structural.

10

What it takes
to build one

Helm was built incrementally over several sessions. No big-bang. No "first finish the design." Here is the honest account of what is required.

Skills needed

Comfortable with a terminal
Can read and edit JSON and Markdown
Know what a git commit is
Have a Google account
Claude Code does the actual coding. You direct.

Time investment

Stage 1: ~1 day of paired sessions
Stage 2: ~2-3 days spread across a week
Stage 3: ~1-2 days per integration
Stage 4: ~1 week for search + notifications
Each stage ships something useful. Nothing is "unfinished" between stages.

Monthly cost

Claude Code: $20/month (subscription)
Firebase: $0 (free tier covers this load)
Gemini: $0 (free CLI quota)
Google APIs: $0 (personal use quota)
Total: ~$20/month
👉

The core idea is transferable. Your context files will look different — your priorities, your projects, your team, your legal situation. The architecture is the same. Files in git. Sync layer in Firestore. Claude for heavy work. Gemini for fast chat. Rituals on a schedule. Pick what matters to you and leave the rest.

Ready to take the helm?

Sign in to access your command center. Today view, calendar, inbox, projects, and inline chat — all in one place.

G Sign in with Google