Setup Guide

Get Started with Agency OS

A step-by-step guide for Mac and Windows. No coding experience required. Budget around 30 minutes for your first setup. After this, it takes seconds to start.

What is this?

Agency OS runs inside Claude Code on your computer

Claude Code is an AI assistant that runs on your computer, either through the Claude Desktop App or through Terminal (Mac) / PowerShell (Windows). It reads, writes, and manages files directly on your machine. Agency OS is a plugin that gives Claude Code specialist skills and commands purpose-built for growing your agency.

TIP

You do not need to be a developer to use this. You type commands in plain English. It does the work.

Before you start

Prerequisites

You need two accounts before installing Claude Code.

Claude Account

A paid Claude plan. Sign up at claude.ai

Pro $20/mo, Max $100/mo, or Max $200/mo

GitHub Account

Free account at github.com. Send our team your GitHub username so we can add you as a collaborator on the Agency OS repo.

Free

CLARIFY

What GitHub authentication does: During setup you will run gh auth login. This only logs you in to GitHub so your machine can pull the Agency OS plugin. You are not connecting or giving access to any of your own repositories.

NOTE

Windows users: You also need Git for Windows installed. Download and install it before proceeding.

Step-by-step

Installation

Select your operating system and follow the steps.

RECOMMENDED

If you prefer a visual interface over the terminal, use the Claude Desktop App. Same functionality, friendlier experience.

Download the Claude Desktop App

Go to claude.ai/download and download the app for your Mac or Windows computer.

Open the app and sign in with your Claude account (Pro or Max plan required).

Install GitHub CLI (one-time terminal step)

You need this for plugin access. Follow the instructions for your operating system only.

MAC If you are on a Mac

Open Terminal (Cmd+Space, type Terminal, Enter).

FIRST

If you do not have Homebrew installed, run this first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After Homebrew is installed, run:

brew install gh && gh auth login

Select: GitHub.com > HTTPS > Login with a web browser. Follow the prompts.

WIN If you are on Windows

Open PowerShell (Windows key, type PowerShell, Run as administrator).

winget install GitHub.cli

Close and reopen PowerShell. Then run:

gh auth login

Select: GitHub.com > HTTPS > Login with a web browser. Follow the prompts.

POWERSHELL TIP

Copy and paste can feel invisible in PowerShell. When you highlight text, press Ctrl+C. It may look like nothing happened, but the copy worked. Same for typing. Trust it and press Enter.

Open the Code tab and select a folder

In the Claude Desktop App, click "Code" at the top (next to Chat and Cowork).

Click "Select a folder" and create one new folder called Agency OS in your Documents. Select it.

Do not create separate folders for each of your brands. Agency OS will create those subfolders for you.

Switch to Local mode (important)

Before you do anything else in the Code tab, click the mode selector at the bottom of the window and choose Local, not Cloud / Default.

Claude Desktop App mode selector showing Local selected, with Cloud / Default, Remote Control, and SSH options

WHY

Cloud mode runs inside Anthropic's cloud sandbox. Anything you install there does not touch your computer. Agency OS needs to install on your machine, so you must be in Local mode. If you skip this, everything below will appear to work but nothing will actually install locally.

Install Agency OS plugin

Step A: In the Code tab chat input, paste:

/plugin marketplace add asmaldigital/agency-os

Step B: Wait for Step A to finish. Then paste:

/plugin install agency-os@agency-os

IF IT SAYS "/plugin IS NOT AVAILABLE"

Remove the leading slash and try again: plugin marketplace add asmaldigital/agency-os then plugin install agency-os@agency-os. One or the other will work depending on how the Desktop App interprets it.

Restart the Claude Desktop App (hard quit)

The plugin will not fully register until you close the app completely and reopen it. Closing the window is not enough.

Mac:

Right-click the Claude icon in your Dock and choose Quit. Or press Cmd+Q while Claude is the active app.

Windows:

Close the window, then open the system tray at the bottom right of your taskbar (click the ^ arrow if icons are hidden). Right-click the Claude icon there and choose Quit or Exit. If it is still running, open Task Manager (Ctrl+Shift+Esc), find Claude, and End task.

Reopen the app and go back to the Code tab.

Verify the plugin is installed

