Sandboxed installs

One sandbox per project. Whichever agent you run.

A sandbox is a complete agent config of its own — commands, settings, MCP servers and workspace token — living under ~/.sandboxes/<name>. Your global agent stays exactly as it was, and the project's memory never mixes with anyone else's.

Hand the install to an agent → /claude-guide

curl · bash

curl -fsSL https://raw.githubusercontent.com/atvirokodosprendimai/agentsmemory/main/clients/claude-code/install.sh | bash

Why isolate

Two modes, one installer

Every command below works either way. Add --sandbox to get an isolated config, or leave it off to wire the kit into the agent you already run.

One project, one config

~/.sandboxes/<name>

Commands, settings and MCP servers scoped to this project
Its own workspace token — revoke it without touching the others
Delete the directory and the sandbox is gone, cleanly

Your global agent, untouched

aiagentmemory install

No sandbox? The kit merges into the config you already run
Managed blocks merge — your own memory file is preserved
Switch modes any time; the installer is idempotent

Per agent

What lands where

The three CLIs are structurally alike and diverge in exactly two places: how they authenticate an HTTP MCP server, and whether they have hooks at all. Pick yours.

The reference install: native MCP, native hooks, and a memory file that resolves imports.

install

aiagentmemory install --sandbox <name>

launch

aiagentmemory run <name>

Config variable: CLAUDE_CONFIG_DIR
Global config dir: ~/.claude
Slash commands: commands/ — invoked /M, /am, /load-skill
Memory file: CLAUDE.md — @imports the protocol beside it
Session gate: settings.json — Stop hook
Our MCP: native: claude mcp add --transport http, bearer header

--recommended also installs the codebase-memory MCP and the eidos + codex plugins.
A sandbox keeps its own commands, settings, MCP servers and token — nothing leaks into ~/.claude.

Don't start from nothing

Bring your logins with you

A fresh sandbox is signed out, with no MCP servers, plugins or skills. Copy that setup in once, or link the credentials so one login serves every sandbox you have.

Inherit your setup

aiagentmemory install --agent pi --sandbox acme --copy

Logins, MCP servers, plugins, skills and settings, copied in
History, logs and caches stay behind — the bulk never travels
Nothing already in the sandbox is overwritten

Share one login

aiagentmemory install --agent pi --sandbox acme --shared-auth

Credential files link back to the global config
Re-authenticate once; every sandbox sees it
Claude on macOS already shares its keychain

Copied credentials are real credentials: the sandbox can act as you until you sign it out. Copy your own config, not a colleague's.
Linked credentials survive an agent that writes them in place. If one ever replaces the link with a file, aiagentmemory run says so at launch and prints the command that re-shares it.

Pin a project

Your repo remembers how it launches

Record the launch once and open it with aiagentmemory load. The agent and its flags are a team decision and get committed; the sandbox name is a fact about your machine and never leaves it — so a teammate who calls their sandbox something else still gets the same setup.

Committed — the team's half

aiagentmemory init --sandbox acme --agent codex -- --model opus

Writes .aiagentmemory: which agent, and the flags it launches with
Everything after -- is stored verbatim and replayed by load
Safe to commit — it names no sandbox and carries no token

Machine-local — your half

~/.sandboxes/agents

One line per project: its absolute path, then your sandbox name
Never in the repository, so it needs no .gitignore entry
An entry on a parent directory covers every project beneath it

When more than one layer names a sandbox, the most specific wins: --sandbox beats $AIAGENTMEMORY_SANDBOX, which beats ~/.sandboxes/agents, which beats .aiagentmemory.local, which beats the committed .aiagentmemory. Every launch prints which one it used.
Both lookups walk up from where you are, so load works from any subdirectory of the project — and one entry on a parent directory can pin a whole tree of repositories, with a per-project entry still overriding it.
With no sandbox on any layer, load stops and tells you to run init. It never falls back to your global config: launching unpinned would defeat the point while looking like success.

Side by side

The whole matrix

Same kit, three shapes. The last row is the one that matters: pi has no MCP client of its own, so the installer ships a bridge extension that registers our tools natively.

Where the agentsmemory kit lands in each agent CLI
Piece	Claude Code	Codex	pi
Config variable	CLAUDE_CONFIG_DIR	CODEX_HOME	PI_CODING_AGENT_DIR
Global config dir	~/.claude	~/.codex	~/.pi/agent
Slash commands	commands/ — invoked /M, /am, /load-skill	prompts/ — invoked /prompts:M	prompts/ — invoked /M
Memory file	CLAUDE.md — @imports the protocol beside it	AGENTS.md — protocol inlined (no import directive)	AGENTS.md — protocol inlined (no import directive)
Session gate	settings.json — Stop hook	hooks.json — Stop hook	none native — the checkpoint ships in the extension
Our MCP	native: claude mcp add --transport http, bearer header	native: codex mcp add --bearer-token-env-var	bridged: extensions/agentsmemory.ts registers each remote tool natively

More than one

Install for every agent at once

A sandbox is one directory that all three agents can share: they never collide on a filename, so --agent all gives you a single config three CLIs can open. --agent both stays what it always was — Claude and Codex.

Kit README on GitHub ↗

shell

aiagentmemory install --agent all --sandbox <name> --recommended

aiagentmemory install --sandbox <name>: Create an isolated config at ~/.sandboxes/<name>.
aiagentmemory install --agent pi|codex|both|all: Choose which agent CLIs the kit is wired into.
aiagentmemory run [--agent codex|pi] <name>: Open an agent in that sandbox — args pass through to the CLI.
aiagentmemory wrap [--agent codex|pi]: Open an agent against its own global config instead.
aiagentmemory init --sandbox <name> [-- agent flags]: Record this project's launch: agent and flags committed, sandbox name kept local.
aiagentmemory load [-- extra flags]: Open the recorded agent and sandbox from anywhere inside the project.