Runtime layout

The runtime root holds global configuration, agent content and state, plugin packages, logs, and OAuth credentials.

init creates the runtime root, the global config/ directory, and the agents/ directory.

Global configuration

config/ holds runtime-wide settings and state.

• system.toml — optional global settings, currently only timezone.
• plugins.toml — the plugin list.
• plugins/<name>.toml — per-plugin configuration.
• openai-codex/ — OpenAI Codex OAuth credentials, one file per auth id.
• migrations.json — applied configuration migration state.
• backups/<migrationId>/ — immutable backups of files changed by migrations.

Agents

Agents live below agents/<slug>/; each agent owns its instructions, memory blocks, skills, task files, and channel configuration.

• core.md — required base instructions.
• blocks/ — required memory blocks (soul.md, identity.md, person.md, long-term.md, style-notes.md) plus optional conditional/*.md blocks.
• config/engine.toml — required inference provider configuration.
• config/tools.toml — required tool enablement.
• config/sandbox.toml — optional command-execution sandbox configuration.
• config/conditions.toml — optional conditional block and path access rules.
• config/heartbeat.toml — optional heartbeat configuration.
• config/cron.toml — optional scheduled jobs.
• config/channels/discord.toml — optional Discord integration.
• config/plugins/<name>.toml — per-agent plugin configuration.
• memories/ — agent memory files.
• skills/<slug>/SKILL.md — reusable skill documents.
• tasks/ — scheduled task files, including HEARTBEAT.md.
• workspace/ — the agent's working area.
• state/<plugin-slug>/ — persistent plugin state.
• sessions.db — the agent's SQLite session database.
• images/ — persisted media referenced by sessions.
• discord-commands.hash — registered Discord command fingerprint.
• discord-presence.json — persisted desired Discord status and custom status message.

Startup

Agents are started concurrently, so startup waits for the slowest agent rather than for all of them in turn. Startup reads each agent's lightweight session index but does not restore session histories or media. The runtime hydrates a persisted session when a channel, scheduler, target resolution, or session operation first uses it. Most of the wait is the Discord gateway handshake, which takes a few seconds per bot regardless of how much session history the agent has.

Configuration migration and plugin loading stay sequential and complete before any agent starts. Effective startup time is therefore the slowest single agent plus the shared preparation, and it does not grow with the number of configured agents. Log lines from different agents interleave during startup; each line still names its agent.

If one agent has invalid configuration, the whole startup fails and no agent is left running. Fix the reported file and start again.

Logs

Runtime logs are written under logs/ as daily rolling JSON files.

Configuration

Configuration is TOML-only.

Use cireilclaw dry-run to validate startup configuration without starting the host or writing runtime state.

Live reload

The running runtime watches agent configuration files and the global config/system.toml file. Changes to system.toml timezone settings apply to subsequent turns and Discord-rendered timestamps. Changes to plugins.toml, plugin code, or channels/discord.toml still require a full runtime restart.