In the Code tab chat input, ask:

Is Agency OS installed?

Or type /agency-os and see if it autocompletes. If it does, you are installed.

Start Agency OS

Type in the Code tab:

/agency-os

If you do not already have a CLAUDE.md file in the folder, accept the prompt to create one. If you do have one, leave it as is.

The system walks you through everything from here, starting with Build 1: Brand DNA.

Open Terminal

Open Finder (the smiling face in your Dock). Go to Applications > Utilities > Terminal. Double-click to open it.

TIP

Shortcut: Press Command + Spacebar to open Spotlight. Type Terminal. Press Enter.

Install Homebrew (package manager)

Paste this into Terminal and press Enter. It will ask for your Mac password (the one you use to log in to your computer).

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After it finishes, it will show "Next steps" with commands to add Homebrew to your PATH. Run each of those commands one at a time.

Install GitHub CLI

brew install gh

Wait for it to finish. You will see a beer mug icon when it is done.

Log in to GitHub

gh auth login

Select: GitHub.com > HTTPS > Login with a web browser. It will open your browser. Log in and enter the code shown in Terminal.

Install Claude Code

curl -fsSL https://claude.ai/install.sh | bash

Wait for it to finish. You will see "Claude Code successfully installed!" and "Installation complete!"

If it says ~/.local/bin is not in your PATH, run the command it shows you, then close and reopen Terminal.

Type claude and press Enter. You will see the Welcome screen. Select "Claude account with subscription" and follow the browser prompts to log in.

Claude Code welcome screen with login options

Your browser will open. Select your organization and confirm access.

When you see "Build something great. You're all set up for Claude Code." you are authenticated.

Create your workspace folder and open Terminal from it

mkdir ~/Documents/Agency\ OS

This is where all your Agency OS files will live.

Open Finder, navigate to Documents, find the Agency OS folder. Right-click it and select "New Terminal at Folder."

Right-click Agency OS folder in Finder and select New Terminal at Folder

Your Terminal will open already inside the Agency OS folder.

Install the Agency OS plugin

In Terminal (not inside Claude Code), run these two commands one at a time:

claude plugin marketplace add https://github.com/asmaldigital/agency-os

Wait for that to finish, then run:

claude plugin marketplace update agency-os

Important: Run these in Terminal itself, not as a message inside Claude Code. If Claude Code is open, type /exit first.

Start Claude Code and run Agency OS

In the Terminal that is open in your Agency OS folder, type claude and press Enter.

claude

Claude Code will open and welcome you.

Claude Code welcome screen showing Welcome back Muhammad

Verify Agency OS is installed: ask Is Agency OS installed? or type /agency-os and see if it autocompletes.

Type "run agency os" or /agency-os to start. If you do not already have a CLAUDE.md in the folder, accept the prompt to create one. If you do, leave it as is.

Agency OS running setup and creating CLAUDE.md rules

Once setup is complete, you have access to all Agency OS commands. Type "show me all agency os commands" to see the full list.

All Agency OS commands listed including 6 builds, agency growth, and creative tools

Install Git for Windows

Download from git-scm.com/downloads/win. Run the installer with default settings. This is required before Claude Code will work.

Open PowerShell

Press Windows key. Type PowerShell. Click "Run as administrator".

Install GitHub CLI

winget install GitHub.cli

Close and reopen PowerShell after this installs.

Log in to GitHub

gh auth login

Select: GitHub.com > HTTPS > Login with a web browser. It will open your browser. Log in and enter the code shown in PowerShell.

Install Claude Code

irm https://claude.ai/install.ps1 | iex

Close and reopen PowerShell after installation.

Create your workspace folder

mkdir $HOME\Documents\Agency OS

This is where all your Agency OS files will live. The plugin will install into this folder.

Install the Agency OS plugin

Open PowerShell from your Agency OS folder first. Navigate to the folder in File Explorer, click the address bar, type powershell, press Enter.

Run these two commands one at a time in PowerShell (not inside Claude Code):

claude plugin marketplace add https://github.com/asmaldigital/agency-os

Wait for that to finish, then run:

claude plugin marketplace update agency-os

Important: Run these in PowerShell itself, not as a message inside Claude Code. If Claude Code is open, type /exit first.

POWERSHELL TIP

