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

# 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.