Agents

An agent is a named configuration that ties together a system prompt, the tools it may use, and its approval policy. Agents are provider-agnostic — they never hard-code a model; it is chosen through the provider resolution system (models.yaml).

Where agents live

Agents are discovered across three namespaces:

• ~/.muaz/plugins/local/agents/ — your own workspace (where agents create writes). Wins name resolution.
• ~/.muaz/plugins/<id>/agents/ — installed plugins (e.g. coding, from the auto-sde plugin).
• built-ins — embedded in the binary, read-only: starter (general-purpose chat), codebase (a read-only explainer that reads an unfamiliar codebase and answers with citations), and the three step agents behind the code-review pipeline.

The agent used when you don’t pass --agent is set by default_agent in config.yaml. Reference any agent by a bare name (resolved local → plugins → built-ins) or a fully-qualified @plugin/name.

Entrypoints and step agents

By default an agent is an entrypoint — something you start a conversation with. Set entrypoint: false to mark one a step agent: built to be called by a pipeline rather than chatted with, and therefore kept out of the new-chat pickers.

That is the only thing the flag does. A step agent still resolves by name, still appears in muaz agents list and on the UI Agents page (tagged step), still shows up in the pipeline editor, and still takes its own binding in models.yaml — which is exactly the point, since running two steps of one pipeline on deliberately different models is what per-agent binding is for.

A full agent config

name: coding
description: "An expert coding assistant"

# No provider here — agents are provider-agnostic. The model is chosen in
# ~/.muaz/models.yaml (a global default plus optional per-agent overrides).
# See /muaz/docs/concepts/providers/ for the binding model.

# system_prompt: inline text, OR a path (~/…, /…, ./…, ../…). Co-locate prompts
# with the agent and use relative paths so the agent stays portable.
system_prompt: "./coding.md"

# Optional: a markdown SOP file appended after system_prompt
sop_file: "./coding-sop.md"

streaming: true   # stream tokens as they arrive (default: true)

# entrypoint: false   # a pipeline step agent — hidden from the new-chat picker,
                      # but still resolvable, listable, and separately bindable

# Agentic loop limits (null = use built-in default)
max_iterations: 20         # tool-call rounds before giving up
max_concurrent_tools: 4    # parallel tool executions per round

# LLM inference parameters (null = use model default)
max_tokens: ~
temperature: ~
top_p: ~

# Compact conversation history when accumulated input tokens exceed this
# threshold. null disables compaction.
compaction_token_threshold: 80000
compaction_summary_prompt: ~   # custom summary instructions (null = built-in)

# Built-in tool safety limits
workspace_root: ~          # default working dir for new sessions (default: where muaz started)
shell_timeout_secs: 120    # kill a shell command after this many seconds

# Hard local-egress lock: `none` strips the web tools and refuses HTTP MCP
# servers for this agent (default: full).
network: full

# Per-agent web guardrails; field-merges over the global config.yaml web_tools block
web_tools:
  allow_private_hosts: false   # reach localhost/private addresses (off blocks SSRF)
  default_format: markdown     # fetch_webpage default output: markdown | text

# Skills available to this agent (omit to expose none; opt in explicitly)
skills:
  allow:
    - verify-and-debug

# Tool access: one level per tool (off | ask | auto). Overrides the global
# config.yaml `tools:` defaults; the most specific setting wins.
tools:
  default: ask               # fallback for tools with no specific setting
  built_in:
    read_file: auto
    search: auto
    edit_file: ask
    shell:                   # stay at ask, but auto-approve read-only git
      level: ask
      allow_when:
        - "program=git"
  # MCP servers are opt-in: an agent attaches one by listing it here.
  servers:
    filesystem:
      default: ask

Key fields

• system_prompt — inline text or a path (~/, /, ./, ../). Resolved relative to the agent’s own directory, so ./coding.md works in any namespace.
• sop_file — optional SOP markdown appended after the system prompt.
• tools — the single tool-access axis: default, per-built_in levels (off/ask/auto, optionally with allow_when), and the MCP servers this agent attaches. Setting a tool off removes it from the toolset; there is no separate include/exclude or approve/deny list.
• workspace_root / shell_timeout_secs — workspace_root is the default working directory for this agent’s new sessions (file-tool confinement + shell cwd); a session can pick a different one at creation, and a deployment that pins the workspace root overrides it. shell_timeout_secs caps shell runtime.
• network — none is a hard local-egress lock: it strips the web tools and drops HTTP MCP servers for this agent (full by default).
• web_tools — per-agent override of the global web tool guardrails (fetch_webpage, web_search); fields merge over the global block.
• skills — controls which skills the agent sees; allow opts into a named subset, deny hides specific skills, paths adds discovery directories.
• compaction_token_threshold — summarise history once accumulated input tokens exceed this, to stay within context limits.

Memory

Agents keep durable, cross-session notes as plain Markdown notebooks under ~/.muaz/memory/, injected into the system prompt at session open. Memory is scoped three ways, and a session loads exactly the notebooks its context selects — the model never has to chase links between them:

Scope	File	Loaded by	Holds
global	memory/global.md	every session	your stable preferences (tone, language, conventions)
agent	memory/agents/<agent>.md	sessions with that agent	how this agent behaves, regardless of project
project	memory/projects/<dir>.md	sessions whose working directory is that dir	repo conventions (build commands, layout, style) — shared by every agent working there

The agent curates its notebooks with the memory tool (each call names a scope); you can edit them too — global memory in Settings, agent memory on the agent’s edit page, project memory from the working-dir chip in the chat header. Each notebook is size-capped (8 KB), and edits apply from the next session, which keeps the current session’s prompt prefix cache-stable. Pipeline steps and subagents run without memory.

Managing agents from the CLI

muaz agents list           # list agents across all namespaces (tagged by namespace)
muaz agents create         # create a new agent interactively (writes to local)
muaz agents show coding    # print the resolved config (any namespace)
muaz agents edit coding    # edit a local agent; forks a built-in/plugin into local first

Editing a built-in or plugin agent forks it into your local workspace (copying the agent and its prompt/SOP), where your copy then wins resolution — the original stays intact and upgradeable.

From inside the REPL, /agents lists agents (with namespaces) and /switch <name> loads a different one in a fresh session; on an ambiguous name it lists the candidates so you can /switch @plugin/name.