gomarble-os

GoMarble OS

Plug your AI agent into your ad accounts. Audit, optimize, and launch campaigns with battle-tested marketing methodology.

A plugin for Claude Code and Codex CLI that turns your terminal-based AI agent into a senior performance marketer.

• 🔌 Live ad-platform data via the GoMarble MCP server (OAuth, one-click sign-in)
• 🧠 36 expert-authored skills — Google Ads, Meta (Facebook/Instagram), GA4, Shopify, Search Console, Klaviyo, TikTok, LinkedIn, Bing Ads, document generation
• ⚡ 5 slash commands for the most common Meta-Ads workflows (Claude Code)
• 🛡️ Built-in guardrails — no synthetic data, no fabricated keywords, proper attribution discipline

Install

Claude Code

In a Claude Code session, run:

/plugin marketplace add gomarble-ai/gomarble-os
/plugin install gomarble-os@gomarble-os

Then connect the MCP server:

/mcp

Pick gomarble, click Authenticate — the browser opens, you sign in to GoMarble, you're done.

Codex CLI

codex plugin marketplace add gomarble-ai/gomarble-os

Start Codex, open the Plugins panel, find GoMarble OS, and install. Then:

codex mcp login gomarble

Same OAuth flow, one-time.

What you can ask the agent

The skills auto-invoke based on what you ask — you don't have to remember anything. Some examples:

Ask	What happens
"Audit my Meta account act_12345 for the last 30 days."	Loads performance + creative + depth-of-analysis skills, pulls 30d data, runs Pareto analysis, flags fatiguing creatives, surfaces ROAS outliers, produces a report.
"How did my Google Ads Search campaigns do this week?"	Loads search-analysis skill, classifies queries Q1–Q5, diagnoses CPC inflation or rank pressure, returns a decision matrix.
"Create a Meta ad set for this creative targeting US iOS users."	Loads create/master + adset skills, verifies parent campaign, detects pixel, builds the propose payload, asks you to confirm before posting.
"Pull a 7d Shopify sales report and compare to GA4 conversions."	Loads Shopify order-discipline + GA4 source-of-truth skills, queries both, reconciles the difference.
"Generate a PPTX summarizing all my paid-media performance."	Loads pptx skill + the relevant analytics skills, produces a deck.

Slash commands (Claude Code only)

8 read-only morning-workflow commands. Each produces analysis + recommendations — never executes mutations. Mutations happen separately via Agent Mode if the user explicitly opts in.

Meta (4)

Command	What it does
/gomarble-os:meta-daily-optimization <acct>	Morning briefing: 1D vs 3D vs 7D, change-log gate, root-cause action recommendations (pause / cut / reallocate / scale candidates)
/gomarble-os:meta-ads-audit <acct>	30-day comprehensive audit — pixel/CAPI, fatigue, audience split, ROAS outliers, budget allocation
/gomarble-os:meta-creative-fatigue-detection <acct>	Per-ad scoring (Healthy / Early Warning / Fatigued / Dead) with refresh recommendations
/gomarble-os:meta-creative-strategy <acct>	Winners + losers, pattern extraction, test plan, scaling plan, 12-creative production spec

Google (4)

Command	What it does
/gomarble-os:google-search-audit <acct>	Daily Search briefing: brand-vs-non-brand segmentation, CUT / FIX / SCALE recommendations
/gomarble-os:google-pmax-pulse <acct>	3d-vs-3d PMax anomaly check — Critical / Alert / Monitor classification, disciplined against overcorrection
/gomarble-os:google-search-term-audit <acct>	Forensic waste audit using 80/80 Pareto + campaign-relative triggers; suggested negative keywords and root negatives
/gomarble-os:google-impression-share <acct>	Lost-IS analysis → scaling opportunities (Budget) vs bid/quality work (Rank), gated on profitability

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

Skills shipped (36)

Google Ads (17)

• Foundations — google-ads-tool-fundamentals, google-ads-guardrails
• Analysis — google-ads-search-analysis, google-ads-shopping, google-ads-pmax-evaluation, google-ads-pmax-scaling, google-ads-keywordplanner, google-ads-depth-of-analysis
• Execution — google-ads-search-execution
• Creation (master + 7 sub-skills) — google-ads-create-master-skill, google-ads-create-campaign, google-ads-create-ad-group, google-ads-create-ad, google-ads-create-asset, google-ads-create-experiment, google-ads-create-negative-keyword-list, google-ads-create-bid-modifiers

