Daemion docs

How do I create an agent?

~5 minutes
Prerequisites: Running gateway

Agents are specialized roles that Claude takes on when you chat with them. You create them by chatting with Daemion — no YAML to write by hand.

Create an agent by chatting

Tell Daemion what kind of specialist you want. It handles the scaffold, model choice, and system prompt.

text

You: Create an agent called researcher that specializes in finding technical information

Daemion: I’ll create a researcher agent — specialized in deep technical lookups, source comparison, and synthesizing information clearly. Should I give it web search access and set the model to sonnet, or do you want opus for heavier research tasks?

Daemion scaffolds the agent folder in ~/.daemion/agents/researcher/, registers it as an extension in SQLite, and makes it available immediately — no restart required.

What gets created on disk

Every agent lives in ~/.daemion/agents/<name>/ with this structure:

text

~/.daemion/agents/researcher/ agents/ researcher.md # system prompt (with YAML frontmatter) daemion.yaml # model, permissions, memory, suggestions soul.md # personality layer (see below) .claude-plugin/ plugin.json # plugin manifest

The daemion.yaml for the researcher agent looks like this:

yaml

identity: icon: magnifying-glass color: “#6366F1”

model: sonnet # haiku | sonnet | opus

memory: engram: true groups: [auto] # ‘auto’ resolves to the agent name

projects: [all]

permissions: autonomous: [Read, Grep, Glob, Bash, Write, WebFetch, WebSearch] requires_approval: []

escalation:

  • when: “can’t resolve” to: user

suggestions:

  • “What’s the latest on [topic]?”
  • “Compare [X] vs [Y] — pros, cons, recommendation”
  • “Research [technology/company/trend] and summarize”

Agents are Claude operating in a role

Every agent — no matter how specialized — runs on Claude. The literal first line of every agent’s system prompt is:

“You are Claude, operating as a Daemion agent”

This is intentional, per Anthropic licensing. Agents are not separate AIs. They are Claude with a focused context: a system prompt, a soul, and a permission set.

What’s a soul?

Each agent has two personality layers:

  • ~/.daemion/soul.md — the base soul, shared across all agents. It captures who your user is: name, communication style, preferences, working patterns. Daemion writes this during your first conversation.
  • soul.md in the agent folder — the agent’s own personality. This is what makes researcher feel different from a general-purpose chat. It is injected into every conversation with that agent.

The researcher agent’s soul.md might look like this:

text

Soul — Researcher

You are Claude, operating as Researcher — the one who goes deep. When something needs investigation, synthesis, or comparison, that’s you.

You are curious and rigorous. You check multiple sources, note confidence levels, and distinguish between what you know and what you’re inferring. You cite your sources.

You value depth over speed. A shallow answer delivered quickly is less valuable than a thorough one. But you also know when “good enough” is good enough.

Ask Daemion to update an agent’s soul at any time: “Make researcher more concise and direct.”

Verify: send a message to the new agent

After creation, send a message through the gateway to confirm the agent responds:

bash

Start a thread with the researcher agent (use its extension ID)

curl -X POST http://localhost:3001/chat
-H “Authorization: Bearer $DAEMION_TOKEN”
-H “Content-Type: application/json”
-d ’{“agent_id”: “ext_09def789”, “content”: “What is Deno 2?”}’

Or just tap the agent in the Daemion app and send it a message. If it responds, it’s working.

API alternative: POST /extensions

If you are building tooling or automating agent creation, use the API directly:

POST /extensions Auth required

Create an agent extension. Scaffolds the disk folder in ~/.daemion/agents/<name>/ and registers the extension in SQLite.

Parameter Type Description
type REQUIRED string Must be "agent".
name REQUIRED string Agent name. kebab-case only (a-z, 0-9, hyphens).
description string Short description shown in the app.
definition.model string Model shortname: haiku, sonnet, or opus. Defaults to sonnet.
definition.system_prompt string Initial system prompt. Stored on disk, not in the database.
source string Origin label. Use "user" for manually created agents.
enabled boolean Whether the agent is active immediately. Defaults to true.
bash

curl -X POST http://localhost:3001/extensions
-H “Authorization: Bearer $DAEMION_TOKEN”
-H “Content-Type: application/json”
-d ’{ “type”: “agent”, “name”: “researcher”, “description”: “Finds and synthesizes technical information”, “definition”: { “model”: “sonnet”, “system_prompt”: “You are Claude, operating as Researcher — the one who goes deep.” }, “source”: “user”, “enabled”: true }’

A successful response returns the new extension record:

json

{ “id”: “ext_09def789”, “type”: “agent”, “name”: “researcher”, “description”: “Finds and synthesizes technical information”, “enabled”: true, “created_at”: “2026-03-31T12:00:00.000Z” }

After creating via API, call POST /reseed to sync built-in extensions from disk if needed — though agent extensions created via the API are registered immediately and do not require a reseed.

Common questions

Q Can I set the model?
Yes. Set model in daemion.yaml to haiku, sonnet, or opus. Haiku is fast and cheap; opus is slower and more capable. You can also ask Daemion: "Switch researcher to opus."
Q What's a soul?
A soul is a plain-text personality file that shapes how the agent communicates. The base soul (~/.daemion/soul.md) describes your preferences. Each agent's own soul.md describes its role and voice. Together they are injected into every conversation.
Q How do I give it tools?
Edit the permissions.autonomous list in daemion.yaml. Tools listed there run without asking. Tools in requires_approval ask first. Supported tools include: Read, Write, Bash, Grep, Glob, WebFetch, WebSearch.
Q Can I edit it later?
Yes — three ways. Ask Daemion ("Update researcher's system prompt to focus on security topics"). Edit the files in ~/.daemion/agents/researcher/ directly. Or PATCH /extensions/:id/disk-config with updated systemPrompt, soulPrompt, or model fields.

What can go wrong

Agent creation errors

400 &#123;"error": "name must be kebab-case (a-z, 0-9, hyphens)"&#125; — Agent names must be lowercase with hyphens only. My Agent and researcher_v2 are invalid. Use my-agent and researcher-v2.

400 &#123;"error": "extension already exists"&#125; — An extension with that name is already registered. Use GET /extensions?type=agent to list existing agents.

404 on chat — The agent ID in the chat request doesn’t match any registered agent. Confirm the ID from GET /extensions?type=agent.

Agent created but not visible in app — The app syncs extensions over WebSocket. If the agent doesn’t appear, pull to refresh or reconnect. The extension is in SQLite — it won’t be lost.

What’s next?