Agent Templates Catalog

LibreFang provides 32 agent templates from the registry. The assistant template is pre-installed; others can be installed from the dashboard. Each template is a ready-to-spawn agent.toml manifest located in the agents/ directory. Templates cover software engineering, research, writing, business operations, personal productivity, and system tasks.

All templates use provider = "default" and model = "default", which means every agent inherits whichever model you have configured as your default in ~/.librefang/config.toml. You can override the model at spawn time if needed.

Quick Start

Spawn any template from the CLI:

librefang spawn orchestrator
librefang spawn coder
librefang spawn --template agents/writer/agent.toml

Spawn via the REST API:

Spawn from a built-in template:

curl -X POST http://localhost:4545/api/agents \
  -H "Content-Type: application/json" \
  -d '{"template": "coder"}'

Spawn with a model override:

curl -X POST http://localhost:4545/api/agents \
  -H "Content-Type: application/json" \
  -d '{"template": "writer", "model": "claude-sonnet-4-20250514"}'

Send a message to a running agent:

curl -X POST http://localhost:4545/api/agents/{id}/message \
  -H "Content-Type: application/json" \
  -d '{"content": "Write unit tests for the auth module"}'

Templates by Category

Templates are organized by use case. Every template uses the default model provider. The table below lists each agent's description, tags, temperature, and max output tokens. Click an agent name to view its full agent.toml manifest in the registry.

Software Engineering

Research and Analysis

Writing and Documentation

Business and Communication

Personal and Lifestyle

System

Understanding Temperature

The temperature setting controls how deterministic or creative an agent's responses are. Templates set this value based on what each agent does:

• 0.2 -- Precise and deterministic. Used by agents where accuracy matters most: debugger, ops, security-auditor, devops-lead, personal-finance, legal-assistant, home-automation.
• 0.3 -- Analytical with slight flexibility. Used by most engineering and research agents: coder, code-reviewer, test-engineer, architect, planner, data-scientist, academic-researcher, customer-support, translator, health-tracker, meeting-assistant, orchestrator.
• 0.4 -- Balanced analytical. Used by analyst, doc-writer, email-assistant, recruiter.
• 0.5 -- General purpose. Used by assistant, researcher, tutor, recipe-assistant, sales-assistant, travel-planner.
• 0.6 -- Conversational. Used by hello-world.
• 0.7 -- Creative. Used by writer and social-media.

Custom Templates

The agents/custom/ directory is reserved for your own agent templates. Create a new agent.toml file following the manifest format below.

Manifest Format

# Required fields
name = "my-agent"
version = "0.1.0"
description = "What this agent does in one sentence."
author = "your-name"
module = "builtin:chat"

# Optional metadata
tags = ["tag1", "tag2"]

# Model configuration (required)
[model]
provider = "default"                 # Uses your configured default provider
model = "default"                    # Uses your configured default model
max_tokens = 4096                    # Max output tokens per response
temperature = 0.3                    # Creativity (0.0 = deterministic, 1.0 = creative)
system_prompt = """Your agent's personality, capabilities, and instructions go here.
Be specific about what the agent should and should not do."""

# To use a specific provider instead of default, set the provider and model explicitly:
# provider = "gemini"
# model = "gemini-2.5-flash"
# api_key_env = "GEMINI_API_KEY"

# Optional fallback model (used when primary is unavailable)
# [[fallback_models]]
# provider = "groq"
# model = "llama-3.3-70b-versatile"
# api_key_env = "GROQ_API_KEY"

# Optional schedule (for autonomous/background agents)
[schedule]
periodic = { cron = "every 5m" }                                     # Periodic execution
# continuous = { check_interval_secs = 120 }                         # Continuous loop
# proactive = { conditions = ["event:agent_spawned"] }               # Event-triggered

# Resource limits
[resources]
max_llm_tokens_per_hour = 150000    # Token budget per hour

# Capability grants (principle of least privilege)
[capabilities]
tools = ["file_read", "file_write", "file_list", "shell_exec",
         "memory_store", "memory_recall", "web_fetch",
         "agent_send", "agent_list", "agent_spawn", "agent_kill"]
network = ["*"]                     # Network access patterns
memory_read = ["*"]                 # Memory namespaces agent can read
memory_write = ["self.*"]           # Memory namespaces agent can write
agent_spawn = true                  # Can this agent spawn other agents?
agent_message = ["*"]               # Which agents can it message?
shell = ["python *", "cargo *"]     # Allowed shell command patterns (whitelist)