Copy and paste can feel invisible in PowerShell. When you highlight text, press Ctrl+C — it may look like nothing happened, but the copy worked. Same for typing. Trust it and press Enter.

Start Claude Code and verify Agency OS

Still in PowerShell inside your Agency OS folder, type:

claude

Claude Code opens. Verify the plugin: ask Is Agency OS installed? or type /agency-os and see if it autocompletes.

Then run /agency-os to start. If you do not already have a CLAUDE.md in the folder, accept the prompt to create one. If you do, leave it as is.

You are ready

Starting Agency OS

Installation is done. Here is how you start Agency OS every time.

Open the Claude Desktop App

Launch the Claude app from your Applications (Mac) or Start Menu (Windows).

Click the Code tab

At the top of the app, click "Code" (next to Chat and Cowork).

Confirm you are in Local mode

Check the mode selector at the bottom of the window. It should say Local. If it says Cloud / Default, click it and switch to Local.

Select your Agency OS folder

Click "Select a folder" and choose the Agency OS folder you created in Documents.

Run Agency OS

Type /agency-os in the chat input and press Enter. Agency OS will check your setup and guide you from there.

Open Finder

Click the Finder icon in your Dock (the smiling face at the bottom of your screen).

Go to your folder

In the sidebar, click Documents. Find the folder called Agency OS

Open Terminal here

Right-click (or Control-click) the folder. Scroll down the menu and look for "New Terminal at Folder" near the bottom.

Start Claude Code

Type claude and press Enter. You are now inside Claude Code.

Run your first command

Type run agency os and press Enter. Agency OS will check your setup and guide you from there.

Open File Explorer

Press Windows key + E to open File Explorer.

Go to your folder

Navigate to Documents > Agency OS

Open PowerShell here

Click in the address bar at the top. Type powershell and press Enter. PowerShell opens in your folder.

Start Claude Code

Type claude and press Enter. You are now inside Claude Code.

Run your first command

Type run agency os and press Enter. Agency OS will check your setup and guide you from there.

Daily use

Key Commands

Type these inside Claude Code. Start with run agency os or /agency-os to begin. Then work through the builds in order.

Start Here

/agency-os

Launch the full guided build (6 builds in sequence). Start here.

/agency-os:setup

First-time setup. Creates the CLAUDE.md rules file.

The 6 Builds

/agency-os:build-profile

Brand DNA interview. Story, voice, methodology, goals.

/agency-os:build-avatar

Ideal Customer Avatar with deep psychographic profiling.

/agency-os:build-offer

Irresistible offer with value stack, pricing, guarantees.

/agency-os:build-funnel

Full funnel: landing page, emails, SMS, lead magnet, GHL setup.

/agency-os:build-content

90-piece content system with 30-day calendar.

/agency-os:build-lead-ads

Meta Lead Form campaigns with GHL automations.

Agency Growth

/agency-os:sell-agency

Build your client acquisition pipeline (outreach, proposals, GHL pipeline).

/agency-os:deliver-client

30-day delivery plan for a signed client.

/agency-os:market-research

Market intelligence: competitor signal, industry state, platform trends.

/agency-os:competitor-research

Alias for market-research. Full competitor + industry + platform scan.

/agency-os:audit-funnel

Visually analyze and audit any landing page or funnel for conversion gaps.

Creative and Copy

/agency-os:write-copy

Elite direct-response copy (emails, landing pages, sales letters).

/agency-os:write-ads

Meta/Facebook/Instagram ad copy with proven hook formulas.

/agency-os:write-vsl

Video Sales Letter scripts using 8 proven frameworks.

/agency-os:create-visuals

AI-generated marketing images and videos.

/agency-os:build-video-prompt

Shot-by-shot video prompts for Seedance 2.0 via HeyGen.

/agency-os:create-lead-magnet

Interactive lead magnet: quiz, calculator, scorecard, or assessment.

/agency-os:create-bot

GHL Conversation AI bot for lead qualification or booking.

/agency-os:critique

Pressure-test any deliverable before shipping it.

Content Operations

/agency-os:repurpose

Turn one piece of content into 15-30+ platform-native assets with visuals.

/agency-os:write-blog

SEO + AI-optimized blog post with mandatory keyword research.

