Named Agents

This page covers everything you need to create, configure, and dispatch persistent AI agents in Huginn.

What a named agent is

A named agent is a persistent persona with its own model, system prompt, memory vault, and allowed tools. Think of it like a team member you define once and call on by name.

You define an agent once. After that it shows up in the agent list, participates in delegation, and accumulates its own long-term memory across every session you use it in.

Huginn ships with three built-in agents — Chris (planner), Steve (coder), and Mark (reviewer) — but these are just examples. You can create as many agents as you want with any specialization.

Creating an agent

Natural language

The fastest way to spin up a new agent:

create an agent named Elena, a security-focused code reviewer who never writes code

Huginn creates the agent file, sets the system prompt from your description, and makes the agent available immediately.

Slash command

From the TUI or web UI chat input:

/agents new

This opens a wizard that walks through name, model, and persona one field at a time. Press Enter to confirm each step.

To skip the wizard and create an agent in one line:

/agents create Elena claude-sonnet-4-6

JSON file

Drop a .json file in ~/.huginn/agents/. The web UI picks it up without a restart. The TUI reads agent files at launch — restart to pick up new agents.

Here is a complete example for a security-reviewer agent:

{
  "name": "Elena",
  "model": "claude-sonnet-4-6",
  "provider": "anthropic",
  "api_key": "$ANTHROPIC_API_KEY",
  "system_prompt": "You are Elena, a security-focused code reviewer. You look for injection vulnerabilities, authentication flaws, insecure defaults, and data exposure risks. You always cite the line number and explain why the pattern is dangerous before suggesting a fix. You do not write new code — only review and advise.",
  "description": "Security reviewer. Finds vulnerabilities, authentication flaws, and data exposure risks. Read-only — does not write or execute.",
  "memory_mode": "conversational",
  "plasticity": "reference",
  "memory_enabled": true,
  "local_tools": ["read_file", "list_dir", "grep", "search_files", "git_diff", "git_log"],
  "toolbelt": []
}

Agent configuration reference

Full field listing for the on-disk JSON format:

The description field

The description field is what other agents read when deciding who to handle a task.

When the planner agent needs to delegate, it reads each agent’s description to figure out who is the right fit. A clear description prevents wrong-agent routing.

{
  "description": "Security reviewer. Finds vulnerabilities and authentication flaws. Does not write code."
}

Without a description, the planner falls back to the agent’s name alone. That’s often not enough context to route correctly — especially once you have more than three or four agents.

Write a one- or two-sentence description for every agent you create, even when the name seems self-explanatory.

Dispatching to an agent

Natural language

have Elena review the new auth middleware for vulnerabilities
ask Steve to implement the payment handler in internal/payment/gateway.go

The primary agent reads agent descriptions and routes the task automatically.

--agent flag

Target a specific agent from the command line, bypassing delegation entirely:

huginn --agent Elena "review the last three commits for security issues"
huginn --agent Steve "implement internal/payment/gateway.go"

/dm command

Open a persistent direct-message space with a specific agent:

/dm Elena

DM spaces are separate from main chat sessions and persist across restarts.

/swarm command

Dispatch tasks to multiple agents at once. Each segment takes the form agentName:prompt:

/swarm Steve:implement the login handler | Elena:review the auth logic for vulnerabilities

Both agents run concurrently. Results stream into the swarm view in real time.

Memory modes

Memory mode controls how proactively an agent uses its memory tools during a session.

Set in the agent JSON:

{
  "memory_mode": "conversational"
}

Plasticity presets

Plasticity controls how aggressively MuninnDB updates an agent’s vault. Higher plasticity = more memories written per session.

Context notes file

Each agent can have a plain-text context file at ~/.huginn/agents/<name>.memory.md. When enabled, this file is read at the start of every session and injected into the agent’s context automatically.

Enable it in the agent JSON:

{
  "context_notes_enabled": true
}

You can seed the file by hand:

cat > ~/.huginn/agents/steve.memory.md << 'EOF'
# Steve's Context Notes

## Project conventions
- All database columns use snake_case
- Error returns before happy path
- Prefer table-driven tests

## Recurring preferences
- Do not add logging unless explicitly asked
- Commit messages: imperative mood, 72-char limit
EOF

The agent can also update the file itself using the update_memory tool. Editing the file directly is always safe — the agent reads whatever is in the file at session start.

Context notes are the zero-setup cross-session memory option. No server, no credentials, no network. Use them when the agent’s knowledge is stable and you want direct control.

Memory tiers

Inside a session, Huginn tracks agent context in three layers:

Agent toolbelt

Each agent has its own allowlist of external connections (GitHub, Slack, AWS, Jira, etc.). An agent with an empty toolbelt cannot reach any external service.

{
  "toolbelt": [
    { "connection_id": "github-myorg", "provider": "github", "approval_gate": false }
  ]
}

For the full toolbelt configuration reference, see the Agent Toolbelt page.

Managing agents

Slash commands

All changes persist to ~/.huginn/agents/ immediately and take effect in the current session without a restart.

Keyboard shortcuts (TUI)