Skip to content

Directory Structure

Leo uses a home directory at ~/.leo/ that holds config, state, and the default workspace.

Directory Layout

~/.leo/
├── leo.yaml                    # Leo config
├── workspace/                  # Default workspace
│   ├── USER.md                 # Your profile (created during setup)
│   ├── prompts/                # Task prompt files
│   └── config/
│       └── mcp-servers.json    # MCP server configuration
├── agents/                     # Default agent workspace (for templates)
└── state/                      # Runtime state and logs
    ├── sessions.json           # Session ID mappings
    ├── agents.json             # Ephemeral agent records (for restart recovery)
    ├── task-history.json       # Task execution history
    ├── service.log             # Service log output
    ├── service.pid             # Background process PID file
    └── leo.sock                # Daemon Unix socket for CLI IPC

Key Paths

~/.leo/leo.yaml

The main configuration file. See Configuration for details.

~/.leo/workspace/

The default workspace directory. Tasks use this workspace unless they specify their own workspace field. The workspace is passed to Claude via --add-dir so the assistant can read and write files here.

~/.leo/workspace/USER.md

A user profile filled in during setup. Included in the assistant's context so it knows who you are, your role, preferences, and timezone.

Operational instructions and skills

Leo no longer writes CLAUDE.md or skills/*.md into the workspace. Instead, every agent — regardless of harness or whether the web UI is enabled — gets Leo's built-in leo_skill MCP tool, which serves the same operational how-to (managing tasks, reading logs, controlling the daemon, dispatching agents) on demand instead of as always-loaded workspace files. A small nudge pointing the agent at leo_skill is injected into its system prompt at launch.

~/.leo/workspace/config/mcp-servers.json

MCP server configuration passed to Claude via --mcp-config. Configure integrations like Google Calendar, Gmail, or custom tools here.

~/.leo/agents/

Default base directory for ephemeral agent workspaces. When you dispatch /agent coding owner/repo, the repo is cloned into ~/.leo/agents/repo/. Templates can override this with their own workspace field.

For worktree spawns (leo agent spawn ... --worktree <branch>), the canonical clone stays at ~/.leo/agents/<repo>/ and each branch gets its own checkout under:

~/.leo/agents/.worktrees/<repo-short>/<branch-slug>/

Multiple agents can run in parallel against the same repo without stepping on each other's working tree. The agentstore record stores both paths — workspace (the worktree) and canonical_path (the shared clone).

~/.leo/state/

Runtime files managed by Leo:

  • sessions.json -- task/agent name to Claude session UUID mappings (for --resume)
  • agents.json -- ephemeral agent records, used to restore agents after daemon restart
  • task-history.json -- execution history for scheduled tasks
  • service.log -- output from the daemon (all supervised agents)
  • service.pid -- PID file for the background service
  • leo.sock -- Unix socket for CLI-to-daemon IPC

Custom Workspaces

Tasks and templates can each specify their own workspace:

tasks:
  repo-check:
    workspace: ~/projects/my-app

templates:
  coding:
    workspace: ~/agents

When no workspace is specified, tasks use ~/.leo/workspace/, and templates use ~/.leo/agents/.