Adding another agent
A second agent takes about five minutes of setup, because your computer is already set up. Step by step, no coding needed.
In short
A second agent needs only a folder, the plugin switched on there, and a name, because your computer is already set up. On macOS or Linux, the short way in Set it up runs the installer again with the new name.
Your first agent took a while: installing tools, the plugin, its packages. None of that happens again. A new agent needs only three things: a folder of its own, the plugin switched on in that folder, and a name.
Each agent has its own memory, tasks, and personality. Nothing one agent learns shows up in another. A common setup:
| Agent | Folder | Job |
|---|---|---|
| Oppi | ~/Documents/Agents/Oppi | Personal life, family, side projects |
| Scout | ~/Documents/Agents/Scout | Client work |
The examples below add Scout. Swap in your own name wherever you see it.
What you can skip
| Step from your first install | Again? |
|---|---|
| Prerequisites: Git, Claude Code, Node.js, Bun, uv, helpers | No, they're per computer |
| Logging in to Claude Code | No, unless this agent should bill a different account (see below) |
Adding the marketplace (/plugin marketplace add) | No, your computer remembers it |
Installing the plugin's packages (bun install) | No, every agent shares them |
Creating a folder, switching the plugin on there, running init | Yes, that's this page |
Pick a name
Give every agent a different name and a different emoji. The name is how the agent introduces itself, and it appears in the session banner, on the dashboard, and in reports. The emoji signs its briefings and standups. With two agents both called Oppi, you can't tell at a glance which one you're talking to.
- Use letters, numbers, spaces, or hyphens:
Scout,Sage,Acme Assistant. - Name the folder after the agent, so
Scoutlives in~/Documents/Agents/Scout. The folder is what keeps the agents apart, so a matching name avoids mix-ups later. - Pick an emoji that isn't 🐙, which is Oppi's.
More on how names work: Naming your agent.
Set it up
The short way, on macOS and Linux
Run the setup guide again with the new name:
curl -fsSL https://agentlayer.one/install.sh | bash -s -- --name ScoutIt checks the new folder, shows the commands to create it and switch the plugin on there, and ends with the line that starts setup with that name offered as the default. Pick up at step 4 and keep it. The steps below do the same by hand.
Create the agent's folder
Open a new terminal window and run:
mkdir -p ~/Documents/Agents/Scout && cd ~/Documents/Agents/ScoutStart the new folder empty. Don't copy your first agent's folder: that copies its memory, name, and history too. To start from your first agent's personality and setup instead, see Start from your first agent.
Switch the plugin on in this folder
In the same terminal, start Claude Code:
claudeIt asks "Do you trust the files in this folder?". Answer Yes: saying no quietly turns the plugin off. You're already logged in, so no browser opens.
Then type:
/plugin install agentlayer --marketplace AgentLayer1/agentlayer-agent-marketplaceIt opens the plugin's details: choose the local scope, which switches it on for this folder only. Then type /exit.
Running the plugin from your own fork? Use /plugin install agentlayer@agentlayer-dev instead, and choose the local scope when it shows the plugin's details.
Start again and run the setup wizard
claudeThen type:
/agentlayer:initThe wizard checks your computer, finds everything already in place, and starts asking questions.
Give it its own name
The first question is "What should this agent be called?", and the suggested answer is Oppi. Don't take it: choose Something else and type the new name, Scout.
Because the name is new, the wizard then asks for an emoji (pick a different one from your other agents) its colors (four pairs, each shown in its own colors, or two hex codes of your own), and an avatar (an image file or link, or skip).
Answer the rest for this agent's job rather than your first agent's: its role, the company it works for, the projects it handles, the code it can reach. Every question after the name can be skipped and filled in later.
Restart the agent
When the wizard finishes, type /exit, then start it again from its folder:
cd ~/Documents/Agents/Scout && claudeIf it asks you to trust the marketplace, accept. Your new agent greets you by its new name.
Using Codex too?
Create the agent with Claude Code as above, and answer Yes when the wizard asks whether you also run Codex from this home. Then start codex from the agent's folder and trust it, as the Codex page shows.
Its own bill
Out of the box, every agent uses the Claude account you're logged into, so all their usage counts against one plan. To give an agent its own account, for example a work account for a client agent, follow Billing per agent. It takes about ten minutes, and from then on you start that agent with agent instead of claude.
Switching between agents
You pick the agent by the folder you start it from. Open one terminal tab per agent:
cd ~/Documents/Agents/Oppi && claudecd ~/Documents/Agents/Scout && claudeBoth can run at the same time. Each one only ever reads and writes its own folder, so their memories never mix, even when they work on the same code. An agent on its own bill starts with agent in place of claude.
If you use Obsidian, open each agent's folder as its own vault.
How agents stay apart
The plugin's code lives once on your computer. Each agent is a folder of its own, and the folder you start from decides which agent you get. Nothing has to be configured to keep them apart.
~/Documents/Agents/Oppi/ # personal projects, journals, life ops
~/Documents/Agents/Scout/ # client work, professional persona
~/Documents/Agents/Sage/ # SEO-focused, only the SEO pack configuredKeep agents under ~/Documents/Agents/ and code under ~/Developer/, never one inside the other. Many agents can then work on one code tree, and syncing your Documents folder never drags repos along. The full layout is on Workstation.
Start from your first agent
Want Scout to begin with Oppi's personality, rules, and skill setup, without Oppi's personal memory? Make a seed bundle from Oppi first: in Oppi's session, ask it to "make a seed bundle" (the seed skill). It walks you through what to include and makes a zip. Then hand that zip to Scout's wizard when it asks "Starting from a teammate's seed bundle?". See Seed bundles.
Other ways to set one up
Inside an existing project
You have a repo with its own AGENTS.md or CLAUDE.md, and you want the agent's memory and tasks in that same folder. Start your host in the repo and run init there. When the wizard says the folder looks like a code project, choose Here anyway. It never touches a root CLAUDE.md, and it adds its manual below your own text in an existing AGENTS.md.
A team-shared agent
Put the agent in a team repo, commit the identity files (AGENTS.md, SOUL.md, IDENTITY.md, .claude/, knowledge/), and gitignore settings.local.json. Every teammate gets the same agent and trusts the plugin once on their host.
For a teammate who should start from your agent and then go their own way, use a seed bundle instead.
Good to know
- Each agent has its own settings. Keys and packs (SEO, GitHub, databases) are set up per agent. Run the
configure-skillsskill in each agent that needs them. - Updating the plugin. Pull the new version once, then run the
upgradeskill in each agent, since each folder has its own files to bring up to date. See Updating. - Start agents from their folder only. A session started anywhere else loads no agent and remembers nothing. See the one convention.
- Never set an agent's settings machine-wide. A value in your user-level settings or shell profile reaches every agent, and
AGENT_HOMEthere sends every session to one brain. Per-agent settings go in that agent's own folder. See Configuration.
If something's off
Most problems come from starting in the wrong folder or taking the default name; find what you see below.