GrowthOS

Autonomous marketing team for Claude Code — 9 AI agents, 20 skills, 4 MCP servers, one /grow command.

GrowthOS turns Claude Code into a full-stack growth engine: strategy, content creation, SEO, social publishing, competitive intelligence, video production, and landing page design — all orchestrated by AI agents with built-in safety controls.

Features

Installation

GrowthOS is distributed only via git clone — it is not published on the Claude Code marketplace. The install.sh script wires the cloned repo into ~/.claude/plugins/growthOS so Claude Code discovers every skill, agent, command, and hook as a real slash command (/grow, /growthOS:<skill>).

What do I need to install?

The core of GrowthOS (skills, agents, commands, hooks) is pure markdown + YAML — Claude Code reads it natively, no runtime needed. Python and Node are only required if you want the optional engines (video rendering, MCP servers, Instagram publisher, carousel export).

You don't need to install TypeScript globally — npm install pulls tsc and all types as local devDependencies for the Remotion project.

1. Clone and install

git clone https://github.com/melgarafael/growthOS.git
cd growthOS
./install.sh

What the installer does:

• Creates a symlink ~/.claude/plugins/growthOS → <your clone> (standard Claude Code plugin discovery path).
• Copies brand-voice.example.yaml → brand-voice.yaml if you don't have one yet.
• Prints next steps.

After it finishes, restart Claude Code (or open a new session) so the new plugin is loaded.

2. (Optional) Python & Node dependencies

Only required if you plan to use the MCP servers, the Remotion video engine, or the Instagram publisher:

# Python shared library (MCP servers, publisher, scripts)
pip install -e shared-lib/

# Node dependencies (Remotion, carousel export)
npm install

3. (Optional) Docker for MCP servers

If you want the MCP servers running in containers:

cp .env.example .env
# Edit .env with your API keys
docker-compose up -d

4. Run the onboarding wizard

Inside Claude Code:

/grow setup

The wizard will guide you through:

1. Setting your brand name and tagline
2. Choosing your tone of voice
3. Selecting your industry
4. Configuring target platforms

It writes to brand-voice.yaml, which all agents read to stay on-brand. That file is gitignored so your personal brand voice never ends up in the repo.

Uninstall

rm ~/.claude/plugins/growthOS

Troubleshooting — slash commands not showing up

If /grow or /growthOS:<skill> do not appear after install:

1. Confirm the symlink exists: ls -la ~/.claude/plugins/growthOS
2. Confirm the manifest: cat ~/.claude/plugins/growthOS/.claude-plugin/plugin.json
3. Fully restart Claude Code (not just reload — exit the session and reopen).
4. Inside Claude Code, run /help to list loaded plugins.

Quick Start

Once installed, everything goes through /grow:

# Start here — the setup wizard
/grow setup

# Create a growth strategy
/grow strategy "Launch our new SaaS product in Q3"

# Write content
/grow create blog "Why AI is transforming marketing"
/grow create thread "5 growth hacks for startups"
/grow create newsletter "Monthly product update"

# Create visual content
/grow carousel "10 tips for better landing pages"
/grow video reel "Quick product demo"

# Analyze competitors
/grow analyze "competitor X social strategy"

# Research trends
/grow research "AI marketing tools 2026"

# Generate a landing page
/grow create landing "New feature launch page"

# Or just describe what you need — the CMO agent routes it
/grow "I need content for our product launch next week"

Skills Reference

Core Skills (11)

Showcase Skills (9)

Advanced video templates for specific use cases:

Agents

GrowthOS uses a CMO router that automatically delegates to specialist agents:

Configuration

Environment Variables

Copy .env.example to .env and configure:

Note: Social platform API keys are only needed if you want to publish directly. GrowthOS works perfectly for content generation without any API keys.

Brand Voice

Copy brand-voice.example.yaml to brand-voice.yaml and customize:

brand:
  name: "Your Brand"
  tagline: "Your tagline"
  tone:
    - professional
    - conversational
  audience: "Your target audience"
  industry: "Your industry"

Or just run /grow setup and the wizard handles it for you.

Architecture

