# Setup

This is a stdlib-only Python agent — no `pip install`, no Docker, no build
step. The work is: get Python 3.9+, get one API key, and fix a few paths
that were hardcoded to the original author's machine.

## What you need

| Requirement | Why | Have it already? |
|---|---|---|
| macOS or Linux with a shell | `agent.py` shells out via `/bin/bash -lc`; any POSIX shell works | Check: `which bash` |
| Python 3.9 or newer | `pathlib`, f-strings, and the stdlib modules used throughout (`urllib`, `http.server`, `hmac`, `argparse`) | Check: `python3 --version` |
| An Anthropic API key | The only required credential — `agent.py` exits immediately without `ANTHROPIC_API_KEY` | Get one at console.anthropic.com |
| Homebrew (macOS only, optional) | Only needed if you don't already have Python 3, or if you wire up the SendBlue tunnel (`cloudflared`/`ngrok`) | Check: `which brew` |

**NOT needed:**
- No Docker — nothing here runs in a container.
- No `pip install` — every file imports only the Python standard library (`urllib`, `json`, `subprocess`, `hashlib`, `hmac`, `http.server`, `threading`, `argparse`, `pathlib`, `logging`, `re`, `shlex`, `importlib`). There is no `requirements.txt` in this repo because none is needed.
- No GPU.
- No database to install — Supabase (if you use it) is a hosted service you connect to over HTTPS, not something you run.
- No account required to run the core agent beyond Anthropic. Supabase, SendBlue, and Telegram are all optional and each gates its own feature; leave any of them unset and that part of the agent simply doesn't activate.
- macOS LaunchAgents (the two `.plist` files) are macOS-only and optional — they schedule the heartbeat and webhook to run automatically. On Linux, use `cron` or `systemd` instead to run the same commands (see Troubleshooting).

## Install, step by step

Fresh machine, assume nothing is installed yet.

### 1. Install Homebrew (macOS, skip if you already have it)

```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Sets up the macOS package manager.
**Check it worked:** `brew --version` → prints `Homebrew 4.x.x`.

### 2. Install Python 3

macOS:
```
brew install python3
```
Windows/Linux: install from https://python.org/downloads (Linux: `sudo apt install python3` on Debian/Ubuntu, or your distro's equivalent).

**Check it worked:** `python3 --version` → prints `Python 3.9.x` or newer. (Any version 3.9+ is fine — nothing here depends on a specific minor release.)

### 3. Clone this repo

```
git clone <this repo's KeyzHub URL> chairman-agent
cd chairman-agent
```
**Check it worked:** `ls agent.py prompt.py` → both files listed, no "No such file" error.

### 4. Get your Anthropic API key

Sign up / log in at https://console.anthropic.com, create a key under API Keys. This is a paid API — you need billing set up there before calls will succeed.

## Configure

Copy the example env file and fill in real values:

```
cp env.example .env
```

`agent.py` looks for its env file at `<repo-root>/../content-os/config/.env`
by default — that is, **one directory above wherever you put this repo**,
under `content-os/config/.env`. This path is a leftover of the original
project's folder layout, not a requirement of your setup. Either:
- recreate that exact relative path (`mkdir -p ../content-os/config && cp env.example ../content-os/config/.env`), or
- open `agent.py` and change the `ENV_FILE` constant near the top to point at wherever you put your `.env` (also update the same constant in `sendblue.py`, `webhook.py`, and `telegram_bridge.py` — each loads its own copy of `ENV_FILE`).

Required variable:

```
ANTHROPIC_API_KEY=YOUR_KEY_HERE  # keyzhub-allow
```

Everything else in `env.example` is optional and independently gated:

```
# Supabase — live business-numbers grounding + task ledger (agent_bus.py). Leave unset: agent runs, just no live-numbers block.
SUPABASE_URL=YOUR_SUPABASE_PROJECT_URL_HERE  # keyzhub-allow
SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY_HERE  # keyzhub-allow
SUPABASE_SERVICE_KEY=YOUR_SUPABASE_SERVICE_KEY_HERE  # keyzhub-allow