# Named shared workspaces (optional).
# Multiple agents can declare the same path — they share the directory
# without identity-file collisions. Paths are relative to workspaces_dir.
# [workspaces]
# library = { path = "shared/library", mode = "rw" }
# archive = { path = "shared/archive", mode = "r"  }

Available Tools

Tips for Custom Agents

1. Start minimal. Grant only the tools and capabilities the agent actually needs. You can always add more later.
2. Write a clear system prompt. The system prompt is the most important part of the template. Be specific about the agent's role, methodology, output format, and limitations.
3. Set appropriate temperature. Use 0.2 for precise/analytical tasks, 0.5 for balanced tasks, 0.7+ for creative tasks.
4. Use shell whitelists. Never grant shell = ["*"]. Whitelist specific command patterns like shell = ["python *", "cargo test *"].
5. Set token budgets. Use max_llm_tokens_per_hour to prevent runaway costs. Start with 100,000 and adjust based on usage.
6. Use memory for continuity. Grant memory_store and memory_recall so the agent can persist context across sessions.

Agent Workspace

Every agent gets a private home directory under ~/.librefang/workspaces/agents/<name>/. The kernel writes identity files here on first spawn:

workspaces/agents/librarian/
├── .identity/          ← identity files (managed by kernel)
│   ├── SOUL.md         ← personality & mission
│   ├── IDENTITY.md     ← visual identity (emoji, color, vibe)
│   ├── USER.md         ← learned user preferences
│   ├── TOOLS.md        ← tool & environment notes
│   ├── MEMORY.md       ← long-term memory
│   ├── AGENTS.md       ← behavioral guidelines
│   └── BOOTSTRAP.md    ← first-run protocol
├── sessions/           ← conversation history
├── memory/             ← daily memory logs
├── data/               ← agent-specific data
├── output/             ← generated output files
├── skills/             ← agent-specific skills
└── logs/               ← agent logs

You can freely edit any file in .identity/ — the kernel uses create_new and will never overwrite your edits.

Shared Workspaces

Use [workspaces] to give multiple agents access to a shared directory without any collision. Each agent keeps its own private home; only the declared shared paths are shared.

# librarian/agent.toml
[workspaces]
library = { path = "shared/library", mode = "rw" }

# researcher/agent.toml
[workspaces]
library = { path = "shared/library", mode = "r" }   # read-only

The kernel creates the directories on spawn and injects their resolved paths into TOOLS.md:

## Shared Workspaces
- @library → /home/you/.librefang/workspaces/shared/library (read-write)

Modes: rw (read-write, default) or r (read-only). Paths are relative to workspaces_dir and must not be absolute or contain ...

External mounts (mount)

Use mount instead of path to expose a directory that already exists outside workspaces_dir — for example an Obsidian vault or a project tree:

# agent.toml
[workspaces]
vault = { mount = "/Users/me/Documents/Obsidian", mode = "r" }

Constraints:

• mount must be an absolute path that already exists. The kernel never creates host directories on the agent's behalf.
• The path must canonicalize to a prefix of one of the entries in config.toml's top-level allowed_mount_roots. Without that whitelist, every mount is rejected at boot — the safe default.
• path and mount are mutually exclusive within a single declaration.

# config.toml — required to enable the example above
allowed_mount_roots = [
  "/Users/me/Documents",
]

readonly mode (mode = "r") is enforced for mounts the same way as for shared workspaces: write tool calls are rejected by the kernel.

Live Context (context.md)

If a context.md file is present in the agent's workspace, it is re-read on every agent turn and injected into the system prompt as a ## Live Context section. This lets external tools (cron jobs, scripts, dashboards) push fresh data — market prices, project state, on-call rosters — into an agent without restarting it.

Path resolution: {workspace}/.identity/context.md is preferred; {workspace}/context.md is used as a fallback for unmigrated workspaces.

Behavior:

• The file is read once per turn, right before the prompt is assembled.
• Reads are capped at 32 KB; oversized files are truncated with a warning.
• When a previously-successful read fails (e.g. the file is briefly replaced by an external writer), the most recent cached content is reused so the agent does not lose context mid-conversation.
• If the file does not exist, no ## Live Context section is added.

Opting out: set cache_context = true in agent.toml to restore the pre-Apr-2026 behavior, where context.md is read once at session start and cached for the lifetime of the session.

# agent.toml
cache_context = true   # default: false (re-read every turn)

Lazy Tool Loading (tool_search / tool_load)

