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 ISN'T AVAILABLE IN THIS ENVIRONMENT"

Your surface does not expose the in-app plugin manager. Retyping it without the leading slash does nothing, so do not bother. Install from a real Terminal (Mac) or PowerShell (Windows) instead. Run these one at a time, then hard-quit and reopen the app:

claude plugin marketplace add asmaldigital/agency-os

claude plugin install agency-os@agency-os

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 three commands one at a time:

claude plugin marketplace add asmaldigital/agency-os

Wait for that to finish, then run:

claude plugin marketplace update agency-os

Then install the plugin itself. Adding the marketplace only makes it available to browse; this command actually installs it:

claude plugin install agency-os@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

FAST PATH (recommended)

One PowerShell command installs everything (Git, GitHub CLI, Node, Claude Code, Agency OS marketplace). Open PowerShell as Administrator and paste:

irm https://ccagency.aileadbuilder.com/install.ps1 | iex

The script handles execution policy, all prerequisites, and the OneDrive/Documents folder pitfall. Skip to Step 8 below when it finishes. If you prefer to do it manually, follow Steps 1-8 in order.

WINDOWS GOTCHAS (read first)

Third-party antivirus (RAV, Norton, McAfee, Kaspersky) often blocks npm and node during install. Pause it for 15 minutes during setup. Windows Defender is fine.
PowerShell execution policy defaults to Restricted on many Windows installs, which blocks npm.ps1. The Fast Path script fixes this automatically. Manually: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
OneDrive Documents can cause file-lock conflicts. If your Documents folder syncs to OneDrive, install Agency OS to C:\Users\you\AgencyOS instead.
Desktop App Code tab: if /plugin says "isn't available in this environment" even in Local mode after a hard quit, your Windows Desktop App build hasn't shipped plugin support yet. Use the PowerShell path below.

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 three commands one at a time in PowerShell (not inside Claude Code):

claude plugin marketplace add asmaldigital/agency-os

Wait for that to finish, then run:

claude plugin marketplace update agency-os

Then install the plugin itself. Adding the marketplace only makes it available to browse; this command actually installs it:

claude plugin install agency-os@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.

READ THIS FIRST

A new session is not a restart. This is the single most common reason people think the update did not work. You have to quit the app entirely, not just open a new chat or a new Code tab. Hard-quit Claude (Cmd+Q on Mac, or Quit from the system tray on Windows) and reopen it. Until you do, you are still running the old version.

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.

DON'T RELY ON /plugin OR /reload-plugins

On some Desktop App builds and inside the Code tab, both /plugin and /reload-plugins report "isn't available in this environment." That is expected, not a bug. It means there is no in-app way to refresh or reload the plugin in that surface. Update from a real Terminal or PowerShell window using the steps below, then fully restart the app. A hard restart is the only thing that loads the new version. /reload-plugins will not save you the restart here.

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

Refresh the marketplace listing first:

claude plugin marketplace update agency-os

Then re-run install to pull the new version. This is the step that actually upgrades it (custom marketplaces do not auto-update by default, so refreshing the listing alone is not enough):

claude plugin install agency-os@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. The update is on disk, but the session you already have open is still running the old version until you restart.

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.

Do not try /reload-plugins to skip the restart. In the Desktop App Code tab it returns "isn't available in this environment." A full restart is the only refresh.

v4.0 and up

Feeding it your calls

The single biggest quality jump in v4.0. The system learns how you actually think and talk from your real conversations, not just from the interview. Coaching calls, sales calls, podcast interviews. The more you give it, the more your content sounds exactly like you.

YOU STAY IN CONTROL

Nothing is processed automatically. The system always shows you a cost estimate and asks before it mines anything. Only share calls you have the right to share, ideally your own coaching, sales, teaching, or podcast calls.

Get a transcript

Most meeting tools export a transcript in two clicks. Plain text or markdown is perfect.

Fireflies: open the meeting, Share or the export icon, choose transcript.
Otter: open the conversation, export as Plain Text.
Fathom: open the meeting, Share, Copy transcript.
Zoom cloud: download the Audio Transcript (VTT) file.
Google Meet / Granola / Read.ai / tl;dv / Loom: use their export or copy-transcript option.

No transcript tool? Drop the raw audio or video file in instead (mp3, mp4, m4a, wav). The system transcribes it locally for free.

Get it into your workspace (two ways)

Easiest, for text transcripts: just paste the transcript straight into the chat, or attach the text file with the + button. The skill will offer to file it for you and always asks before it writes anything. You never have to find a folder.

Or drop the file in manually (required for raw audio/video, since those are transcribed on your machine). Put it in this folder, creating it if needed:

brand/[your-workspace]/raw-conversations/

Replace [your-workspace] with your actual workspace folder (for most people that is _default, or your client folder like client--acme). One transcript per file. Name them by date if you like, for example 2026-05-30-sales-call.txt.

Run the build

If you are setting up your profile for the first time, run /build-profile. If you already have a profile and are adding this layer, run /deepen-profile.

/deepen-profile

It scans the folder, shows you the cost, and asks before mining. Then it pulls your assumptions, your reframes, the way you diagnose, and the questions you ask, straight from how you actually talk.

HOW MANY

Three to five strong calls is plenty to start. Patterns that show up across more than one call are marked as high confidence, so a handful of real conversations beats one. You can always add more later and re-run.

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 isn't available in this environment" (and so is "/reload-plugins")

Expected on some Desktop App builds and inside the Code tab. The in-app plugin manager is not exposed there, so neither /plugin nor /reload-plugins will run. This is not a bug, and there is no in-app fix. Do not retype the command without the slash, that does not work either. Instead, open a real Terminal (Mac) or PowerShell (Windows) outside Claude Code and run claude plugin marketplace update agency-os then claude plugin install agency-os@agency-os, then hard-quit and reopen the app. 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.

"npm.ps1 cannot be loaded because running scripts is disabled" (Windows)

PowerShell's default execution policy blocks npm scripts. Fix it once for your user account:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Type Y to confirm. Close and reopen PowerShell. Then retry the install command.

"High-risk process blocked" by RAV / Norton / McAfee during install (Windows)

Third-party antivirus is blocking npm or node. Pause it for 15 minutes (system tray > right-click AV icon > Pause), re-run the install, then re-enable AV after. Windows Defender does not have this problem.

Desktop App says "/plugin isn't available in this environment" even in Local mode

Your Windows Desktop App build does not yet expose the plugin marketplace. Check that you are in Local mode (not Cloud / Default), do a full hard-quit (system tray > right-click Claude > Quit), reopen. If still failing, switch to the PowerShell path: run irm https://ccagency.aileadbuilder.com/install.ps1 | iex and install via Claude Code CLI instead.

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.