qalatra/docs/agent.config reference

The agent.config file

A small JSON contract between your agent and Qalatra.

agent.config is a JSON file at the root of every agent folder. Qalatra scans folders for it, registers the folder as a runnable agent, and now also derives a structured capability record from the same file.

Minimal config

{
  "name": "Research Agent",
  "description": "Researches a topic and produces a markdown report",
  "context": "internal",
  "command": "claude --dangerously-skip-permissions"
}

Existing configs like this still work. Qalatra infers a default capability from the name, description, context, project, and folder path.

With capability metadata

{
  "name": "Filer",
  "description": "Files invoices and local documents into the right folders.",
  "context": "internal",
  "command": "claude --dangerously-skip-permissions",
  "timeout_minutes": 30,
  "capability": {
    "kind": "agent",
    "aliases": ["filing", "file organization", "desktop cleanup"],
    "triggers": [
      "file this invoice",
      "where should this go",
      "organize these files"
    ],
    "delegation": {
      "mode": "qalatra_agent",
      "target": "."
    },
    "permissions": {
      "read_files": "allowed",
      "move_files": "confirm",
      "delete_files": "double_confirm",
      "send_email": "never"
    },
    "files": [
      {
        "path": "AGENTS.md",
        "role": "instructions",
        "readable": true,
        "writable": false,
        "include_in_bundle": true
      },
      {
        "path": "knowledge/routing-rules.md",
        "role": "routing_rules",
        "readable": true,
        "writable": true,
        "include_in_bundle": true
      }
    ]
  }
}

Reference

Key	Type	Default	Notes
`name`	string	—	Unique. Used in task `&agent` references.
`description`	string	none	Used in agent lists and capability search.
`context`	string	none	Broad operating bucket, such as internal, personal, or a client slug. Leave it unset to make the agent global — it surfaces in every context-scoped capability search, not just unfiltered ones.
`project`	string	none	Named project or repo. Used for filtering agents and capabilities.
`command`	string or string[]	global default	CLI command Qalatra uses to run the agent from its folder. A string runs through the login shell; an array is started directly with no shell. See Command forms.
`coding`	boolean	false	When true, running the agent routes the task to the Code view.
`runtime`	string	inferred from the command	Which CLI runs the agent: `claude`, `codex`, or `raw` to run `command` untouched. Leave it out and Qalatra infers it from the command's program: `codex` uses the Codex runtime, and anything else (including wrapper scripts) uses Claude, with a warning logged when the program isn't recognised. Set it explicitly for a wrapper around a non-Claude CLI.
`timeout_minutes`	number	60	Maximum runtime before Qalatra stops the agent and everything it started. The job is recorded as timed out rather than failed, and its session can be continued by sending another message on the task.
`concurrency_key`	string	the folder	Jobs that share a key never run at the same time (1.9.45+). Every job in a folder shares its working tree, so the default serializes each folder on its own; give the plan, execute and pipeline agents of one repo the same key when they work on one checkout.
`worktrees`	boolean	false	Run each task-bound job (such as a FlightDesk dispatch) in its own git worktree under `.qalatra-worktrees/` in the repo, so different tasks in this folder run in parallel while one task’s jobs still run in order (1.9.55+). The worktree starts from the repo’s base branch (`worktree_base` overrides it), is reused for the task’s later jobs, and is removed when the task closes. `worktree_copy` lists untracked files, such as `.env`, to copy into a new worktree.
`memory_high` / `memory_max`	string	1G / 2G	Per-run memory limits on Linux servers, in systemd size syntax such as `"3G"` or `"3072M"` (1.9.55+). A run that is OOM-killed keeps its resumable session and partial output. From 1.9.56, diagnostics distinguish a confirmed per-run limit from a shared-slice limit where evidence permits; missing evidence is reported as unknown. From 1.9.64, a run killed after reaching its limit, or while the shared slice was killing for memory, is reported as a likely OOM even without a kernel record. Shared-host contention calls for reducing concurrent demand, rather than automatically raising this allowance.
`idle_timeout_minutes`	number	off	Stop the agent after this long with no output at all. Useful for work that should never go quiet; leave it off when a single step (a full test suite, a large build) can legitimately produce nothing for a while.
`stream`	boolean	true	Read the agent’s output as it arrives, which is what lets a stopped job keep a continuable session. Set to `false` only to fall back to the older behaviour of reading everything at exit.
`capability`	object	inferred	AI-facing routing metadata, permissions, delegation, and owned files.

Command forms

Qalatra fills in {title}, {description} and {spec_file} when a command mentions them. How the value gets there depends on the form of the command.

A string command runs through your login shell, so $(…), cd and && all work. Qalatra shell-quotes each value, but only when the placeholder stands alone or sits inside exactly one pair of quotes. Text appended inside those quotes, such as '{description} and more', nests the quoting and can cut a prompt down to its first word; Qalatra warns at launch when it sees that shape.

An array command is started directly, with no shell. Every element is one argument and the values are dropped in exactly as written, newlines included, so there is nothing to quote:

{
  "name": "Remote Coder",
  "command": ["flightdesk", "register", "--title", "{title}", "--prompt", "{description}"]
}

A placeholder can also be part of a larger element, like "--prompt=Task: {description}". Don't carry quotes over from a string command — "'{description}'" hands the quotes to the agent literally.

Whichever form you use, every run also receives the task values as environment variables: QALATRA_TITLE, QALATRA_DESCRIPTION, QALATRA_TASK_ID, QALATRA_JOB_ID and, when the command refers to it, QALATRA_SPEC_FILE. A string command that needs shell features can reference those instead of splicing the text into the line:

{
  "command": "cd \"$(ls -d ~/repos/* | head -1)\" && flightdesk register --title \"$QALATRA_TITLE\" --prompt \"$QALATRA_DESCRIPTION\""
}

Agents vs capabilities. The top-level fields tell Qalatra how to run an agent. The optional capability block tells another AI when to pick it, what guardrails apply, and what files define it.