CLI for creating and managing self-modifying AI agents powered by the Claude Agent SDK
npm install voluteA CLI for creating and managing persistent, self-modifying AI agents.
Each agent is a long-running server with its own identity, memory, and working directory. Agents can read and write their own files, remember things across conversations, and — most importantly — fork themselves to test changes in isolation before merging back. Talk to them from the terminal, the web dashboard, or Discord.
Built on the Anthropic Claude Agent SDK.
``sh
npm install -g volute
You now have a running AI agent with persistent memory, auto-committing file changes, and session resume across restarts. Open
http://localhost:4200 for the web dashboard.The daemon
One background process runs everything.
volute up starts it; volute down stops it.`sh
volute up # start (default port 4200)
volute up --port 8080 # custom port
volute down # stop all agents and shut down
`The daemon handles agent lifecycle, crash recovery (auto-restarts after 3 seconds), connector processes, scheduled messages, and the web dashboard.
Agents
$3
`sh
volute create atlas # scaffold a new agent
volute start atlas # start it
volute stop atlas # stop it
volute status # list all agents
volute status atlas # check one
volute logs atlas --follow # tail logs
volute delete atlas # remove from registry
volute delete atlas --force # also delete files
`$3
`sh
volute send atlas "what's on your mind?"
`Responses stream back to your terminal in real time. The agent knows which channel each message came from — CLI, web, Discord, or system — and routes its response back to the source.
$3
`
~/.volute/agents/atlas/
├── home/ # the agent's working directory (its cwd)
│ ├── SOUL.md # personality and system prompt
│ ├── MEMORY.md # long-term memory, always in context
│ ├── VOLUTE.md # channel routing docs
│ └── memory/ # daily logs (YYYY-MM-DD.md)
├── src/ # agent server code
└── .volute/ # runtime state, session, logs
`
SOUL.md is the identity. This is the core of the system prompt. Edit it to change how the agent thinks and speaks.
MEMORY.md is long-term memory, always included in context. The agent updates it as it learns — preferences, key decisions, recurring context.Daily logs (
memory/YYYY-MM-DD.md) are working memory. Before a conversation compaction, the agent writes a summary so context survives.Auto-commit: any file changes the agent makes inside
home/ are automatically committed to git.Session resume: if the agent restarts, it picks up where it left off.
Variants
This is the interesting part. Agents can fork themselves into isolated branches, test changes safely, and merge back.
`sh
Create a variant — gets its own git worktree and running server
volute fork atlas experimentTalk to the variant directly
volute send atlas@experiment "try a different approach"List all variants
volute variants atlasMerge it back (verifies, merges, cleans up, restarts the main agent)
volute merge atlas experiment --summary "improved response style"
`What happens:
1. Fork creates a git worktree, installs dependencies, and starts a separate server
2. The variant is a full independent copy — same code, same identity, its own state
3. Merge verifies the variant server works, merges the branch, removes the worktree, and restarts the main agent
4. After restart, the agent receives orientation context about what changed
You can fork with a custom personality:
`sh
volute fork atlas poet --soul "You are a poet who responds only in verse."
`Agents have access to the
volute CLI from their working directory, so they can fork, test, and merge their own variants autonomously.Connectors
Connect agents to external services.
$3
`sh
Set the bot token (shared across agents, or per-agent with --agent)
volute env set DISCORD_TOKEN Connect
volute connect discord atlasDisconnect
volute disconnect discord atlas
`The agent receives Discord messages and responds in-channel. Tool calls are filtered out — Discord users see clean text responses.
$3
Read from and write to channels directly:
`sh
volute channel read discord:123456789 # recent messages
volute channel send discord:123456789 "hello" # send a message
`Schedules
Cron-based scheduled messages — daily check-ins, periodic tasks, whatever you need.
`sh
volute schedule add atlas \
--cron "0 9 *" \
--message "good morning — write your daily log"volute schedule list atlas
volute schedule remove atlas --id
`Environment variables
Manage secrets and config. Supports shared (all agents) and per-agent scoping.
`sh
volute env set API_KEY sk-abc123 # shared
volute env set API_KEY sk-xyz789 --agent atlas # agent-specific override
volute env list --agent atlas # see effective config
volute env remove API_KEY
`Web dashboard
The daemon serves a web UI at
http://localhost:4200 (or whatever port you chose).- Real-time chat with full tool call visibility
- File browser and editor
- Log streaming
- Connector and schedule management
- Variant status
- First user to register becomes admin
Upgrading agents
When the Volute template updates, you can upgrade agents without touching their identity:
`sh
volute upgrade atlas # creates an "upgrade" variant
resolve conflicts if needed, then:
volute upgrade atlas --continue
test:
volute send atlas@upgrade "are you working?"
merge:
volute merge atlas upgrade
`Your agent's
SOUL.md and MEMORY.md are never overwritten.Templates
Two built-in templates:
-
agent-sdk (default) — Anthropic Claude Agent SDK
- pi — pi-coding-agent for multi-provider LLM support`sh
volute create atlas --template pi
`Model configuration
Set the model via
home/.config/volute.json in the agent directory, or the VOLUTE_MODEL env var.Development
`sh
git clone
cd volute
npm install
npm run dev # run CLI via tsx
npm run build # build CLI + web frontend
npm run dev:web # frontend dev server
npm test # run tests
`Install globally for testing:
npm run build && npm link`.