A default agent answering "hi" used to ship the JSON schema of every built-in tool in every request — ~75 tools × ~90 tokens each ≈ 6 000 tokens of dead weight per turn. Lazy tool loading shrinks that to the ~19 tools the model actually needs in most turns and exposes the long tail through two meta-tools the LLM calls on demand:

• tool_search(query) — keyword-match against the catalog (name + description + hint). Returns matching tools with their one-line hints.
• tool_load(name) — fetch one tool's full schema. The tool becomes callable on the next turn (the schema is added to the request from then on).

The full catalog is still rendered as a one-line-per-tool hint list in the system prompt, so the model knows what exists without paying for full schemas. Tools the runtime classifies as "always native" (file_read, shell_exec, the cron tools, …) keep their full schema in every request — there's no point making the model tool_load something it almost certainly will use.

Opt out per agent if a model is bad at tool_search chains:

# agent.toml — disable lazy loading; ship every tool schema every turn
lazy_tools = false

Spawning Agents

CLI

# Spawn by template name
librefang spawn coder

# Spawn with a custom name
librefang spawn coder --name "backend-coder"

# Spawn from a TOML file path
librefang spawn --template agents/custom/my-agent.toml

# List running agents
librefang agents

# Send a message
librefang message <agent-id> "Write a function to parse TOML files"

# Kill an agent
librefang kill <agent-id>

REST API

# Spawn from template
POST /api/agents
{"template": "coder"}

# Spawn with overrides
POST /api/agents
{"template": "coder", "name": "backend-coder", "model": "deepseek-chat"}

# Send message
POST /api/agents/{id}/message
{"content": "Implement the auth module"}

# WebSocket (streaming)
WS /api/agents/{id}/ws

# List agents
GET /api/agents

# Delete agent
DELETE /api/agents/{id}

OpenAI-Compatible API

# Use any agent through the OpenAI-compatible endpoint
POST /v1/chat/completions
{
  "model": "librefang:coder",
  "messages": [{"role": "user", "content": "Write a Rust HTTP server"}],
  "stream": true
}

# List available models
GET /v1/models

Orchestrator Delegation

The orchestrator agent can spawn and delegate to any other agent programmatically:

User: "Build a REST API with tests and documentation"

Orchestrator:
1. agent_send(coder, "Implement the REST API endpoints")
2. agent_send(test-engineer, "Write integration tests for these endpoints")
3. agent_send(doc-writer, "Document the API endpoints")
4. Synthesize all results into a final report

Environment Variables

All agent templates use provider = "default" and model = "default". The model that agents actually use depends on which provider and model you configure in ~/.librefang/config.toml.

Set one or more of the following API keys depending on which provider you want to use:

Configure your default provider and model in ~/.librefang/config.toml:

[model]
provider = "groq"                    # or "gemini", "openai", "anthropic", "deepseek"
model = "llama-3.3-70b-versatile"    # the model identifier for your chosen provider
api_key_env = "GROQ_API_KEY"         # env var holding the API key

Any agent spawned without an explicit model override will use this default configuration.

Agent Manifest Field Reference

agent.toml accepts a number of top-level fields that aren't shown in the standard quick-start templates. Listing the full set so you can find the field name when you need it. All fields are optional unless marked otherwise.

Tool / skill scoping

tool_allowlist = ["web_search", "web_fetch", "file_read", "file_write"]
tool_blocklist = ["shell_exec"]
tools_disabled = false             # explicit master kill-switch — overrides everything else
allowed_plugins = ["truncate", "redact"]   # plugin names; empty = all available plugins
mcp_servers    = ["github", "linear"]     # MCP server names; empty = all connected servers
skills_disabled = false            # explicit master kill-switch for skills

Identity & spawn behaviour

generate_identity_files = true     # create SOUL.md / IDENTITY.md / TOOLS.md on first spawn
inherit_parent_context  = true     # subagents inherit parent context by default
auto_evolve             = true     # background skill-evolution review after each turn
is_hand                 = false    # auto-set when spawned by a Hand
pinned_model            = "anthropic/claude-sonnet-4"   # locks model in Stable kernel mode

Channel & exec policy overrides (per-agent)

[channel_overrides]
dm_policy = "always"
group_policy = "trigger_only"
group_trigger_patterns = ["(?i)\\bmy-bot\\b"]

[exec_policy]
shell_allowlist = ["git", "cargo"]
deny = ["rm -rf"]

Response shaping & augmentation

show_progress = true
response_format = "json_object"   # or { type = "json_schema", schema = "..." }
web_search_augmentation = "auto"  # "off" | "auto" | "always"

[[context_injection]]
name = "rules"
content = "Be concise. Never use emoji."
position = "system"