mixpanel-headless-setup

name	mixpanel-headless:setup
description	This skill installs mixpanel_headless, pandas, numpy, matplotlib, seaborn, networkx, anytree, scipy (and pyarrow on Python 3.11+), then verifies Mixpanel credentials. It should be invoked when setting up a new environment for Mixpanel data analysis, when dependencies are missing, or when configuring service account or OAuth credentials for the first time.
disable-model-invocation	true
allowed-tools	Bash

mixpanel-headless — Setup

Install dependencies and verify credentials for CodeMode analytics.

Run Setup

bash ${CLAUDE_SKILL_DIR}/scripts/setup.sh

This will:

1. Verify Python 3.10+ is available
2. Install mixpanel_headless, pandas, numpy, matplotlib, seaborn, networkx>=3.0, anytree>=2.8.0, scipy, and pyarrow>=17.0 on Python 3.11+ (tries uv, pip in order)
3. Verify all packages import successfully (including pyarrow on 3.11+, networkx, anytree, and scipy)
4. Check for configured Mixpanel credentials (single schema — Account → Project → Workspace)

Check Credentials

After installation, check the active session:

python3 ${CLAUDE_SKILL_DIR}/../mixpanelyst/scripts/auth_manager.py session

Parse the JSON state field:

• ok — credentials configured. Show account.name → project project.id and proceed to verification.
• needs_account — no account configured. Read next for onboarding suggestions and follow "If Credentials Are Missing" below.
• needs_project — account configured but no project pinned. Suggest mp project list then mp project use <id>.
• error — show error.message. If error.actionable is true, the message names a concrete next command.

If Credentials Are Missing

If no credentials are configured, guide the user to one of these methods:

Recommended: mp login

The frictionless one-shot path. Tell the user to run:

! mp login

mp login runs the right auth flow for the environment, derives the account name from /me, and pins a default project. For laptops with a usable browser, this opens the PKCE flow; for environments with MP_USERNAME + MP_SECRET set, it skips the browser and uses the service-account path; for MP_OAUTH_TOKEN set, it uses the static bearer.

Region behavior:

• service_account and oauth_token paths probe us → eu → in when --region is omitted.
• oauth_browser (the bare-mp login default) defaults to us. EU and India browser users must pass --region eu or --region in.

Useful flags: --name NAME, --region us|eu|in, --project ID, --service-account, --token-env VAR, --no-browser, --secret-stdin.

Alternative: Guided Setup (explicit account add)

Tell the user to run /mixpanel-headless:auth account add for a step-by-step walkthrough. The slash command never prompts for secrets in conversation — it instructs the user to run ! mp account add ... themselves so the secret is read with hidden input. Use this path when the user wants explicit control over the account name, region, and type at registration time.

Alternative: Service-Account Environment Variables (temporary)

For quick testing, set all four variables in the shell — the resolver picks them up directly without account registration:

export MP_USERNAME="service-account-username"
export MP_SECRET="service-account-secret"
export MP_PROJECT_ID="12345"
export MP_REGION="us"  # or "eu", "in"

Alternative: Raw OAuth Bearer Token (best for agents / CI)

If the user has an OAuth 2.0 access token from another source, they can use it directly without the PKCE browser flow:

export MP_OAUTH_TOKEN="<bearer-token>"
export MP_PROJECT_ID="12345"
export MP_REGION="us"  # or "eu", "in"

This is the recommended mode for non-interactive contexts. The full service-account env-var set (MP_USERNAME + MP_SECRET + MP_PROJECT_ID

• MP_REGION) takes precedence when both sets are complete.

Cowork Environment

If running inside Claude Cowork (detected automatically), credentials work differently:

• OAuth login and interactive account setup are NOT available (no browser, no host terminal access)
• Credentials must be configured on the host machine before starting a Cowork session

If No Credentials Found in Cowork

Tell the user:

No Mixpanel credentials found in this Cowork session.

On your host machine (outside Cowork), run:

mp account export-bridge --to ~/.claude/mixpanel/auth.json

This writes a v2 bridge file embedding your account record (and any oauth_browser tokens) so the Cowork session can read your credentials at startup.

Then start a new Cowork session — credentials will be available automatically.

Do NOT suggest /mixpanel-headless:auth account login, /mixpanel-headless:auth account add, or interactive flows — these won't work inside Cowork.

If Bridge File Found But Token Expired

The library will auto-refresh the OAuth token via the on-disk refresh token (no browser needed). If refresh fails:

Your OAuth session has expired and could not be refreshed. On your host machine, run:

mp login --name personal             # re-authenticate (or `mp account login personal`)
mp account export-bridge --to ~/.claude/mixpanel/auth.json

Then start a new Cowork session.

Verify Everything Works

python3 ${CLAUDE_SKILL_DIR}/../mixpanelyst/scripts/auth_manager.py account test

The subcommand never raises — read result.ok to determine outcome.

• result.ok: true → setup is complete; the user can ask analytics questions.
• result.ok: false → suggest /mixpanel-headless:auth account test for detailed diagnostics.

Post-Setup: Explore Your Data

Once authenticated, these slash commands help orient the user:

• /mixpanel-headless:auth project list — discover all accessible projects via /me
• /mixpanel-headless:auth session — see active account / project / workspace
• /mixpanel-headless:auth project use <id> — switch to a different project
• /mixpanel-headless:auth target add NAME --account A --project P — save a named cursor position

The user can also construct a Workspace targeting a specific account / project / workspace directly:

import mixpanel_headless as mp

ws = mp.Workspace()                                  # default session
ws = mp.Workspace(account="team")                    # named account
ws = mp.Workspace(project="67890")                   # explicit project (active account)
ws = mp.Workspace(account="team", project="67890")   # both axes
ws.use(project="98765").events()                     # in-session switch (no re-auth)

The mixpanelyst skill auto-triggers on analytics questions. For the analytical frameworks that guide investigations, see analytical-frameworks.md. For the complete Python API, see python-api.md.