Meta — Facebook + Instagram (10)

• Foundations — meta-tool-fundamentals, meta-guardrails
• Analysis — meta-performance-analysis, meta-creative-analysis, meta-depth-of-analysis
• Operations — meta-agent-operations
• Creation (master + 3 sub-skills) — meta-create-master-skill, meta-create-campaign, meta-create-adset, meta-create-ad-with-creative

Other platforms (4)

• ga4-source-of-truth — conversions ≠ transactions, channel-subset-sum trap, attribution discipline
• shopify-order-discipline — no financial_status filter, gross-vs-net, refunds, multi-currency
• search-console-master-skill — organic search analysis + opportunity scoring
• creative-research — competitor research, evergreen + breakout winners, pattern analysis

Document generation (5)

• documents-docx-skill, documents-pptx-skill, documents-pdf-skill, documents-xlsx-skill — generate professional reports
• python-sandbox-skill — foundation for all document generation

How it works

You ask:  "Audit my Meta account"
    ↓
Claude / Codex auto-invokes the right skills by description
    ↓
Skill instructs the agent to call GoMarble MCP tools (meta_get_account_insights, etc.)
    ↓
GoMarble MCP → live Meta Ads API call (with your OAuth token)
    ↓
Agent applies the methodology + guardrails to interpret the data
    ↓
You get the answer

The plugin ships only the methodology. All live data comes from the GoMarble MCP server you authorized with /mcp (Claude) or codex mcp login gomarble.

Updating

# Claude Code
/plugin marketplace upgrade gomarble-os

# Codex CLI
codex plugin marketplace upgrade gomarble-os

The SessionStart hook also surfaces an "update available" prompt automatically the first time you start a session on an outdated version.

Repo layout

gomarble-os/
├── .claude-plugin/
│   ├── plugin.json              # Claude Code manifest
│   └── marketplace.json         # marketplace declaration
├── .codex-plugin/
│   └── plugin.json              # Codex manifest with rich install metadata
├── .mcp.json                    # remote MCP wiring (Streamable HTTP + OAuth)
├── commands/                    # 5 slash commands (Claude reads; Codex ignores)
├── hooks/
│   ├── hooks.json               # registers SessionStart hook
│   └── session-start.mjs        # MCP probe + version check + today's-date injection
├── skills/                      # 36 SKILL.md folders — both hosts read from here
└── README.md

Why one folder works for both hosts

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

Host	Manifest	Reads	Ignores
Claude Code	.claude-plugin/plugin.json	skills/, commands/, .mcp.json (mcpServers key)	.codex-plugin/
Codex	.codex-plugin/plugin.json	skills/, .mcp.json (mcp_servers key)	.claude-plugin/plugin.json, commands/

.mcp.json ships both wrapper keys with identical content so each host finds its preferred form.

Credentials

Plugin users need nothing beyond the install command. The MCP OAuth flow is handled by Claude (/mcp) and Codex (codex mcp login gomarble).

Publishing a new version (for maintainers)

# 1. Edit any SKILL.md, command, hook, or manifest
# 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 v0.X.Y"
git tag v0.X.Y
git push --follow-tags

# 4. Update the public version manifest at https://apps.gomarble.ai/plugin/version.json:
#    { "version": "0.X.Y", "released": "YYYY-MM-DD", "notes": "What changed." }

Users get the update prompt on their next session via the SessionStart hook.

SessionStart hook

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

• Injects today's date into the agent's context (lets "this week" resolve correctly)
• Probes the MCP server for reachability — warns if down
• Checks for plugin updates — compares local version to the public manifest

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, you'll see a "trust this hook" prompt. Accept once, then it runs silently.

Support

• Docs & examples: https://gomarble.ai
• Issues & feature requests: https://github.com/gomarble-ai/gomarble-os/issues
• Account / billing: https://apps.gomarble.ai

© GoMarble. All rights reserved.