# gomarble-agent

The GoMarble marketing agent, packaged as a plugin for **Claude Code** and **Codex CLI**.

Installing it connects the host to the GoMarble MCP server (OAuth) and adds:

- **37 model-invoked skills** covering Google Ads, Meta (Facebook/Instagram), GA4, Shopify, Search Console, and document generation
- **5 slash commands** for common Meta-Ads workflows (Claude Code only)
- **A SessionStart hook** that probes MCP reachability and checks for plugin updates

## Install

### Claude Code

In a Claude Code session, run these two slash commands:

```
/plugin marketplace add gomarble-ai/gomarble-agent
/plugin install gomarble-agent
```

Then:
```
/mcp
```
Authorize **gomarble** through the browser OAuth flow. One-time.

### Codex CLI

In your terminal:

```
codex plugin marketplace add gomarble-ai/gomarble-agent
```

Then start Codex, open the **Plugins** panel, find `gomarble-agent` under the `gomarble-agent` marketplace, and install/enable it. Finally:

```
codex mcp login gomarble
```

Same OAuth flow, one-time.

## Updating

When a new version is released, run `/plugin marketplace upgrade gomarble-agent` (Claude) or `codex plugin marketplace upgrade gomarble-agent` (Codex). The SessionStart hook will also prompt you on the first session of an outdated install.

## Slash commands (Claude Code)

| Command | What it does |
|---|---|
| `/gomarble-agent:meta-ads-audit <acct>` | 30-day audit: pixel/CAPI, fatigue, audience splits, ROAS/CPA, budget |
| `/gomarble-agent:meta-performance-report <acct>` | 7d vs prior 7d, campaign/adset/creative breakdown |
| `/gomarble-agent:meta-budget-reallocation <acct>` | SCALE/REDUCE/HOLD/PAUSE per campaign using 1D + 3D + 7D |
| `/gomarble-agent:creative-strategy <acct>` | Full pattern analysis → test plan → 12-creative plan |
| `/gomarble-agent:creative-fatigue-detection <acct>` | Per-ad fatigue scoring with refresh actions |

In Codex, just describe the task in natural language — the skills' `description` fields handle auto-routing.

## Repo layout

```
gomarble-agent/
├── .claude-plugin/
│   ├── plugin.json              # Claude Code manifest
│   └── marketplace.json         # marketplace declaration (Codex reads this too)
├── .codex-plugin/
│   └── plugin.json              # Codex manifest
├── .mcp.json                    # remote MCP, both `mcpServers` and `mcp_servers` keys
├── commands/                    # 5 slash commands (Claude reads; Codex ignores)
├── hooks/
│   ├── hooks.json               # registers SessionStart hook
│   └── session-start.mjs        # MCP probe + version check + date injection
├── skills/                      # 37 skills (both hosts read from here)
│   └── <slug>/SKILL.md
├── README.md
└── .gitignore
```

## How both hosts share one folder

Each host looks for its manifest in a dedicated subfolder; everything else is shared.

| Host | Manifest | Ignores |
|---|---|---|
| Claude Code | `.claude-plugin/plugin.json` | `.codex-plugin/` |
| Codex | `.codex-plugin/plugin.json` | `.claude-plugin/plugin.json` (but reads `.claude-plugin/marketplace.json`) |

- **`skills/`** — both hosts expect `skills/<name>/SKILL.md`
- **`.mcp.json`** — Claude reads `mcpServers`, Codex reads `mcp_servers`. Both keys present with identical content
- **`commands/`** — Claude picks up slash commands; Codex has no `commands/` concept

## Publishing a new version

```bash
# 1. Edit skills/<slug>/SKILL.md, commands/*.md, hooks, or manifests
# 2. Bump version in BOTH .claude-plugin/plugin.json AND .codex-plugin/plugin.json
# 3. Commit + tag + push
git add -A
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z
git push --follow-tags

# 4. (Optional) Update https://apps.gomarble.ai/plugin/version.json so the SessionStart
#    hook surfaces the update prompt to existing users:
#    { "version": "X.Y.Z", "released": "YYYY-MM-DD", "notes": "What changed." }
```

Users run `/plugin marketplace upgrade gomarble-agent` (Claude) or the Codex equivalent to pull the new version.

## SessionStart hook

Every session, `hooks/session-start.mjs` runs once and:

1. Injects today's date into the agent's context
2. Probes `https://apps.gomarble.ai/mcp-api/sse` for reachability; warns if down
3. Compares local version to `https://apps.gomarble.ai/plugin/version.json` and prints an update prompt if outdated

All network calls have 2.5s timeouts and silent failure modes — the hook never blocks a session.

Both hosts treat plugin hooks as **non-managed** — on first install users see a "trust this hook" prompt. They accept once, then it runs silently.

## Credentials

Users need nothing beyond the install commands. The MCP OAuth flow is handled by Claude (`/mcp`) and Codex (`codex mcp login gomarble`). Skills are edited directly in this repo — no Langfuse access needed.

## Known caveats

- **`mcp_servers` vs `mcpServers`** — `.mcp.json` ships both wrapper keys with identical content so each host finds its preferred form.
- **First-install hook trust** — hooks are non-managed; users must accept the trust prompt the first time.