# SendBlue — iMessage bridge (see SENDBLUE-SETUP.md). Leave unset: no iMessage channel.
SENDBLUE_API_KEY_ID=YOUR_SENDBLUE_KEY_ID_HERE  # keyzhub-allow
SENDBLUE_API_SECRET_KEY=YOUR_SENDBLUE_SECRET_HERE  # keyzhub-allow
SENDBLUE_FROM_NUMBER=+1YOUR_SENDBLUE_NUMBER_HERE  # keyzhub-allow
SENDBLUE_WEBHOOK_SECRET=YOUR_SENDBLUE_WEBHOOK_SECRET_HERE  # keyzhub-allow
SENDBLUE_AUTHORIZED_NUMBERS=+1YOUR_PHONE_NUMBER_HERE  # keyzhub-allow
KEYS_IMESSAGE_NUMBER=+1YOUR_PHONE_NUMBER_HERE  # keyzhub-allow

# Telegram — chat bridge (telegram_bridge.py). Leave unset: no Telegram channel.
TELEGRAM_BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN_HERE  # keyzhub-allow
TELEGRAM_USER_ID=YOUR_TELEGRAM_USER_ID_HERE  # keyzhub-allow
```

Also worth knowing before you run anything:

- **`prompt.py` and `config/agents.py` are written for 19Keys / Sovereign Mind Media by name.** They are plain-language system prompts, not code that needs to compile — but the agent will follow whatever persona you leave in there, verbatim. Rewrite them before pointing this at your own business.
- **Hardcoded absolute paths.** `musa_cadence.py` (line 30) and `dashboard/server.py` (line 24) hardcode `/Users/19keys/sovereign-empire-sweep/...` / `chairman-agent` as their root path. If you didn't clone to that exact location, edit those two `ROOT`/`HOME` constants (or don't use `musa_cadence.py` / `dashboard/server.py` until you have). `agent.py`, `webhook.py`, `sendblue.py`, and `telegram_bridge.py` all resolve their own paths relative to the file (`Path(__file__).resolve().parent`), so those work regardless of clone location.
- **`prompt.py`'s `MEMORY_ANCHOR` references `sovereign-wiki/memory/CHAIRMAN-MEMORY.md`**, a file not included in this repo. Either create that path yourself or edit/remove the reference — the agent works without it, it just has no persistent memory file to read/write.

## Run it

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

Success looks like: a plain-text reply printed to stdout after a few
seconds (the agent may call its `bash`/`web_search`/file tools first — you
won't see that, just the final answer). If instead you see
`ERROR: ANTHROPIC_API_KEY not set`, your `.env` isn't being found — see
Troubleshooting.

Other entry points once the basic chat works:

```
python3 agent.py --heartbeat                 # one autonomous cycle (what the LaunchAgent runs on a schedule)
echo "summarize today" | python3 agent.py --chat-stdin
cd dashboard && python3 server.py             # local ops dashboard at http://localhost:8919
```

## Troubleshooting

1. **`ERROR: ANTHROPIC_API_KEY not set`** — the `.env` file isn't where `agent.py` is looking (`../content-os/config/.env` relative to the repo, by default). Either put your `.env` at that exact path or edit `ENV_FILE` in `agent.py` (and in `sendblue.py`/`webhook.py`/`telegram_bridge.py` if you use those). Quick sanity check: `python3 -c "import os; print(os.environ.get('ANTHROPIC_API_KEY'))"` after `source .env` — but `agent.py` does its own file parsing, not `source`, so this only confirms the key format, not that the loader finds the file.

2. **`API 400: ... credit balance is too low`** or a stalled heartbeat with no error** — the Anthropic account has no credit, or `cost_guard.py`'s 80%-of-$50/month cutoff has tripped (see `chairman-agent/data/api_costs.json` once it exists). Add credit at console.anthropic.com, or for a tripped budget cutoff, ask the Telegram bridge for `/unlock` (or call `cost_guard.reset_cutoff()` directly).

3. **`python3` not found, or a `python3` older than 3.9 runs instead of the one you installed** — the two `.plist` files and some docs assume `/usr/bin/python3` (macOS system Python). If you installed via Homebrew, that binary is usually at `/opt/homebrew/bin/python3` instead. Check with `which -a python3` and either update the `.plist` `ProgramArguments` to the correct path or symlink accordingly. On Linux there is no `.plist` equivalent — run these as `cron` entries or a `systemd --user` service instead, pointing at your real `python3` path.