# SWAPA Analytics — Claude Code & Cowork Setup Guide

---

## Before You Start — Check Your Account

Claude Code requires a **Pro, Max, Team, or Enterprise** plan.
The free Claude.ai plan does NOT include Code access.

**To check:** Open claude.ai → click your avatar → Settings → Plan.
If you're on a paid plan, you're good. If not, you'll need to upgrade before Code will work.

---

## Part 1 — Claude Code (the Code Tab)

Claude Code gives Claude direct access to your local files. You use it to refresh data,
maintain the fetch script, and make updates to the dashboard.

### Step 1 — Check if You Already Have It

You already have Claude Desktop installed (you set up ADO MCP with it).
Open the Claude Desktop app and look for three tabs at the top: **Chat · Cowork · Code**.
If you see the Code tab, skip to Step 3.

If you only see Chat, your Desktop app may need an update:
- macOS: Claude menu → Check for Updates

### Step 2 — Install / Update Claude Desktop (if needed)

Download the latest installer from claude.ai/download and run it.
Sign in with your existing Anthropic account when prompted.

### Step 3 — Open Your Project in the Code Tab

1. Click the **Code** tab in Claude Desktop
2. Click **"Open Folder"** or the folder icon
3. Navigate to and select your `swapa_analytics` folder
   (wherever you saved it — e.g. `~/swapa_analytics`)
4. Claude Code will read `CLAUDE.md` automatically on session start

That's it. Claude Code is now pointed at your project.

### Step 4 — Verify It Works

In the Code tab chat box, type:

> Run the fetch script and show me the output

Claude Code will run `python3 fetch_stats.py`, show you the output, and
confirm the data file was updated. If credentials are wrong or Python isn't
found, it will tell you and help you fix it.

### What to Use Claude Code For

| Task | What to say |
|---|---|
| Refresh podcast data | "Run the fetch script" |
| Check if data is current | "When was podcast_stats.json last updated?" |
| Add Podbean API (when ready) | "Add Podbean API support to fetch_stats.py" |
| Fix a bug in the script | Just describe what's wrong |
| Update the dashboard HTML | "Update the dashboard to load from the JSON file" |
| Set up the weekly schedule | "Install the launchd schedule on this Mac" |

### Installing the Weekly Auto-Run (optional but recommended)

Once Code is working, ask it:
> Install the launchd schedule so fetch_stats.py runs every Monday at 7am

Claude Code will handle the `cp` and `launchctl load` commands for you and
confirm it's scheduled correctly.

---

## Part 2 — Cowork (the Cowork Tab)

Cowork is an autonomous agent that works in a **cloud VM** — it does NOT see your
local files. You use it for generating reports, slides, and emails from your data.

### How to Use Cowork for Analytics Reports

1. First, run Code to get fresh data:
   - Open Code tab → "Run the fetch script"

2. Open `data/podcast_stats.json` in a text editor and copy all the contents

3. Open the **Cowork tab** in Claude Desktop

4. Open `COWORK_BRIEF.md` from your `swapa_analytics` folder
   Copy the entire contents of that file

5. Paste the brief into Cowork, then paste the JSON data at the bottom
   (there's a marked section at the end of the brief for this)

6. Choose which output you want (email, PowerPoint, or written summary)
   and tell Cowork to generate it

Cowork will work independently and deliver the finished output.
For PowerPoints, it will generate a downloadable .pptx file.

### What to Use Cowork For

| Task | Notes |
|---|---|
| Weekly summary email for Amy | Paste brief + JSON, ask for Option A |
| Monthly PowerPoint deck | Paste brief + JSON, ask for Option B |
| Executive summary write-up | Paste brief + JSON, ask for Option C |
| Analyzing trends or anomalies | Paste the JSON and ask specific questions |

---

## Part 3 — When Podbean Responds

When Podbean confirms API analytics access:

1. Open Code tab, point to `swapa_analytics`
2. Say: "Podbean confirmed API analytics access. Add automated Podbean
   download fetching to fetch_stats.py using Client ID `baf2841c7e9e83f77b2e4`
   and Client Secret `97fc818f4a5c1b30884f7`. The podcast ID is `EmAEvYtOwC6J`."
3. Claude Code will write and test the Podbean fetch function
4. Test it: "Run the fetch script with Podbean enabled and show me the output"
5. If it works: "Update the launchd schedule so we no longer need the --podbean CSV flag"

At that point the entire pipeline is fully automated — no CSV exports needed at all.

---

## Quick Reference

```
swapa_analytics/
├── CLAUDE.md           ← Claude Code reads this automatically (project memory)
├── COWORK_BRIEF.md     ← Paste into Cowork to generate reports
├── SETUP_GUIDE.md      ← This file
├── README.md           ← Technical setup (launchd, credentials, etc.)
├── fetch_stats.py      ← The data fetching script
├── com.swapa.analytics.plist  ← macOS weekly schedule
└── data/
    └── podcast_stats.json     ← Live data output
```

## Troubleshooting

**"Claude Code can't find python3"**
Open a regular terminal and run `which python3`. If it returns nothing, install Python
from python.org. If it returns a path, tell Claude Code: "Python is at [that path]".

**"HTTP 403 from Buzzsprout"**
The token may have been regenerated. Get the new token from Buzzsprout → My Account → API Access,
then tell Code: "Update the Buzzsprout token in fetch_stats.py to [new token]".

**"The Code tab isn't showing up"**
Update Claude Desktop — the Code tab requires a recent version.
Claude menu (macOS) → Check for Updates.

**"Cowork says it can't access my files"**
That's correct and expected — Cowork doesn't have local file access.
Copy the JSON content manually and paste it into the Cowork conversation.