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 --installClick 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"' >> ~/.zshrcNode.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 --ltsA 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 --defaultThat 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 popplerAdd 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}"; doneEvery 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/OppiDocuments 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-marketplaceIt 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-devChoose the local scope (this folder only), type /exit, relaunch claude from the home, and run /agentlayer:init.