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

Category	What You Get
9 AI Agents	CMO (router), Growth Strategist, Content Creator, Intelligence Analyst, Visual Designer, Social Publisher, Growth Engineer, Carousel Designer, Video Producer
20 Skills	Marketing Strategy, Copywriting, SEO Growth, Content Creation, Social Media, Competitive Intel, Video Production, Landing Pages, Platform Mastery, Instagram Carousel, Remotion Video, Remotion Pro, + 8 Showcase templates
4 MCP Servers	Social Publish (Twitter, LinkedIn, Reddit, GitHub, Threads), Social Discover (analytics), Obsidian Vault (knowledge base), Remotion Render (video)
Safety System	Dry-run by default, progressive autonomy (4 levels), audit logging, circuit breaker
Video Engine	11 Remotion compositions for reels, explainers, product demos, walkthroughs
Carousel Engine	6 HTML templates (1080x1350) — Minimal, Bold, Gradient, Educator, Dark Premium, Vibrant
Brand Voice	YAML config for tone, audience, vocabulary, anti-slop filters

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

If you want to…	You need
Use `/grow`, skills, agents (strategy, copy, content, analysis)	nothing beyond Claude Code
Render Remotion videos or export carousels to PNG	Node 18+ (`npm install` inside the repo)
Run the MCP servers, the Instagram publisher, or the Python scripts	Python 3.10+ (`pip install -e shared-lib/`, plus `playwright install chromium` for the IG publisher)
Everything	*Node 18+ and* Python 3.10+**

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:

Setting your brand name and tagline
Choosing your tone of voice
Selecting your industry
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:

Confirm the symlink exists: ls -la ~/.claude/plugins/growthOS
Confirm the manifest: cat ~/.claude/plugins/growthOS/.claude-plugin/plugin.json
Fully restart Claude Code (not just reload — exit the session and reopen).
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)

Skill	What It Does	Trigger Example
Marketing Strategy	Growth frameworks, OKRs, campaign planning, AARRR funnels	`/grow strategy "Q3 plan"`
Copywriting	AIDA, PAS, 4U formulas, CTA patterns, emotional triggers	`/grow create copy "headline for launch"`
SEO Growth	Keyword research, on-page audit, content clusters, E-E-A-T	`/grow create seo "audit our blog"`
Content Creation	Blog posts, newsletters, docs, editorial workflows	`/grow create blog "topic"`
Social Media Management	Platform strategies, scheduling, community management	`/grow create social "launch campaign"`
Competitive Intelligence	SWOT analysis, market trends, competitor tracking	`/grow analyze "competitor X"`
Video Production	Scripts, storyboards, video SEO, thumbnail concepts	`/grow video script "product demo"`
Landing Page Design	Conversion-optimized HTML, hero sections, A/B variants	`/grow create landing "feature Y"`
Platform Mastery	Algorithm knowledge per platform (YouTube, LinkedIn, X, etc.)	`/grow research "LinkedIn algorithm"`
Instagram Carousel	6 carousel structures, slide blueprints, engagement triggers	`/grow carousel "10 tips"`
Remotion Video	Storyboard-to-composition mapping, frame calculations	`/grow video reel "quick tip"`

Showcase Skills (9)

Advanced video templates for specific use cases:

Skill	Use Case
Remotion Pro	Advanced video compositions with custom animations
Showcase: Before/After	Transformation comparisons (9:16 vertical)
Showcase: Course Trailer	Educational course promos
Showcase: Data Story	Animated statistics and data visualization
Showcase: Feature Highlight	Product feature spotlights
Showcase: Product Demo	Full product walkthroughs (16:9)
Showcase: Social Proof	Testimonials and social proof reels
Showcase: Tech Terminal	CLI/terminal demonstration videos
Showcase: Walkthrough	Step-by-step app tutorials (16:9)

Agents

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

Agent	Role	When It Activates
CMO	Routes intent to the right specialist	Every `/grow` command
Growth Strategist	Strategic planning, frameworks, OKRs	Strategy requests
Content Creator	Writes blogs, threads, newsletters	Content creation
Intelligence Analyst	Competitor analysis, market research	Analysis requests
Visual Designer	Carousels, landing pages, visual assets	Visual content
Social Publisher	Platform-specific content, publishing	Social media tasks
Growth Engineer	Technical SEO, landing page code	Technical growth
Carousel Designer	Instagram carousel design and generation	Carousel requests
Video Producer	Video scripts, Remotion compositions	Video requests

