Workspace
Your Agent's Workspace
The workspace is a directory where your agent keeps everything it needs: its identity, personality, instructions, memory, and installed skills. By default, it lives at ~/.config/babyclaw/workspace/, but you can change this with the workspace.root config option.
On first run, BabyClaw creates a set of template files in the workspace. These are starting points -- you and the agent will fill them in together during the bootstrap conversation.
Workspace files
| File | What it's for |
|---|---|
IDENTITY.md | The agent's name, creature type, vibe, and emoji |
SOUL.md | Personality, boundaries, and behavioral guidelines |
USER.md | Information about you -- name, timezone, preferences |
AGENTS.md | Workspace rules, conventions, and operating instructions |
TOOLS.md | Notes about local tools -- SSH hosts, API quirks, device names |
HEARTBEAT.md | Checklist for periodic heartbeat checks |
BOOTSTRAP.md | First-run onboarding script (deleted after the agent completes it) |
The bootstrap process
When the workspace is brand new, BabyClaw creates a BOOTSTRAP.md file. The first time you message the agent, it reads this file and walks through a getting-to-know-you conversation: picking a name, figuring out its personality, learning about you.
Once bootstrap is done, the agent deletes BOOTSTRAP.md. It won't come back unless you create a completely fresh workspace.
Customizing your agent
You can edit any of these files at any time. The agent reads them at the start of each session.
Want a different personality? Edit SOUL.md. The default template encourages the agent to be helpful without being performative, have opinions, and be resourceful. Change it to whatever works for you.
Want to give the agent context about you? Edit USER.md with your name, timezone, projects you're working on, or anything else that helps.
Want to change how the agent operates? Edit AGENTS.md. This is where conventions, safety rules, and workspace-specific instructions live.
Memory
The workspace also holds your agent's memory:
memory/YYYY-MM-DD.md-- daily memory files, created automatically after conversationsMEMORY.md-- curated long-term memory that the agent maintains over time
See Memory for more on how this works.
Skills
Installed skills live in skills/ inside the workspace. Each skill is a subdirectory with a SKILL.md file. The agent discovers them automatically.
See Skills for how to install and manage skills.
Directory structure
A workspace after some use might look like this:
workspace/
├── AGENTS.md
├── IDENTITY.md
├── SOUL.md
├── USER.md
├── TOOLS.md
├── HEARTBEAT.md
├── MEMORY.md
├── memory/
│ ├── 2026-02-18.md
│ ├── 2026-02-19.md
│ └── 2026-02-20.md
└── skills/
├── some-skill/
│ └── SKILL.md
└── another-skill/
└── SKILL.md