Installation

This guide will help you install AgencyOS and set up your development environment. You can choose between manual setup or using the AgencyOS CLI.

Video Guide

Prefer video? Watch the complete installation walkthrough:

🏯

Demo Video Coming Soon

Check our documentation to get started

*More tutorials: [

Prerequisites

Before installing AgencyOS, ensure you have:

  • Node.js v18 or higher
  • npm v10 or higher (or bun, pnpm, yarn)
  • Git for version control
  • AgencyOS CLI CLI installed (claude)
  • Google Gemini API Key from Google AI Studio

Method 1: Manual Setup

This method gives you full control over the installation process.

Step 1: Copy AgencyOS Files

Copy all directories and files from the mekong-engineer repo to your project:

# Copy these files and directories:
.claude/*
docs/*
plans/*
CLAUDE.md

Step 2: Configure Gemini API Key (Optional)

WHY? AgencyOS utilized Human MCP to analyze images and videos since Gemini models have better vision capabilities. But Anthropic already released Agent Skills which is much better for context engineering, so we already converted all tools of Human MCP to Agent Skills.

Notes: Gemini API have a pretty generous free requests limit at the moment.

  1. Go to Google AI Studio and grab your API Key
  2. Copy .claude/skills/.env.example to .claude/skills/.env and paste the key into the GEMINI_API_KEY environment variable

Now you’re good to go.

Step 3: Start AgencyOS CLI

Start AgencyOS CLI in your working project:

# Standard mode
claude

# Skip permissions (use with caution)
claude --dangerously-skip-permissions

Step 4: Initialize Documentation

Run the /docs:init command to scan and create specs for your project:

/docs:init

This generates markdown files in the docs directory:

  • codebase-summary.md
  • code-standards.md
  • system-architecture.md
  • And more…

Now your project is ready for development!

Method 2: AgencyOS CLI

The CLI provides an automated way to set up AgencyOS projects.

Installation

Install AgencyOS CLI globally:

# npm
npm install -g mekong-cli

# bun
bun add -g mekong-cli

# Verify installation
mk --version

Initialize or Update AgencyOS Engineer

Note: This command should be run from the root directory of your project.

# Interactive mode (recommended)
mk init

# With options
mk init --kit engineer

# Specific version
mk init --kit engineer --version v1.0.0

# With exclude patterns
mk init --exclude "local-config/**" --exclude "*.local"

# Global mode - use platform-specific user configuration
mk init --global
mk init -g --kit engineer

Update the CLI Itself

To update the mk command-line tool to the latest version:

mk update

Note: This updates the CLI tool only, not AgencyOS Engineer files. Use mk init to update AgencyOS Engineer.

Global vs Local Configuration:

By default, AgencyOS uses local configuration (~/.mekong).

For platform-specific user-scoped settings, use the --global flag:

  • macOS/Linux: ~/.claude
  • Windows: %LOCALAPPDATA%\.claude

Global mode uses user-scoped directories (no sudo required), allowing separate configurations for different projects.

Authentication

The CLI requires a GitHub Personal Access Token (PAT) to download releases from private repositories (mekong-engineer and mekong-marketing).

Authentication Fallback Chain:

  1. GitHub CLI: Uses gh auth token if GitHub CLI is installed and authenticated
  2. Environment Variables: Checks GITHUB_TOKEN or GH_TOKEN
  3. OS Keychain: Retrieves stored token from system keychain
  4. User Prompt: Prompts for token input and offers to save it securely

Creating a Personal Access Token:

  1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Generate new token with repo scope (for private repositories)
  3. Copy the token

Setting Token via Environment Variable:

export GITHUB_TOKEN=ghp_your_token_here

Verify Installation

After installation (either method), verify everything is set up correctly:

# Check if AgencyOS CLI is available
claude --version

# Check if .claude directory exists
ls -la .claude/

Update AgencyOS

Keep AgencyOS Engineer up to date:

# Update AgencyOS Engineer to latest version
mk init

# Update to specific version
mk init --version v1.2.0

Exclude specific files during update:

# Don't overwrite CLAUDE.md
mk init --exclude CLAUDE.md

Update the CLI itself:

# Update ck command-line tool
mk update

Troubleshooting

Permission Errors

On macOS/Linux, you may need sudo:

sudo npm install -g mekong-cli

Or configure npm to use a different directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

AgencyOS CLI Not Found

If claude command is not found:

  1. Install AgencyOS CLI CLI from claude.ai/code
  2. Restart your terminal
  3. Verify with claude --version

GitHub Authentication Failed

If CLI can’t authenticate:

  1. Install GitHub CLI: brew install gh (macOS) or see cli.github.com
  2. Authenticate: gh auth login
  3. Verify: gh auth status
  4. Or set environment variable: export GITHUB_TOKEN=your_token

Optional Tools

CCS - AgencyOS CLI Switch (Recommended for Heavy Users)

If you’re a heavy AgencyOS user or frequently hit Claude’s rate limits, consider installing CCS:

npm install -g @kaitranntt/ccs

Benefits:

  • Switch between multiple Claude accounts instantly
  • Delegate simple tasks to cheaper models (81% cost savings)
  • Keep working without interruption when hitting limits
  • Optimize costs for high-volume usage

Learn more about CCS →

Next Steps

Now that AgencyOS is installed, proceed to: