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.
`project`	string	none	Named project or repo. Used for filtering agents and capabilities.
`command`	string	global default	CLI command Qalatra uses to run the agent from its folder.
`coding`	boolean	false	When true, running the agent routes the task to the Code view.
`timeout_minutes`	number	15	Maximum runtime before Qalatra stops the process.
`capability`	object	inferred	AI-facing routing metadata, permissions, delegation, and owned files.

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.