Agents > Xedant Agent > Docs > MiniAgent

MiniAgent

MiniAgent is the built-in coding agent: a fully self-contained backend compiled right into Xedant Agent (a C# library, a minimal Pi-style agent rewritten from scratch). It needs no external program and has nothing to install — Xedant Agent and MiniAgent are one whole and fully self-sufficient out of the box.

MiniAgent is part of Xedant Agent’s backend system and is selected with the AGENT_BACKEND=mini variable. For the general overview of backends, see the Backends page.

Why this matters for your business

Regular backends are third-party programs downloaded and installed through a package manager. MiniAgent is different: it lives inside Xedant Agent itself, which means:

  • Independence from third-party developers. The agent’s work does not depend on someone else’s projects and their updates — the engine is always at the server’s side.
  • Supply security. No packages installed from third-party sources — the very risk of receiving a compromised installer disappears.
  • Self-sufficiency out of the box. MiniAgent is already inside the product: nothing to download, install, or update separately.
  • Everything on your server. The agent runs wherever Xedant Agent runs: your data never leaves your infrastructure.

Capabilities

It is a full agent with everything real work needs:

  • Tools read, write, edit, bash, parallel_bash, grep, find, ls, glob, load_skill, and todo_write — reading, editing, and creating files, running commands, search, and skill loading;
  • Persistent sessions — the conversation is saved in JSONL format and resumes after a restart;
  • Model and reasoning-level switching on the fly — right in the middle of a dialog, losing nothing;
  • Automatic context compaction — long conversations do not “forget” their beginning;
  • Retries on transient provider failures and protection from lost replies;
  • Token and cost accounting — in the chat and in analytics;
  • Project context — reads CLAUDE.md/AGENTS.md itself (CLAUDE.md takes priority) and finds the .claude/skills skills on its own;
  • Interactive forms and buttons (agent.form/agent.button) — right in the system prompt, with no separate extensions.

Note: passing images into the chat is not wired up yet — images are ignored on send with a warning in the log.

Connecting it

MiniAgent is selected with the AGENT_BACKEND=mini variable. The easiest way is to create a model from a ready provider template that already carries the MiniAgent backend: Anthropic, DeepSeek, z.ai, BigModel, OpenRouter, xAI, MiniMax, Moonshot, OpenAI, OpenCode Go/Zen. The template fills in the backend and the connection parameters for you:

  • MINI_BASE_URL — the provider address;
  • MINI_API — the protocol format: anthropic-messages or openai-completions;
  • MINI_AUTH — the authorization type: api-key or bearer;
  • MINI_API_KEY — the access key.

The model is set in the “provider/model:thinking” format, for example MODEL=anthropic/claude-sonnet-5:medium. The :thinking suffix sets the reasoning level: off, minimal, low, medium, high. A model the templates do not know is assembled automatically from the parameters above; when a ~/.mini/models.json file exists (a Pi-compatible format), it takes priority. If no model is set at all, deepseek/deepseek-v4-flash is used. The default provider can be set with the MINI_PROVIDER variable — it applies when the model name has no “provider/” prefix.

Data

MiniAgent’s data is stored in the ~/.mini folder (overridable with the MINI_AGENT_DIR variable):

  • models.json — the model configuration;
  • agent-sessions — sessions in JSONL format;
  • skills — additional skills;
  • CLAUDE.md — the global context.

MiniAgent profiles

A profile is a named set of settings for the built-in agent: which context files to load, which tools it may use, how long a single call may run, and the token ceiling for requests. Profiles let you keep several modes of working in one project: a “safe” one without bash for sensitive repositories, a “draft” one with a long timeout for heavy tasks, a “read-only” one for reviews — and switch between them just by changing the model.

Profiles live in the miniagent.yml file in the project’s brand folder (.xedant/). The root map is profiles: — the key is the profile name, the value is its settings:

# miniagent.yml
profiles:
  safe:                       # safe mode: no bash, a short timeout
    disabledTools:
      - bash
    toolCallTimeout: 60
    loadAgentsMd: false

  readonly:                   # read-only: only the search tools are allowed
    enabledTools:
      - read
      - grep
      - find
      - glob
      - ls

The model picks the profile with a mini:name suffix in the AGENT_BACKEND variable of the model’s configuration on the Models page — for example, AGENT_BACKEND=mini:safe. The profile name is lowercased and looked up case-insensitively; the legacy alias mini-agent:safe works too. A plain AGENT_BACKEND=mini without a suffix, an empty suffix, or a nonexistent name all give the built-in defaults — a missing profile logs a warning. Only the MiniAgent backend understands the colon suffix; other backends take the AGENT_BACKEND value as a whole.

Profile settings

Every profile field is optional: a missing field, an empty {} profile, or a missing file all mean the built-in defaults.

FieldTypeDefaultWhat it does
loadClaudeMdbooltrueloads CLAUDE.md into the context
loadAgentsMdbooltrueloads AGENTS.md into the context
enabledToolslist of namesnone (all 11 enabled)the tool allowlist; an empty list is an error; mutually exclusive with disabledTools
disabledToolslist of namesnone (all enabled)the tool denylist; mutually exclusive with enabledTools
toolCallTimeoutint, seconds300the ceiling on a single tool call
maxOutputTokensint131072the request’s output-token ceiling; overrides the model’s maxTokens
thinkingBudgetint65536the thinking budget for every reasoning level except off; applied on anthropic endpoints
parallelBashThreadsint5how many commands of one parallel_bash call run at once
systemPromptstringbuilt-inreplaces the built-in base system prompt; empty also means built-in
sessionHeaderstringnone (X-Agent-Session, X-Opencode-Session on opencode)the name of the HTTP header carrying the session id on every provider request; a headers entry in models.json with the same name takes priority

The tool names are exactly the 11 built-in ones: read, bash, parallel_bash, edit, write, grep, find, glob, ls, load_skill, todo_write. Both enabledTools and disabledTools in one profile is an error (in the yml and in environment variables alike): allowing and forbidding the same tool makes no sense. An empty enabledTools is rejected — it would leave the profile with no tools at all — while an empty disabledTools only produces a warning.

Each setting’s priority: environment variable > profile > built-in default. The profile lays on top of the defaults, and the variable on top of the profile.

The session header. Every provider request carries the session id in an HTTP header — the receiving provider can tell MiniAgent chats apart: group traffic, rate-limit requests, or keep per-session storage without parsing the conversation. By default the header is named X-Agent-Session; on opencode providers (a provider id starting with opencode or an address on opencode.ai) — X-Opencode-Session. The name is changed by the profile’s sessionHeader field or the MINI_PROFILE_SESSION_HEADER variable; an explicit headers entry in models.json with the same name beats the automatic stamp. The sessionHeader key has no editor in the settings dialog — you write it into miniagent.yml by hand or set the variable; the dialog passes a hand-set value through unchanged. A request sent before the session id exists carries no header.

Environment variables

Any profile setting can be overridden at the process level with a MINI_PROFILE_* variable — it applies on top of the selected profile (or the defaults, when no profile is set):

VariableOverrides
MINI_PROFILE_LOAD_CLAUDE_MDloadClaudeMd
MINI_PROFILE_LOAD_AGENTS_MDloadAgentsMd
MINI_PROFILE_ENABLED_TOOLSenabledTools (comma-separated names)
MINI_PROFILE_DISABLED_TOOLSdisabledTools (comma-separated names)
MINI_PROFILE_TOOL_CALL_TIMEOUTtoolCallTimeout
MINI_PROFILE_MAX_OUTPUT_TOKENSmaxOutputTokens
MINI_PROFILE_THINKING_BUDGETthinkingBudget
MINI_PROFILE_PARALLEL_BASH_THREADSparallelBashThreads
MINI_PROFILE_SYSTEM_PROMPTsystemPrompt
MINI_PROFILE_SESSION_HEADERsessionHeader

An empty variable value counts as unset — the setting comes from the profile or the default, so you can “clear” an override with an empty string. Both list variables at once (MINI_PROFILE_ENABLED_TOOLS and MINI_PROFILE_DISABLED_TOOLS) is a hard error, as is an unparseable value (not true/false, not a positive number): the session is not created, and the error names the variable.

Example — a Docker container with a 120-second tool-call timeout and bash disabled for all chats:

docker run -e MINI_PROFILE_TOOL_CALL_TIMEOUT=120 \
           -e MINI_PROFILE_DISABLED_TOOLS=bash \
           xedant/agent

MiniAgent, like the other backends, respects the network variables HTTP_PROXY, HTTPS_PROXY, and NO_PROXY: when the server reaches the internet through a proxy, provider requests go through it too, while addresses from NO_PROXY go direct. Details on the Models page.

The parallel_bash tool

parallel_bash is MiniAgent’s tool for running several independent commands in one call. The model decides which commands do not depend on each other (this independence contract is fixed in the tool’s description) and combines them into a single call:

parallel bash:
  - git status --short
  - ls pages/ | wc -l
  - df -h /project

The commands run concurrently: parallelBashThreads (5 by default) limits how many run at once, the rest wait in the queue. The call finishes after every command answers, and the result returns ordered [i] command sections — one per command, in input order, so the agent can match each output to its command. The trivial difference from bash: bash runs one command, parallel_bash runs a batch; both work on the shared ShellCommand core, and bash behavior is unchanged.

The profiles dialog in settings

The dialog opens from the “MiniAgent” card in the Configuration group of the settings hub (the gear in the header) — more about the hub on the Settings page. The dialog edits the same miniagent.yml a text YAML editor would, but as a form:

  • Profile list — create, rename, and delete. The name follows the mask ^[a-z0-9][a-z0-9_-]*$: a lowercase letter or digit, then lowercase letters, digits, hyphens, and underscores — and it doubles as the mini:name suffix;
  • Profile editor — the loadClaudeMd/loadAgentsMd toggles, tool toggles with an “N of M tools enabled” readout (they edit disabledTools), numeric fields with default-value hints, and a system-prompt editor with a preview of the built-in one. The Reset to default button clears the prompt text — the built-in one is taken fresh from every application update, never copied;
  • Built-in defaults summary — shown next to the list;
  • Conflict protection — every save passes a checksum check (md5): when the file has changed in the meantime (an edit in another client, a text editor, or the Project Settings tab), the server answers 409 and offers to reload the dialog — your edits are never silently overwritten;
  • The same validation as YAML — saving from the form and editing as text pass the same rules (profile names, mutually exclusive lists, number ranges) and give the same errors; the validator runs as a pseudo-build.

Settings freeze at session creation: a live chat works with the profile it was created with, and edits apply to new sessions — switching the profile or the model recreates the session. One more subtlety: when the profile disables the load_skill tool, the “Start by loading the … skill” line disappears from the system prompt — demanding a skill load from a tool that does not exist makes no sense.

A practical example

The “safe” profile — bash off, a 60-second call timeout. Create it in the dialog: Settings → Configuration → MiniAgent → “New profile”, name it safe, turn the bash toggle off, set toolCallTimeout: 60, and save. The equivalent file:

profiles:
  safe:
    disabledTools:
      - bash
    toolCallTimeout: 60

Now assign it to a model: in the model wizard on the Models page, set the AGENT_BACKEND=mini:safe variable (in yml — a line in the variables: list). Chats on that model will run without shell commands and cap every tool call at 60 seconds — everything else stays built-in.

  • Settings — the MiniAgent card and the settings hub;
  • Models — the AGENT_BACKEND variable and the model’s profile choice;
  • Skills — skills in the chat and the load_skill tool.

← Back: Backends

Next: Tips & Troubleshooting →