growthOS Documentation

growthOS is an open-source plugin that turns Claude Code into an autonomous marketing team. 12 AI agents, 26 skills, 4 MCP servers, one /grow command.

Installation

growthOS is distributed via git clone only — it is not on the Claude Code marketplace.

What do you need?

1. Clone and install

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

The installer creates a symlink ~/.claude/plugins/growthOS → your clone and copies the brand voice template. Restart Claude Code after install.

2. Optional dependencies

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

# Node (Remotion, carousel export)
npm install

3. Docker (optional)

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

Uninstall

rm ~/.claude/plugins/growthOS

Quick Start

Everything goes through /grow:

# First run — configure your brand
/grow setup

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

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

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

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

# Or just describe what you need
/grow "I need content for our product launch next week"

Brand Voice Setup

Run /grow setup to configure your brand. The wizard writes to brand-voice.yaml (gitignored — your brand never leaks into the repo).

Configuration sections

Supported platforms

LinkedIn, Twitter/X, Reddit, Threads, GitHub, YouTube, Instagram, StackOverflow. Each has independent tone override and content limits.

Architecture

growthOS follows a CMO router pattern: every request enters through a single command (/grow), gets classified by the CMO agent via NLP, and is delegated to the appropriate specialist agent. Agents invoke skills, which may call MCP servers for external operations.

User → /grow "..." → CMO (intent classification)
                        ├── Growth Strategist    → marketing-strategy skill
                        ├── Content Creator      → content-creation + copywriting skills
                        ├── Intelligence Analyst → competitive-intelligence skill
                        ├── Visual Designer      → landing-page-design skill
                        ├── Social Publisher     → social-media + MCP social-publish
                        ├── Growth Engineer      → landing-page-design + seo-growth skills
                        ├── Carousel Designer    → instagram-carousel skill + templates
                        ├── Video Producer       → remotion-video skill + MCP remotion-render
                        └── Sales Page Architect → 8-phase pipeline (6 skills)

File structure

growthOS/
├── agents/          # 12 AI agents (AGENT.md definitions)
├── skills/          # 26 skills (SKILL.md definitions)
├── commands/        # /grow command entry point
├── hooks/           # 4 safety hooks
├── mcp-servers/     # 4 MCP servers (Python/FastMCP)
├── remotion/        # Video engine (11 compositions)
├── templates/       # HTML templates (carousels, landing pages)
├── design-intelligence/  # Visual doctrine + references
├── voice/           # Brand voice, offers, viral intelligence
├── shared-lib/      # Python shared library
└── brand-voice.yaml # Your brand config (gitignored)

CMO Router

The CMO is the single entry point for all growthOS interactions. It classifies user intent into categories and routes to the correct specialist.

Intent classification

Pipeline detection

The CMO detects multi-step intents and chains agents automatically:

• create-and-publish — Content Creator → Social Publisher
• create-and-design — Content Creator → Visual Designer
• research-and-create — Intelligence Analyst → Content Creator
• full-publish-pipeline — Research → Create → Design → Publish

Safety System

growthOS is designed with safety-first principles. Nothing publishes without your explicit approval by default.

Autonomy levels

Safety mechanisms

Anti-Slop Engine

growthOS enforces zero tolerance for generic AI output across copy and design.

Banned phrases (Tier 1 — auto-reject)

"game-changer", "revolutionary", "cutting-edge", "best-in-class", "synergy", "leverage", "disrupt", "innovative solution", "transform your", "unlock the power", "dive deep", "it's worth noting", "in today's fast-paced", "at the end of the day", "think outside the box", "move the needle", "low-hanging fruit", "paradigm shift", "holistic approach", "seamlessly integrate"

Style rules (always enforced)

• Active voice over passive
• Specific numbers over vague claims
• No clickbait headlines
• No unsupported superlatives
• Custom banned phrases via brand-voice.yaml

Visual anti-slop (design)

The Design Intelligence system has a parallel 3-tier anti-slop checklist in AI-SLOP.md. Tier 1 bans: generic gradients, Inter/Roboto as display font, stock photos, rounded corners >16px on cards, everything-centered layouts.

Agents

12 AI agents, each with a clear role. The CMO routes every /grow request to the right specialist.

Core Skills (11)

Sales Page Pipeline (6 skills)

An 8-phase pipeline that builds world-class sales pages through directed design intelligence. Every decision traces to a reference — never from AI defaults.

Video Showcase Skills (9)

Advanced video templates routed from the remotion-pro orchestrator skill.

/grow Command Reference

Complete reference for all /grow subcommands.

Design Doctrine

The Design Intelligence system ensures every visual decision is directed by references, not generated from AI defaults.

5 axioms

1. Every decision traces to a reference or psychological principle. No "I thought it looked nice."
2. Beauty serves conversion. Each pixel exists to move the user toward action.
3. The reference bank grows with every project. RLHF visual — approved designs feed the profile.
4. Restriction generates creativity. Archetypes with concrete tokens liberate, not limit.
5. Mobile-first is not optional. 70%+ of sales page traffic comes from mobile.

7 Visual Archetypes

Each archetype defines a complete visual universe: palette, typography, spacing, animation, hero pattern, and CTA style.

Reference Sites (11)

Detailed analysis of elite landing pages. Each file documents visual identity, key techniques, patterns to extract, code snippets, and anti-patterns.

Psychology Theory (5)

Research-backed principles that justify every design and copy decision.

MCP Servers (4)

External operation servers built with Python/FastMCP. Only needed for publishing, analytics, vault access, and video rendering.

Safety Hooks (4)

Remotion Engine (11 compositions)

Templates

Carousel templates (6)

HTML templates at 1080x1350 (4:5 portrait, Instagram-optimal):

Bold · Clean Educator · Dark Premium · Gradient · Minimal · Vibrant Creator

Landing page templates (3)

Bold · Gradient · Minimal

Report templates (3)

A/B Test · CRO Report · Tracking Plan

Voice System

The voice system ensures all content matches your brand. Created during /grow setup.

Components

Configuration

All config is in brand-voice.yaml (gitignored). See Brand Voice Setup for details.

Environment Variables

Copy .env.example to .env. Only needed for MCP servers and publishing.