Chairman Agent

Requirements: Python 3.9+ (stdlib only, no pip install), one Anthropic API key — everything else (Supabase, SendBlue, Telegram, macOS LaunchAgents) is optional — full walkthrough in SETUP.md.

An autonomous "chief of staff" agent: a conversational + heartbeat-driven Claude loop with server-side tool use (bash, file editing, web search), a cost guard that hard-stops spend at a monthly cap, a 32-persona agent roster it can delegate to, and a local dashboard to watch it work.

This is not a chatbot wrapper. It has three ways in — one-shot CLI chat, a scheduled heartbeat via macOS LaunchAgent, and two optional messaging bridges (iMessage via SendBlue, Telegram) — and one execution loop underneath all of them (agent.py:agent_loop). Whatever channel a message comes in on, it hits the same system prompt, the same tools, and the same cost guard.

Why it matters

Most "AI assistant" setups are a single prompt-response call. This one is a standing process: it runs on a timer whether or not you're looking at it, tracks its own spend and refuses to keep calling the API once a cap trips, and keeps a persona roster it can route sub-tasks to instead of trying to be one undifferentiated generalist. If you want an agent that has actual authority to act (run bash, edit files, search the web) on a schedule instead of only when you type to it, this is the shape of that.

What's in here

• agent.py — the core loop. --chat, --chat-stdin, and --heartbeat modes; server-side tool use (bash, text editor, web search) against the Anthropic Messages API; retries until the model stops calling tools.
• prompt.py — the agent's persona and standing operating rules (voice, execution standard, memory policy, mandated output structure). This is the actual "who is this agent" file — read it before you run anything, and rewrite it to be yours before you point it at your own business.
• config/agents.py — a 32-persona roster (Executive / Oversight / Operations / Intelligence / Revenue / Community / Product tiers) the Chairman can delegate named tasks to. Each entry is a system prompt + provider + model.
• cost_guard.py — monthly spend cap with an auto-cutoff threshold; wraps the API call so a runaway tool loop can't blow past budget mid-run.
• credit_guard.py, musa_cadence.py — smaller guard/cadence utilities used by the heartbeat and Telegram bridge.
• agent_bus.py — writes task/decision ledger rows to a Supabase project (optional — the agent runs fine with this unset, it just won't log).
• webhook.py + sendblue.py — inbound/outbound iMessage bridge via SendBlue. No Mac Full Disk Access or AppleScript required. See SENDBLUE-SETUP.md for the full wiring walkthrough.
• telegram_bridge.py — a stdlib long-poll Telegram bridge with one-tap commands (/pulse, /costs, /agent <ID> <task>, etc.) routed through the same agent_loop.
• dashboard/ — a local ops dashboard (server.py + index.html + ops.html) for watching heartbeat status, chat history, token/cost usage, and connection health. Run it separately from the agent itself.
• com.chairman.heartbeat.plist, com.chairman.webhook.plist — macOS LaunchAgent definitions for the scheduled heartbeat and the always-on webhook server.
• CUTOVER.md — a worked example of migrating a Telegram bot + agent roster from one system into this one. Useful as a reference for how the pieces fit together, not something you need to run.

Not included: the data/, inbox/, done/, and dashboard/conversations/ directories, and dashboard/usage.jsonl — these are runtime state (task queue, processed tasks, real chat history, real usage logs) from the original deployment. They're gitignored here on purpose; your own instance will grow its own versions of these directories the first time you run it.

Quickstart

1. Install dependencies

The agent itself is stdlib-only (urllib, no pip install needed for agent.py, webhook.py, sendblue.py, telegram_bridge.py, dashboard/server.py). You need Python 3.9+ and a shell. That's it.

2. Set your environment

Copy env.example to .env and fill in real values (it's named without the leading dot in this repo so it survives KeyzHub's secret-filename scanner — rename it however you like once it's on your machine):

cp env.example .env

At minimum you need ANTHROPIC_API_KEY. Everything else (Supabase, SendBlue, Telegram) is optional and gates its own feature — leave a block unset and that bridge simply won't come up.

agent.py looks for its .env at <repo-root>/content-os/config/.env by default (ENV_FILE near the top of the file — it's a relative path one level up from this directory, named after the original project's layout). Either recreate that path, or change ENV_FILE in agent.py to point at wherever you put your .env.

3. Make the persona yours

Open prompt.py and config/agents.py. Both are written for 19Keys / Sovereign Mind Media by name. Replace the identity, voice rules, and roster with your own before running this against your own business — the agent will follow whatever persona and standing mandate you give it, verbatim.

prompt.py also references a memory file path (sovereign-wiki/memory/CHAIRMAN-MEMORY.md in the original deployment) that isn't part of this repo. Point it at wherever you want the agent's memory to live, or remove the reference if you're not wiring up persistent memory.

4. Run it once, by hand

python3 agent.py --chat "what should I focus on this week"

or pipe a message in:

echo "summarize today's priorities" | python3 agent.py --chat-stdin

Run a single heartbeat cycle manually (this is what the LaunchAgent will run on a schedule):

python3 agent.py --heartbeat

Drop a task file for the next heartbeat to pick up:

mkdir -p inbox
cat > inbox/$(date +%Y%m%d-%H%M)-task.md <<'EOF'
## Task
Whatever you want the agent to do next cycle.
EOF

5. Load the LaunchAgent (macOS scheduled heartbeat)

Edit the two .plist files first — they hardcode absolute paths (/Users/19keys/sovereign-empire-sweep/chairman-agent/...) that need to point at wherever you cloned this repo, and the heartbeat's StartCalendarInterval (currently: Mondays at 9:00am) is a placeholder schedule, not a recommendation.

cp com.chairman.heartbeat.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.chairman.heartbeat.plist

Unload:

launchctl unload ~/Library/LaunchAgents/com.chairman.heartbeat.plist

The webhook plist (com.chairman.webhook.plist) is only needed if you're wiring up the SendBlue iMessage bridge — see SENDBLUE-SETUP.md.

6. Run the dashboard (optional)

cd dashboard
python3 server.py

Defaults to http://localhost:8919. It reads the same logs/, data/, and dashboard/conversations/ directories the agent writes to at runtime — those will be empty until you've actually run the agent a few times.

Make it your own

• Persona: prompt.py is the whole personality. Nothing here is magic — it's plain-language standing instructions the model follows. Rewrite it in your own voice.
• Roster: config/agents.py defines every persona the Chairman can delegate to. Trim it to the roles you actually have, or expand it.
• Cost cap: cost_guard.py holds the monthly spend cap and cutoff threshold — set your own number before you turn on the heartbeat.
• Channels: iMessage (SENDBLUE-SETUP.md) and Telegram (telegram_bridge.py) are both optional and independent — wire up whichever channels you actually want to talk to the agent through.
• Live grounding: agent.py:live_crm_context() pulls business numbers from a Supabase project into the system prompt if SUPABASE_URL / SUPABASE_ANON_KEY are set. If you don't have a Supabase project, leave those unset — the agent runs without live grounding.

A note on scope

This was built as one operator's personal chief-of-staff agent, wired to their specific business. The architecture (heartbeat + tool-using loop + cost guard + multi-channel bridge + persona roster) is the reusable part. The specific persona, roster, and business-numbers wiring are not — treat them as a fully worked example to fork and replace, not as configuration to leave as-is.