AgentLayer▸docs
Start here

Install by hand

Every step the Quickstart runs, one at a time. For Windows, for starting with Codex, and for seeing each step.

The Quickstart is the short path: one line on macOS or Linux. This page is the same result by hand. Use it on Windows, when you start with Codex, or when you want to see every step.

Three parts, each done once: the prerequisites per machine, a home per agent, and the plugin per host. Each tool links to its own install page, which always carries the current command; copy it from there.

Prerequisites

Two version floors apply on every system: the Claude Code version the plugin needs (claude update brings an older install current) and Bun 1.4.4 or newer (bun upgrade). Setup checks both and stops if one is older.

Pick your system. The choice sticks across the docs. On Linux or WSL2, follow the macOS tab, with your package manager in place of xcode-select and Homebrew.

Git

xcode-select --install

Click through the installer. Then tell git who you are. The agent's version history commits under this name; without one, it uses a name local to the agent's folder:

git config --global user.name "Your Name" && git config --global user.email "you@example.com"

Your host

Install from the Claude Code setup page (Native Install tab); it updates itself. It lands in ~/.local/bin, which a fresh Mac doesn't have on its PATH. If claude --version says command not found in a new terminal:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Node.js

Install fnm from its GitHub page, following the macOS install there. It installs through Homebrew, so install Homebrew first (the Helpers step below) if you don't have it. Then, in a new terminal:

fnm install --lts

A Node you already have from another installer works too.

Bun

Install from bun.sh. It adds itself to ~/.zshrc, but only when that file already exists; on a Mac without one it prints two lines to add instead, so run those.

uv and Python

Install uv from docs.astral.sh/uv (the standalone installer). It lands in ~/.local/bin and updates itself with uv self update. Then, in a new terminal:

uv python install --default

That installs the current Python and makes it python and python3 in your shell, leaving the system and Homebrew Pythons alone. If it asks for --preview, add it.

Helpers

Install Homebrew. It asks for your Mac password (typing shows nothing). When it finishes, run the Next steps it prints: they put Homebrew on your PATH, the step most often missed. Then:

brew install poppler

Add gh to the line if you plan to turn on the GitHub pack. Attaching screenshots to issues needs gh 2.99 or later.

CotEditor

Install from coteditor.com or the App Store.

MarkEdit

Install from its GitHub page or the App Store.

Default apps

Make CotEditor the default for .txt and .json files, and MarkEdit for .md files. For each kind, select a file of that kind in Finder, choose File → Get Info, pick the app under Open with, and click Change All.

cmux

cmux draws with Ghostty's engine and reads its settings, so install Ghostty first. Then install cmux from cmux.com, and launch your agent from a cmux terminal. The setup guide compares your Ghostty and cmux settings with the recommended ones and shows only what's missing. Once cmux is installed, setup offers to switch on the AgentLayer sidebar, already ticked when setup runs inside cmux.

Check

Quit and reopen Terminal so the PATH changes load, then:

for c in git node bun uv python3 claude; do v=$($c --version 2>/dev/null | head -1); printf '%-7s %s\n' "$c" "${v:-MISSING}"; done

Every line should show a version, and python3 should be uv's, not the system's 3.9. On Codex, swap claude for codex.

The question mark beside each step says what that piece is for. Setup checks all of these and stops with a pointer if a required one is missing.

You never install a browser yourself. Setup installs the plugin's packages, and Chromium for the browser tools comes with them.

Pick a home

The home is the folder the agent's brain lives in. Every host is launched from it. Give the agent a new folder of its own, outside any git repository.

mkdir -p ~/Documents/Agents/Oppi && cd ~/Documents/Agents/Oppi

Documents synced to iCloud or OneDrive?

That's fine: the brain syncs like any folder, and History keeps its version history in a local folder the sync can't touch. Say yes when macOS asks whether your terminal may access Documents.

Install the plugin

Launch claude from the home, log in when the browser opens, and answer Yes to "Do you trust the files in this folder?" (dismissing it quietly disables the plugin). Then, inside the session:

/plugin install agentlayer --marketplace AgentLayer1/agentlayer-agent-marketplace

It adds the marketplace and opens the plugin's details. Choose the local scope, so the plugin is on for this folder only, the home, and loads whenever you launch from there. Then type /exit.

Relaunch claude from the home and run /agentlayer:init. Its first step installs the plugin's packages, which takes a few minutes and about 300 MB. If that install can't run, setup stops and prints the command for your terminal with the exact path.

What setup asks next, and the relaunch that ends it, are on What setup asks.

Starting from a seed bundle?

A teammate's export gives you a zip that pre-loads the agent's name, character, and starting knowledge. Install as above, then hand the zip to setup when it asks. See Seed bundles.

From your own fork

Contributors run the plugin from their own clone, which doubles as a marketplace named agentlayer-dev. Fork and clone first, as on Contributing, then:

Launch claude from the home, then:

/plugin marketplace add ~/Developer/agentlayer-agent
/plugin install agentlayer@agentlayer-dev

Choose the local scope (this folder only), type /exit, relaunch claude from the home, and run /agentlayer:init.

On this page