growthOS/
├── plugin.json                  # Plugin manifest (entry point)
├── brand-voice.example.yaml     # Brand config template
├── .env.example                 # Environment variables template
│
├── agents/                      # 9 AI agents
│   ├── cmo/                     #   CMO — intent router
│   ├── growth-strategist/       #   Strategic planning
│   ├── content-creator/         #   Content production
│   ├── intelligence-analyst/    #   Competitive intel
│   ├── visual-designer/         #   Visual assets
│   ├── social-publisher/        #   Social media ops
│   ├── growth-engineer/         #   Technical growth
│   ├── carousel-designer/       #   Carousel generation
│   └── video-producer/          #   Video production
│
├── skills/                      # 20 specialized skills
│   ├── marketing-strategy/      #   Core skills (11)
│   ├── copywriting/
│   ├── seo-growth/
│   ├── content-creation/
│   ├── social-media-management/
│   ├── competitive-intelligence/
│   ├── video-production/
│   ├── landing-page-design/
│   ├── platform-mastery/
│   ├── instagram-carousel/
│   ├── remotion-video/
│   ├── remotion-pro/            #   Showcase skills (9)
│   ├── showcase-before-after/
│   ├── showcase-course-trailer/
│   ├── showcase-data-story/
│   ├── showcase-feature-highlight/
│   ├── showcase-product-demo/
│   ├── showcase-social-proof/
│   ├── showcase-tech-terminal/
│   └── showcase-walkthrough/
│
├── mcp-servers/                 # 4 MCP servers (Python/FastMCP)
│   ├── mcp-social-publish/      #   Publish to 5 platforms
│   ├── mcp-social-discover/     #   Trend & analytics
│   ├── mcp-obsidian-vault/      #   Knowledge base CRUD
│   └── mcp-remotion-render/     #   Video rendering
│
├── shared-lib/                  # Python shared library
│   └── growthOS_shared/
│       ├── config.py            #   Brand voice config (Pydantic)
│       ├── intent_router.py     #   NLP intent classification
│       ├── autonomy.py          #   Progressive autonomy + kill switch
│       ├── token_manager.py     #   Rate limiting
│       ├── circuit_breaker.py   #   Circuit breaker pattern
│       ├── audit_logger.py      #   Action audit trail
│       ├── carousel_generator.py#   HTML carousel generation
│       └── scheduler.py         #   Content scheduling
│
├── hooks/                       # 4 safety hooks
│   ├── audit-logger.md          #   Log all actions
│   ├── circuit-breaker.md       #   Failure protection
│   ├── preview-before-publish.md#   Preview before sending
│   └── dry-run-guard.md         #   Block real calls in dry-run
│
├── commands/                    # CLI commands
│   └── grow/                    #   /grow entry point + setup
│
├── remotion/                    # Video rendering engine
│   └── src/
│       ├── Root.tsx             #   Composition registry
│       ├── compositions/        #   11 video compositions
│       └── components/          #   Reusable animation components
│
└── templates/                   # Output templates
    ├── carousels/               #   6 HTML carousel templates
    ├── content/                 #   Content templates
    └── landing/                 #   Landing page templates

Safety and Security

GrowthOS is designed with safety-first principles:

See SECURITY.md for the responsible disclosure policy.

Development

Prerequisites

• Node.js 18+
• Python 3.10+
• Claude Code CLI

Setup

# Clone and wire into Claude Code
git clone https://github.com/melgarafael/growthOS.git
cd growthOS
./install.sh

# Python shared library (development mode)
pip install -e shared-lib/

# Node.js dependencies (Remotion, carousel export)
npm install

# Run tests
cd shared-lib && pytest

What lives in the repo vs. what stays local

GrowthOS ships the structure needed to run on any project, but per-project content is gitignored so your personal brand never leaks into the repo. Cloners get empty folders (preserved via .gitkeep) and fill them in locally.

Contributing

See CONTRIBUTING.md for development guidelines, coding standards, and PR process.

Roadmap

• Core agent system (CMO + 8 specialists)
• 20 marketing skills
• Remotion video engine (11 compositions)
• Instagram carousel generator (6 templates)
• Obsidian vault integration
• Brand voice system
• Safety hooks (audit, circuit breaker, dry-run, preview)
• Live social publishing (Twitter, LinkedIn, Reddit, GitHub, Threads)
• Analytics dashboard
• A/B testing framework
• Multi-language content support

License

MIT — see LICENSE for details.