Skip to main content
This tutorial customizes the Scout agent from your first agent — any agent group works, just swap the folder and --id. An agent has three customization surfaces:
  1. Personality and rules — groups/<folder>/CLAUDE.local.md, the agent’s editable persistent memory
  2. Brain — model, reasoning effort, and other container config fields, edited with ncl
  3. Capabilities — packages and MCP servers, which go through the approval flow covered in self-modification
One file you will not edit: groups/<folder>/CLAUDE.md. The host regenerates it on every container spawn from a shared base plus skill and MCP fragments, and mounts it read-only into the container. Anything you write there gets clobbered. CLAUDE.local.md is the file that’s yours (and the agent’s).
1

Personality, the conversational way

The simplest path is to just tell the agent:
pnpm run chat scout "scout, from now on answer in haiku and sign off as 'Scout'"
The self-customize skill (on every agent by default) teaches the agent that CLAUDE.local.md edits are free — no approval needed — so it writes the rule into its own groups/scout/CLAUDE.local.md through the read-write workspace mount. The current conversation follows the rule immediately because you just said it; the file is what makes it stick for every future session.Check what it wrote:
cat groups/scout/CLAUDE.local.md
2

Personality, the direct way

You can edit the same file yourself — useful for longer instructions you’d rather paste than dictate:
groups/scout/CLAUDE.local.md
## Style

- Answer in haiku
- Sign off as "Scout"

## Standing rules

- Always confirm before deleting anything
When does this take effect? Instructions load when a container spawns, so a warm container mid-conversation won’t pick up your edit. Either wait — containers exit after idling, and the next message spawns a fresh one — or force it now:
ncl groups restart --id <agent-id>
If you’d rather be guided than edit files, run /customize in Claude Code from your NanoClaw checkout. It’s an interactive skill: it asks what you want to change, hands off to a dedicated skill when one exists (/add-telegram, /manage-channels, /manage-mounts, …), and otherwise routes the change to the right surface — the agent group’s memory file for persona, container config for runtime behavior, wirings for triggers.
As of v2.1.4 the /customize skill’s own text still points persona edits at the composed groups/<folder>/CLAUDE.md. Follow this tutorial instead: edit CLAUDE.local.md — anything written to the composed file is clobbered at the next spawn.
3

Swap the brain

Model and reasoning effort live in the agent group’s container config, not in any file. Update them with ncl:
ncl groups config update --id <agent-id> --model sonnet --effort low
  • --model takes an alias (sonnet, opus, haiku) or a full model ID. Unset means the SDK default.
  • --effort is one of low, medium, high, xhigh, max.
Config values are read at every spawn, so a running container keeps its old config — the change applies to the next container automatically. To force it now:
ncl groups restart --id <agent-id>
A cheap-and-fast Scout (--model haiku --effort low) is great for routing or lookup duty in a multi-agent swarm; keep opus with higher effort for agents that do real work. The same command also takes --assistant-name, --provider, and more — see the container config reference.
4

Verify

Ask Scout something and confirm the haiku rule and the model change both took:
pnpm run chat scout "which model are you running on?"
You can also peek at the composed file to see why it’s off-limits:
cat groups/scout/CLAUDE.md

<!-- Composed at spawn — do not edit. Edit CLAUDE.local.md for per-group content. -->
@./.claude-shared.md
@./.claude-fragments/module-self-mod.md
...
It’s nothing but a header and imports — the shared base plus per-skill fragments. Your text isn’t in it because it doesn’t need to be: Claude Code auto-loads CLAUDE.local.md alongside CLAUDE.md on every spawn.

​
What you changed

Two surfaces, two mechanisms: personality went into a file the agent and you co-own (CLAUDE.local.md), the brain went into a DB row (container_configs). Both are read at container spawn — edits apply to the next container, and ncl groups restart forces one now. The third surface — capabilities — works differently because it can change what the agent is able to do, so it goes through admin approval.

​
Next steps

Last modified on June 10, 2026