gomarble-agent

gomarble-agent

The GoMarble marketing agent for Claude Code and Codex CLI. One install command wires the host to the GoMarble MCP server (OAuth) and ships:

• 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 only)
• A SessionStart hook that checks MCP reachability and prompts to update when a new plugin version is released

Install

npx gomarble-agent

That's it. It installs to whichever hosts are present (Claude Code, Codex, or both), and prints the next step.

After install:

• Claude Code: open Claude, run /mcp, click "Authorize" for gomarble (browser OAuth, one-time).
• Codex CLI: restart Codex, then run codex mcp login gomarble.

Install for one host only

npx gomarble-agent --claude     # Claude Code only
npx gomarble-agent --codex      # Codex CLI only

Uninstall

npx gomarble-agent uninstall
npx gomarble-agent uninstall --claude
npx gomarble-agent uninstall --codex

Alternative: install from GitHub (no npm)

npx github:gomarble-ai/gomarble-agent

What it does

User runs `npx gomarble-agent`
      ↓
CLI copies plugin files to ~/.claude/plugins/gomarble-agent and
~/.codex/plugins/gomarble-agent, and updates ~/.agents/plugins/marketplace.json
      ↓
Plugin's .mcp.json wires the host to https://apps.gomarble.ai/map-api/sse
      ↓
First session: SessionStart hook probes the MCP server + checks for updates
      ↓
User authorizes OAuth (one-time, in browser)
      ↓
MCP tools available + 37 skills auto-invoke based on what the user asks

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 auto-route the agent.

Repo layout (for maintainers)

gomarble-agent/
├── .claude-plugin/plugin.json   # Claude Code manifest
├── .codex-plugin/plugin.json    # Codex manifest (with skills/mcpServers/interface pointers)
├── .mcp.json                    # MCP server config — both `mcpServers` and `mcp_servers` keys
├── commands/                    # 5 slash commands (Claude reads; Codex ignores)
├── hooks/
│   ├── hooks.json               # registers SessionStart hook
│   └── session-start.mjs        # probes MCP + version check + injects today's date
├── skills/                      # 37 skills (both hosts read from here)
│   └── <slug>/SKILL.md
├── bin/
│   └── install.mjs              # the CLI that runs when users do `npx gomarble-agent`
├── package.json
├── README.md
└── .gitignore

Publishing a new version

# 1. Edit skills/<slug>/SKILL.md, commands/*.md, hooks, or manifests as needed.

# 2. Bump version + publish
npm version patch         # patch / minor / major — bumps package.json + creates a git tag
git push --follow-tags
npm publish

# 3. Update https://apps.gomarble.ai/plugin/version.json so existing users see the update prompt:
#    { "version": "0.1.1", "released": "2026-05-26", "notes": "What changed." }

Why both hosts share one folder

Both Claude Code and Codex look for their manifest in a dedicated subfolder:

Host	Manifest	Ignores
Claude Code	.claude-plugin/plugin.json	.codex-plugin/
Codex	.codex-plugin/plugin.json	.claude-plugin/

Everything else is shared:

• skills/ — skills/<name>/SKILL.md is the format both hosts expect
• .mcp.json — Claude reads the mcpServers key, Codex reads mcp_servers. We ship both with identical content
• commands/ — Claude picks up slash commands here; Codex doesn't have a commands/ concept, so it just ignores the folder

The SKILL.md frontmatter has both name: (required by Codex) and description: (used by both auto-invocation systems).

SessionStart hook — what it does

Every session, before the first message, hooks/session-start.mjs runs once and:

• Injects today's date so prompts like "this week" resolve correctly.
• Probes the GoMarble MCP server for reachability — warns the user if it's down.
• Checks for plugin updates — compares local version to https://apps.gomarble.ai/plugin/version.json. If outdated, prints the update command.

For the version check to surface updates to users, host a tiny manifest at the configured URL:

{
  "version": "0.1.1",
  "released": "2026-05-26",
  "notes": "What changed in this release."
}

Both Claude and Codex treat plugin hooks as non-managed — on first install, users see a "trust this hook" prompt before session-start.mjs runs. They click Accept once, then it runs silently from then on.

Credentials

Plugin users need nothing beyond running npx gomarble-agent. The OAuth flow on the MCP is handled by Claude Code (/mcp) and Codex (codex mcp login gomarble). Maintainers don't need any credentials either — skills are edited directly in this repo.

Known caveats

• mcp_servers vs mcpServers — .mcp.json ships both wrapper keys with identical content. If Codex ever rejects the file because of the extra mcpServers top-level key, drop the camelCase block.
• /sse URL with type: "http" — the MCP URL ends in /sse but is configured as Streamable HTTP (type: "http"). If Claude Code rejects, switch to type: "sse" in .mcp.json.