/agency-os:create-video

Marketing videos with HeyGen AI avatars.

Multiple Brands or Products

/agency-os:add-product

Add a new product or brand to the active workspace.

/agency-os:list-products

List all products in the active workspace.

/agency-os:status

Show workspace and per-product build status.

/agency-os:language

Switch the workspace language (English or German).

Utilities

/agency-os:dream

Save session to memory and clear context. Use when your chat gets long.

/agency-os:health-check

Scan skills for compatibility with the current plugin version.

/agency-os:rebuild-dashboard

Regenerate the workspace dashboard from current build artifacts.

/agency-os:rebuild-deck

Regenerate a product's PowerPoint deck from current build artifacts.

TIP

You can also just type in plain English. "Write me 5 LinkedIn posts about leadership" works. Claude figures out the right skill.

Staying current

Updating Agency OS

In most cases you do not have to do anything. Starting a new Claude Code session or reopening the Desktop App will automatically pull the latest version of the plugin.

USUALLY AUTOMATIC

Terminal (Mac / Windows): Exit your current Claude Code session (type /exit or press Ctrl+C), then type claude to start a new session. The plugin updates on startup.

Desktop App: Hard-quit the Claude Desktop App and reopen it. The plugin updates when the Code tab loads.

If auto-update does not work

Run these manually in Terminal (Mac) or PowerShell (Windows). Not inside Claude Code.

Pull the latest version

If you have not added the marketplace source yet, run this first:

claude plugin marketplace add https://github.com/asmaldigital/agency-os

You only need to do this once. If you already ran it during installation, skip to Step 2.

Update the plugin

claude plugin marketplace update agency-os

This updates skills, commands, and plugin files. Your brand data (everything in brand/) is never touched by updates.

Restart so the new version loads

After a manual update, restart so Claude picks up the changes.

Terminal: exit your current session (/exit or Ctrl+C), then type claude again.

Desktop App: hard-quit and reopen. On Mac, right-click the Dock icon and choose Quit. On Windows, open the system tray (click ^ if hidden), right-click Claude, and choose Quit.

Common issues

Troubleshooting

Plugin installed but commands do not appear

You are probably in Cloud / Default mode in the Desktop App Code tab. Cloud mode runs in a sandbox. Switch to Local mode at the bottom of the Code tab, then reinstall the plugin. All prior installs in Cloud mode will not be on your machine.

"/plugin is not available in this environment"

Remove the leading slash and try again. Paste plugin marketplace add asmaldigital/agency-os without the slash. If that also fails, hard-quit the Desktop App and restart it. On Mac: right-click the Dock icon and Quit. On Windows: open the system tray (click ^ if icons are hidden), right-click Claude, and Quit.

"fatal: early EOF" during plugin install

Git download failed mid-transfer. Run these in Terminal / PowerShell to fix it, then retry:

git config --global http.postBuffer 524288000 git config --global core.compression 0

"command not found: claude"

Claude Code installed but your terminal does not know where to find it. Run the PATH command that was shown during installation, then close and reopen Terminal.

"command not found: brew" (Mac only)

Homebrew installed but the PATH was not set. Run the "Next steps" commands that Homebrew showed after installation. Then close and reopen Terminal.

PowerShell copy or paste looks broken (Windows)

PowerShell gives no visible feedback when you highlight text and press Ctrl+C, or when you paste in long commands. It still worked. Trust it and press Enter. If nothing runs, paste again and try Enter once more.

Claude is stuck or not responding

In a terminal: press Ctrl+C. Then type claude to start a new session. In the Desktop App: hard-quit and reopen.

Accidentally closed the terminal

No problem. Open a new one from your folder. Type claude --resume to continue where you left off.

Smart quotes breaking commands (copy-paste from WhatsApp/Messages)

Messaging apps replace straight quotes with curly quotes, which break commands. Type commands manually, or paste into a plain text editor first.

"HTTPS authentication failed" when installing the plugin

Run gh auth login first. Select GitHub.com > HTTPS > Login with browser. Then retry the plugin install.

Plugin not showing commands after install

Hard-quit the Desktop App (not just close the window) or Ctrl+C out of the terminal Claude Code session. Reopen and verify with /agency-os. Plugins only load on a fresh start.