Configuration

Environment Variables

Copy .env.example to .env and configure:

Variable	Required	Description
`GROWTHOS_TWITTER_API_KEY`	For Twitter	Twitter/X API key
`GROWTHOS_LINKEDIN_TOKEN`	For LinkedIn	LinkedIn access token
`GROWTHOS_REDDIT_CLIENT_ID`	For Reddit	Reddit app client ID
`GROWTHOS_GITHUB_TOKEN`	For GitHub	GitHub personal access token
`GROWTHOS_THREADS_TOKEN`	For Threads	Threads API token
`GROWTHOS_VAULT_PATH`	No	Obsidian vault path (default: `./vault`)
`GROWTHOS_AUTONOMY_LEVEL`	No	`supervised` \| `assisted` \| `delegated` \| `autonomous`
`GROWTHOS_DRY_RUN`	No	`true` \| `false` (default: `true`)

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:

Feature	Description
Dry-run mode	Enabled by default — no real API calls until you disable it
Progressive autonomy	4 levels: `supervised` → `assisted` → `delegated` → `autonomous`
Kill switch	Instantly revoke all autonomous permissions
Audit logging	Every action recorded in `.growthOS/audit/`
Circuit breaker	Auto-stops on repeated API failures
Preview hook	See exactly what will be published before it goes live
Path validation	Vault operations prevent directory traversal attacks
Safe rendering	Remotion uses subprocess isolation to prevent injection

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.

Path	Structure committed?	Content committed?
`voice/` (golden doc, transcriptions, virals, preferences)	yes	no — personal
`design-system/` (briefs, HTML, revisions)	yes	no — personal
`assets/` (logos, photos, screenshots, icons)	yes	no — personal
`brand-voice.yaml`	example only	no — personal
`output/{approved,carousels,exports,reviews,revisions}`	yes	no — runtime
`out/` (rendered videos)	yes	no — runtime
Playwright artifacts, browser profiles, `.growthos/`	—	no — runtime
`skills/`, `agents/`, `commands/`, `hooks/`, `mcp-servers/`, `remotion/`, `shared-lib/`, `templates/`	yes	yes — reusable framework

Contributing

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

Roadmap

License

MIT — see LICENSE for details.

Navigation Menu

Repository files navigation

GrowthOS

Features

Installation

What do I need to install?

1. Clone and install

2. (Optional) Python & Node dependencies

3. (Optional) Docker for MCP servers

4. Run the onboarding wizard

Uninstall

Troubleshooting — slash commands not showing up

Quick Start

Skills Reference

Core Skills (11)

Showcase Skills (9)

Agents

Configuration

Environment Variables

Brand Voice

Architecture

Safety and Security

Development

Prerequisites

Setup

What lives in the repo vs. what stays local

Contributing

Roadmap

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
agents		agents
assets		assets
boletim		boletim
commands		commands
deploy		deploy
design-intelligence		design-intelligence
design-system		design-system
docs		docs
hooks		hooks
mcp-servers		mcp-servers
out		out
output		output
publisher		publisher
remotion		remotion
review-server		review-server
sales-page-preview		sales-page-preview
scripts		scripts
shared-lib		shared-lib
skills		skills
templates		templates
voice		voice
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
brand-voice.example.yaml		brand-voice.example.yaml
docker-compose.yml		docker-compose.yml
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
plugin.json		plugin.json
pyproject.toml		pyproject.toml
tsconfig.json		tsconfig.json
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

GrowthOS

Features

Installation

What do I need to install?

1. Clone and install

2. (Optional) Python & Node dependencies

3. (Optional) Docker for MCP servers

4. Run the onboarding wizard

Uninstall

Troubleshooting — slash commands not showing up

Quick Start

Skills Reference

Core Skills (11)

Showcase Skills (9)

Agents

Configuration

Environment Variables

Brand Voice

Architecture

Safety and Security

Development

Prerequisites

Setup

What lives in the repo vs. what stays local

Contributing

Roadmap

License

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages