# Agent Playground
```
_____ _____ _____
/\ \ /\ \ /\ \
/::\ \ /::\ \ /::\ \
/::::\ \ /::::\ \ /::::\ \
/::::::\ \ /::::::\ \ /::::::\ \
/:::/\:::\ \ /:::/\:::\ \ /:::/\:::\ \
/:::/__\:::\ \ /:::/__\:::\ \ /:::/ \:::\ \
/::::\ \:::\ \ /::::\ \:::\ \ /:::/ \:::\ \
/::::::\ \:::\ \ /::::::\ \:::\ \ /:::/ / \:::\ \
/:::/\:::\ \:::\ \ /:::/\:::\ \:::\____\ /:::/ / \:::\ ___\
/:::/ \:::\ \:::\____\/:::/ \:::\ \:::| |/:::/____/ ___\:::| |
\::/ \:::\ /:::/ /\::/ \:::\ /:::|____|\:::\ \ /\ /:::|____|
\/____/ \:::\/:::/ / \/_____/\:::\/:::/ / \:::\ /::\ \::/ /
\::::::/ / \::::::/ / \:::\ \:::\ \/____/
\::::/ / \::::/ / \:::\ \:::\____\
/:::/ / \::/____/ \:::\ /:::/ /
/:::/ / ~~ \:::\/:::/ /
/:::/ / \::::::/ /
/:::/ / \::::/ /
\::/ / \::/____/
\/____/
```
`agent-playground` is a simple CLI for running agent in a temporary playground.
It is currently supported on macOS and Linux.
## Motivation
Agent harnesses are very useful, but they are designed to be launched from a specific working directory, like a codebase or a project folder, to perform a series of tasks.
Sometimes we only want to use them for a quick operation, such as calling a remote service through MCP, or for a one-off task such as searching the web and writing a short report. In those cases, manually creating and cleaning up a temporary working directory is unnecessary friction.
`apg` (abbrv. for "agent playground") CLI solves this by letting you define a set of template working directories, i.e. playgrounds, and spin up temporary copies from them to launch an agent. When the work is done, the temporary directory is cleaned up automatically (unless you choose to keep it).
## Install
### With Cargo
```bash
cargo install agent-playground
```
`cargo install` on Windows is not supported.
### With installer script
```bash
## Usage
```bash
# initialize a playground in ~/.config/agent-playground/playgrounds
# choose a proper name for your playground, e.g. "notion" for notion MCP agent
# when git is available, this also initializes a git repository in the new playground
# `default` is reserved for the empty-playground subcommand and cannot be used as a playground id
apg init demo
# you can also initialize a playground and include specific agent config templates
apg init demo --agent claude --agent codex
# list all configured playgrounds
apg list
# run a playground with the default agent
# almost equal to `cd /some/temp/dir && claude`
apg demo
# run the default agent in an empty temporary playground
apg default
# or specify the agent to run with
apg demo --agent codex
# or specify the agent for the empty playground
apg default --agent codex
```
When the agent exits, `apg` asks whether to keep the temporary playground copy. Enter `y` to save it under the configured archive directory, or press Enter to discard it.
## Configuration layout
The CLI stores configuration under `~/.config/agent-playground`.
The actual layout on disk looks like this:
```text
~/.config/agent-playground/
├── config.toml
├── playgrounds/
│ ├── demo/
│ │ ├── apg.toml
│ │ └── ...
│ └── another-playground/
│ ├── apg.toml
│ └── ...
└── saved-playgrounds/ # default archive directory; configurable
```
`config.toml` is the root config file. These are all supported fields:
```toml
# Directory used when you choose to keep a temporary playground after the
# agent exits.
# Relative paths are resolved against ~/.config/agent-playground.
saved_playgrounds_dir = "saved-playgrounds"
# Known agents. The key is the agent id used in `apg ... --agent <id>`,
# and the value is the shell command used to launch it.
[agent]
# Built-in default entries created by `apg init`.
claude = "claude"
opencode = "opencode"
# You can also define custom commands:
# opencode = "docker run --rm -it opencode/agent:latest"
# codex = "codex"
# Default runtime options inherited by every playground unless that
# playground overrides them in its own apg.toml.
[playground]
# Default agent id for playground runs.
# This value must exist in the [agent] table.
default_agent = "claude"
# Whether to load the playground template's `.env` into the agent process
# environment when running.
# When enabled, the `.env` file itself is still not copied into the
# temporary or saved playground.
load_env = false
```
Default values when `config.toml` is first created:
- `saved_playgrounds_dir = "saved-playgrounds"`
- `[agent].claude = "claude"`
- `[agent].opencode = "opencode"`
- `[playground].default_agent = "claude"`
- `[playground].load_env = false`
Each playground directory contains a flat `apg.toml` (not nested under
`[playground]`) which can override the inherited root defaults:
```toml
# Human-readable description shown in `apg list` and `apg info`.
description = "TODO: describe demo"
# Optional playground-specific default agent id.
# If omitted, the value from config.toml [playground].default_agent is used.
# This value must exist in the root config's [agent] table.
default_agent = "codex"
# Optional playground-specific override for whether to load `.env`.
# If omitted, the value from config.toml [playground].load_env is used.
load_env = true
```
## License
MIT