Configuration: automation
The settings in agentx.json that make agents work on their own: schedules, the daily exceptions digest, services, incoming webhooks, workflows, learned procedures, notifications, approvals, open requests, task watchers, request status, the weekly quality report, resuming after a restart, due reminders, native apps and the wiki's daily contributions. For the other sections and how to edit the file, see the Configuration reference.
"Default" is the value used when the key is left out. "required" means the entry is rejected without it; "—" means it is unset unless you set it.
crons
Schedules (also called scheduled jobs, cron jobs or routines), keyed by job id: crons.<id>. Each job either asks an agent to run a prompt or runs a shell command.
| Key | Type | Default | What it does |
|---|---|---|---|
enabled | boolean | true | Turns the job on or off without deleting it. |
schedule | string | required | When the job runs, as a cron expression such as 0 7 * * 1. |
timezone | string | "UTC" | The timezone the schedule is read in, for example Europe/Paris. |
agent | string | required | The agent that runs the prompt. For a command job, the agent told when it fails. |
prompt | string | "" | What the agent is asked to do. A job needs a prompt or a command. |
command | string | — | A shell command run directly instead of an agent: no model, no tokens. |
timeout | number | 600 | Time limit in seconds. Agent jobs get at least 2 hours; see time limits. |
model | string | — | Model for this job only, instead of the agent's model. |
maxOutputTokens | number (50–8000) | — | Asks the agent to keep its answer under about this many tokens. A soft cap added to the prompt. |
taskType | string (up to 64 characters) | — | The type of task each run is. It picks the proof a watcher asks for before the run counts as done (watchers.evidence.<type>). Unset, or a type with no rule of its own: the rule for cron, if there is one. To exempt a job from proof, remove the cron rule rather than set a type. See Require proof of done. |
autonomy | "report" | "propose" | "act" | — (acts as act) | How much the run may do. See routine autonomy. Not allowed on command jobs. |
requireSources | boolean | — | Check each answer before it is sent: every line that states a fact must carry a link (https://…, or a link to a .md file in the agent's folder). If one does not, the message ends with a warning that names the line, and the run record counts it as unsourced. See sales leads. |
expectExitZero | boolean | — | For a prompt that tells the agent to run a shell command. The agent is asked to end its answer with a line EXIT=<code>, the command's exit code (0 means it worked). The run counts as failed when that line is missing or is not EXIT=0, so the failure shows in the schedule's run history and onError applies. Without it, a run counts as a success whenever the agent itself finished, even if the command it ran failed. Not allowed on command jobs, which already fail on a non-zero exit. See a prompt that runs a command. |
value | object | — | The job's value line: why it runs and the number that proves it. Shown as written on the Hub's Schedules tab and in Settings › Schedules. A job without one shows no value line. |
value.why | string (1–200 characters) | required | Why the job runs, for example Keeps the support queue answered overnight. |
value.metric | string (1–200 characters) | required | The number that proves it, for example Tickets older than 12 h each morning: 0. AgentX does not measure it. |
value.number | string (number id) | — | The tracked number that measures it, for example video-views. See Track numbers over time. |
goal | string (goal id) | — | The goal record the job serves, for example zero-issues. Each run's prompt starts with the goal's state: its title, what done means, its check and what the check saw last, and how many of its requests are open and done. Once the goal is done or dropped the job no longer runs, including a run it missed while the node was off; its settings are left as they are, and the Hub's Schedules tab shows goal … done, disable?. A prompt job without one shows no goal beside its value line. See A goal's own record. |
onError | "log" | "notify" | "disable", or a list of them | "log" | What happens when a run fails: log it, send a message, or turn the job off after 3 failures in a row. From the second failure in a row a message is sent anyway. |
notify | object | — | Where this job's messages go: the answer from each successful run, and failure messages. |
notify.channel | string | required | Channel for the job's messages, for example telegram. |
notify.chatId | string | required | The chat on that channel. |
notify.accountId | string | — | Which account on that channel, when you have more than one. |
deliverResult | boolean | true | Sends the answer from each successful run to notify. Set false to send only failure messages there. Without notify, true marks a schedule waiting for a destination: agentx connect telegram (when it saves your chat) fills it in for agents that belong to a team, and agentx team notify fills it in for a team's schedules. |
report | "always" | "exceptions" | "always" | "exceptions": the run decides whether there is anything to say. The agent is asked to reply with exactly NOTHING_TO_REPORT when all is well, and such a run sends nothing to notify. Failure messages are sent either way. See report only when something is wrong. |
fireToken | string | — | Secret that lets another system start the job now. See fire a routine. |
createdBy | string | — | The agent that created the job from chat. Set by AgentX; an agent may only manage jobs it created, unless it is an admin. |
approval | object | — | A change an agent asked for that waits for you. Set by AgentX; cleared by agentx schedule approve or agentx schedule reject. |
approval.action | "create" | "delete" | required | What the agent asked for. A job waiting on create never runs. |
approval.requestedBy | string | required | The agent that asked. |
approval.requestedAt | string | required | When it asked (date and time). |
"crons": {
"weekly-summary": {
"schedule": "0 8 * * 1",
"timezone": "UTC",
"agent": "writer",
"prompt": "Summarise last week's merged changes",
"onError": ["notify", "disable"],
"notify": { "channel": "telegram", "chatId": "123456789" }
}
}A prompt that runs a command
A job with a command runs it directly and fails when it exits with an error. A job with a prompt that only says "run this command" is different: the agent runs it and describes the result in words, and the run counts as a success as long as the agent finished.
- Editor: if the job only runs the command, move it from
prompttocommand. No agent and no tokens are used. - Editor: if the agent must read or act on the result, keep the
promptand add"expectExitZero": trueto the job.
"crons": {
"nightly-import": {
"schedule": "0 3 * * *",
"agent": "writer",
"prompt": "Run: ./scripts/import.sh, then summarise what it imported",
"expectExitZero": true,
"onError": ["notify"]
}
}A run that ends with EXIT=1, or with no EXIT= line at all, is recorded as failed with the error the command exited with code 1 or the answer did not report the command's exit code.
On a run that worked, the EXIT=0 line is removed before the answer is sent to notify, so the reader never sees it. The run history keeps the answer as the agent wrote it. With requireSources, the EXIT=0 line is not checked for a source.
A run the daemon makes up after a restart, for a time it missed while it was off, counts the same way: a failure adds to the failures in a row, sends the failure message, and can turn the job off under onError. It is not retried; the next regular run follows the schedule.
exceptionsDigest
One message a day that lists only what is wrong on this machine: schedules whose latest run failed or that did not run when due, stuck open requests, and agents or projects paused by their budget. When nothing is wrong, nothing is sent. Off by default. Guide: Get a daily list of what is wrong.
| Key | Type | Default | What it does |
|---|---|---|---|
exceptionsDigest.enabled | boolean | false | Turns the digest on. |
exceptionsDigest.time | string (HH:MM, 24-hour) | "09:00" | When it goes out each day. |
exceptionsDigest.timezone | string | — | Time zone time is read in, for example Europe/Paris. Unset: this computer's. |
exceptionsDigest.destination | object | — | Where it goes: channel, chatId and optional accountId. Unset: notifications.destination. |
{
"exceptionsDigest": { "enabled": true, "time": "08:30", "timezone": "Europe/Paris" }
}wikiNotes
Notes agents leave for the wiki observe/sweep run: what changed, the source and the date. The listed schedules, and the absorb pass of absorbAgent, read them first and record each one as patched, rejected or deferred. Off by default. Guide: Let agents leave notes for the wiki run.
| Key | Type | Default | What it does |
|---|---|---|---|
wikiNotes.enabled | boolean | false | Turns wiki notes on for this node. Needs wikiNotes.inbox. |
wikiNotes.inbox | string | — | Agent that runs the wiki observe/sweep schedule. Notes are kept on its node; other nodes forward theirs to it. |
wikiNotes.crons | string[] | [] | Schedule ids (keys of crons) that read the inbox when they start. Each must run as the inbox agent. |
wikiNotes.absorbAgent | string | — | Agent whose agentx wiki absorb pass reads the inbox and answers each note with a patch, a rejection or a deferral. Must be an agent on this node, the node that keeps the inbox. Unset: absorb reads no notes. |
wikiNotes.maxNotesPerRun | number (1-100) | 20 | Most notes one run is given, open notes before deferred ones. The rest wait for the next run. |
wikiNotes.maxDeferrals | number (1-20) | 3 | A note deferred this many times expires and is no longer offered. |
{
"wikiNotes": { "enabled": true, "inbox": "wiki-agent", "crons": ["wiki-sweep"], "absorbAgent": "wiki-agent" }
}services
Services answer a known kind of message with a fixed prompt, keyed by service id: services.<id>. When an incoming message matches a trigger, the service's prompt is sent to its agent.
| Key | Type | Default | What it does |
|---|---|---|---|
name | string | required | Name shown in lists and logs. |
triggers | list of objects | required | Patterns that start the service. |
pattern | string | required | A trigger's regular expression, matched against the message text, ignoring case. |
channel | string | — | Limits a trigger to one channel, for example whatsapp. |
allowedContacts | list of strings | — | Only these senders can start the service. Unset: anyone. |
agent | string | required | The agent that runs the prompt. |
prompt | string | required | The prompt sent to the agent when a trigger matches. |
schedule | string | — | A cron expression kept with the service. The daemon does not run services on a schedule yet; use crons for timed work. |
timezone | string | "UTC" | Timezone for schedule. |
notify | object | — | A destination kept with the service (channel, chatId, notify.accountId). Not used by the daemon yet. |
webhooks
The list of incoming webhooks, as managed on the dashboard's Webhooks tab. The address a system posts to is always /webhook/<agentId>/<source> on the daemon.
| Key | Type | Default | What it does |
|---|---|---|---|
id | string | required | Short name for the entry: lowercase letters, digits, - and _. |
source | string | required | The sending system, for example github, gitlab or stripe. |
agentId | string | required | The agent that handles the event. |
secretEnv | string | — | Name of the environment variable that holds the signing secret. When set, unsigned or wrongly signed requests are refused. |
description | string | — | A note for people reading the list. |
enabled | boolean | true | A disabled entry is ignored. |
node | string | — | Sends the event to this mesh peer instead of running it on this machine. |
triggers | map of strings | — | Starts a different workflow per event type. Keys are event types such as issues.opened or Merge Request Hook; values are workflow ids. |
defaultWorkflow | string | — | Workflow started when no triggers key matches. Unset: the agent handles the event itself. |
"webhooks": [
{ "id": "repo-events", "source": "github", "agentId": "reviewer", "secretEnv": "GITHUB_WEBHOOK_SECRET",
"triggers": { "pull_request.opened": "review-pr" } }
]workflows
The workflow engine. See Workflows.
| Key | Type | Default | What it does |
|---|---|---|---|
workflows.enabled | boolean | false | Turns the workflow engine on. |
workflows.dir | string | ".agentx/workflows" | Folder that holds workflow definitions. |
workflows.n8n | object | {"baseUrl":"","apiKey":""} | Connects your n8n instance so the builder can list its workflows as steps. |
workflows.n8n.baseUrl | string | "" | Address of your n8n instance. Empty: not connected. |
workflows.n8n.apiKey | string | "" | n8n API key. Use an environment reference such as ${N8N_API_KEY}. |
workflows.matching | object | {} | Matching incoming messages to a workflow. |
workflows.matching.enabled | boolean | false | Checks each message for a matching workflow. |
workflows.matching.mode | "suggest" | "auto" | "suggest" | suggest only logs a match; auto runs the workflow instead of the agent. |
workflows.matching.autoRunThreshold | number (0–1) | 0.85 | In auto mode, how confident a match must be to run the workflow. |
workflows.matching.suggestThreshold | number (0–1) | 0.65 | How confident a match must be to count at all. Also how close a saved workflow must be before an agent is told it fits a request (follow-up workflows). |
workflows.followUp | object | {} | Workflows that agents start for your requests and AgentX follows to the end. See Let a workflow follow a request. |
workflows.followUp.enabled | boolean | true | Agents may start follow-up workflows, and are told when a saved workflow fits a request. Needs workflows.enabled. |
workflows.followUp.agents | object | {} | Per agent, by id: false turns follow-up workflows off for that agent. |
workflows.followUp.stallMinutes | number | 30 | Minutes without progress before an agent step gets a reminder (a nudge). At most 10080 (7 days). |
workflows.followUp.maxNudges | integer (0–20) | 2 | Nudges before the step counts as blocked and you are told. |
workflows.followUp.approval | "step" | "start" | "step" | When you approve messages to people: each before it is sent, or all at once when a run starts. A workflow's own approval wins. |
workflows.required | object | {} | Every task runs inside a workflow run: a saved workflow that fits, else a plan the agent writes, else one step. See Run every task through a workflow. |
workflows.required.enabled | boolean | false | On for every agent. Needs workflows.enabled. |
workflows.required.agents | object | {} | Per agent, by id: true or false wins over enabled. |
workflows.required.exemptQuestions | boolean | true | A plain question (no plan, only tools that change nothing) leaves no run. |
workflows.required.retentionDays | number | 30 | Task runs that ended are removed this many days after their last change, when the daemon starts and every 6 hours. 0 keeps them all. |
workflows.editor | "disabled" | "readonly" | "edit" | "edit" | The dashboard's workflow editor: hidden, view only, or editable. |
procedures
Procedures are step-by-step guides AgentX learns from work that repeats. When the extraction job runs is set by the procedure-extract entry in crons, which agentx procedure watch writes.
| Key | Type | Default | What it does |
|---|---|---|---|
procedures.enabled | boolean | true | Turns procedures on. |
procedures.dir | string | ".agentx/procedures" | Folder that holds procedures. |
procedures.extraction | object | {} | Settings for finding new procedures. |
procedures.extraction.enabled | boolean | false | Turns finding new procedures on. |
procedures.extraction.onTaskCompletion | boolean | false | Counts repeated patterns after each finished task. Uses no model. |
procedures.extraction.minOccurrences | number (2 or more) | 3 | How often a pattern must repeat before it becomes a draft. |
procedures.extraction.sinceDays | number (1 or more) | 7 | How many days of past work to look at. |
procedures.extraction.maxClusters | number (1 or more) | 5 | Most drafts made in one run. |
procedures.extraction.via | string | — | Agent whose session writes the drafts. |
procedures.injection | object | {} | Giving procedures to agents. |
procedures.injection.enabled | boolean | true | Adds matching procedures to a new agent conversation as guidance. |
procedures.injection.maxProcedures | number (1 or more) | 2 | Most procedures added at once. |
procedures.injection.minScore | number (0–1) | 0.5 | How closely a procedure must match the request to be added. |
notifications
Messages about finished, failed or long tasks. See get notified.
| Key | Type | Default | What it does |
|---|---|---|---|
notifications.longTaskThreshold | number | 30 | Seconds a task must run before you are told about it. 0 turns this off. |
notifications.destination | object | — | Where task messages go. Unset: no task messages. |
notifications.destination.channel | string | required | Channel, for example telegram or push. |
notifications.destination.chatId | string | required | The chat on that channel. |
notifications.destination.accountId | string | — | Which account on that channel. |
notifications.channel | string | — | Where agentx notify and messages held during Focus go when no channel is given, for example push or ntfy. Unset: push when channels.push.enabled is on, otherwise ntfy. |
notifications.publicUrl | string | — | The address your phone opens the Hub at, such as https://my-mac.example.ts.net. A tap on an ntfy notification opens its own link, else its request on the Hub, else the Hub. Not localhost or 127.0.0.1. Unset: calls.phone.appUrl; if that is unset too, an ntfy notification without a link of its own opens nothing. |
notifications.on | object | {} | Which events send a message. |
notifications.on.taskComplete | boolean | true | A long task finished. |
notifications.on.taskError | boolean | true | A task failed. |
notifications.on.taskQueued | boolean | false | A task had to wait in the queue. |
notifications.local | object | {} | What agentx notify does on this Mac. macOS only. |
notifications.local.banner | boolean | true | Shows a desktop banner. |
notifications.local.sound | boolean | true | Plays a sound. |
notifications.local.soundName | string | "Glass" | A sound from /System/Library/Sounds, without the extension. |
notifications.local.volume | number (0–1) | 0.4 | Sound volume. |
notifications.local.icon | string | — | Image for the banner icon (.png, .jpg or .icns). Unset: the AgentX logo. Applied by agentx desktop install. |
notifications.local.quietWaitSeconds | whole number (0–120) | 15 | Seconds the sound waits while something else speaks on this computer, such as a spoken answer or a script using say. If something is still speaking after that, the banner shows without the sound. 0: never wait. |
notifications.told | object | {} | The record of what you were told. Everything sent to your own addresses is written down once. Something you were already told is not sent again on any channel, and system reminders wait for the daily digest. See Told once. |
notifications.told.enabled | boolean | true | Records and checks every message to your own addresses. |
notifications.told.repeatWindowHours | number (up to 720) | 24 | Hours during which a notice with the same key is not told again, on any channel. A notice without a key is matched by its words for at most 20 hours. Agents' answers are never matched. |
notifications.told.channels | list of strings | ["push", "ntfy"] | Channels that only ever reach you. Every message on them goes through the record. |
notifications.told.addresses | list of strings | [] | Your other private chats, as channel:chatId, for example telegram:123456789. |
notifications.told.digestNags | boolean | true | System reminders, such as "Not finished", a missing voice or a channel that stopped, wait for the daily digest (approvals.digest) instead of a notification each. Off, or with no digest destination: each is sent at once. |
notifications.reach | object | {} | Urgent messages that follow you. Seen and answered marks, where you were last seen and channel health are always recorded; this switches only the second send. See Did it land. |
notifications.reach.enabled | boolean | false | An urgent message goes where you were seen last and, unseen, once to the next address. |
notifications.reach.escalateAfterMinutes | integer (1 to 1440) | 10 | Minutes an urgent message waits to be seen or answered before it is sent once to the next address. |
notifications.reach.ladder | list of strings | [] | Your addresses in order, as channel:chatId, for example push:default or telegram:123456789. Empty: the told channels, then the told addresses. Use only told channels and addresses: a message to any other address is not recorded, so it cannot be seen or sent on. |
notifications.desk | object | {} | Where a new item on your Desk reaches you the moment it appears. With approvals.digest, these are the three settings of the Desk. See Choose where new items go. |
notifications.desk.phone | "all", "urgent" or "off" | "off" | A notification on the phone app (or ntfy) for each new item. urgent: only an item that expires within a day. Off: the Desk and the digest only. |
notifications.desk.computer | "all", "urgent" or "off" | unset | The Mac card for each new item when approvals.popup.enabled is on, otherwise a banner on this computer. Unset: all when the popup is on, off when it is off. |
calls
Agents ringing you for a live voice call on AgentX Voice and your phone. See Calls from your agents. The same settings cover an agent asking to see through your phone camera (Share your phone camera): a camera ask counts as a call here.
| Key | Type | Default | What it does |
|---|---|---|---|
calls.allow | string[] | [] | Agents that may call you, or ask to see: ids, or "*" for every agent. Empty: nobody. |
calls.maxPerHour | number (1–60) | 3 | Most calls and camera asks one agent may place in an hour, together. |
calls.ringSeconds | number (10–300) | 45 | Seconds a call rings, or a camera ask waits on the phone, before it counts as missed. |
calls.maxCallMinutes | number (1–240) | 30 | An answered call nobody hung up ends after this many minutes (the widget quit or crashed, the Mac slept), so the agent can call again. |
calls.ringSound | string | "Submarine" | The ring: a sound from /System/Library/Sounds, without the extension. |
calls.summary | boolean | true | After hang-up, the agent writes a short summary, filed in the dashboard's Ask history. |
calls.busy.retryMinutes | number (1–60) | 5 | While a call waits because AgentX Voice is busy (you are in another call, in a turn, or recording), you get the call-waiting notice again this often. |
calls.busy.maxWaitMinutes | number (1–240) | 10 | The longest a call waits. Still busy then, it counts as missed. |
calls.busy.title | string | "Call waiting: {agent}" | Title of the call-waiting notice. {agent} becomes the caller's name. |
calls.busy.notice | string | "AgentX Voice is busy. The call rings when it is free." | Second line of that notice, under the caller's reason. |
calls.phone.ring | "always" or "away" | "always" | When an agent's voice call also rings your phone. always: together with AgentX Voice; the first to answer takes the call. away: only when AgentX Voice is not running. See Answer on your phone. |
calls.phone.appUrl | string (an origin) | unset | The address your phone opens the app at, such as https://my-mac.example.ts.net. With ntfy, a tap on the call opens it in the phone app. Also used for what a tap on an ntfy notification opens when notifications.publicUrl is unset. Not needed for Web Push. |
approvals
The Approvals inbox. See Approvals.
| Key | Type | Default | What it does |
|---|---|---|---|
approvals.defaultExpiryDays | number (up to 365) | 3 | Days a decision card waits when the agent gave no expiry. |
approvals.maxExpiryDays | number (up to 365) | 30 | The longest any card may wait. |
approvals.laterHours | number (up to 720) | 24 | Hours Later hides an item. |
approvals.notifyAgent | boolean | true | Tells the agent that raised a card when it is decided or expires. |
approvals.forwardTo | string | — | The name of a machine in mesh.peers whose inbox and popup take the cards agents on this machine raise. The answer comes back to the agent here. Unset: cards stay on this machine. See Agents on another machine. |
approvals.digest | object | {} | One reminder a day of what is waiting. |
approvals.digest.enabled | boolean | true | Sends the daily reminder. |
approvals.digest.time | string | "09:00" | Time of day, 24-hour HH:MM. |
approvals.digest.timezone | string | — | Timezone for time, for example Europe/Paris. Unset: this machine's. |
approvals.digest.destination | object | — | Where the reminder goes. Unset: notifications.destination. |
approvals.digest.destination.channel | string | required | Channel for the reminder. |
approvals.digest.destination.chatId | string | required | The chat on that channel. |
approvals.digest.destination.accountId | string | — | Which account on that channel. |
approvals.popup | object | {} | Shows waiting cards on this Mac. macOS only. See Answer from a card on your Mac. |
approvals.popup.enabled | boolean | false | Shows waiting cards on this Mac. |
approvals.popup.style | "card" | "dialog" | "card" | "card": the web card window. "dialog": plain macOS dialogs, also the fallback when the window can't open. |
approvals.popup.theme | "system" | "light" | "dark" | "system" | The card's colours. "system" follows light or dark mode. |
approvals.popup.speak | boolean | true | Speaks one short line when the card opens. |
approvals.popup.voice | string | — | A macOS voice for the spoken line. Unset: the system voice. |
approvals.popup.sound | string | "chime" | "chime" (the card's soft chime), a sound from /System/Library/Sounds such as "Glass", or "" for none. |
approvals.popup.volume | number (0 to 1) | 0.4 | Sound volume. |
approvals.popup.timeoutSeconds | number (10 to 3600) | 600 | How long the card waits for an answer. After that the card stays in the inbox. |
approvals.checkin | object | {} | Check-ins: waiting cards and your open Apple Reminders on the Mac card, a few times a day. macOS only. See Check-ins. |
approvals.checkin.enabled | boolean | false | Runs check-ins. |
approvals.checkin.dailyAt | string (HH:MM) | "09:00" | The daily check-in: every open reminder. |
approvals.checkin.times | string[] (HH:MM) | ["11:00", "14:00", "17:00"] | The other check-ins: reminders due soon. |
approvals.checkin.timezone | string | — | IANA time zone for the times. Unset: this machine's. |
approvals.checkin.lists | string[] | ["Reminders"] | Your Reminders lists to look at. |
approvals.checkin.agent | string | — | The agent that writes cards for reminders without an agentx: line. Unset: those reminders are skipped. |
approvals.checkin.dueWithinHours | number | 24 | A normal check-in takes reminders due within this many hours, or overdue. |
approvals.checkin.maxAsksPerPass | number (1 to 20) | 5 | Most agents one check-in asks to write a card, whatever they answer. |
approvals.checkin.composeTimeoutSeconds | number (30 to 3600) | 300 | How long an agent may take to write one card, counted from the start of its turn. The turn is stopped at the limit. |
quality
Quality gates for agent-written changes. Each one is off by default.
| Key | Type | Default | What it does |
|---|---|---|---|
quality.specTests.enabled | boolean | false | A separate test agent writes tests from the issue text for issues that go to a Claude cloud session. See Have a second agent write tests from the issue. |
quality.specTests.paths | list of strings | ["src/daemon"] | Folders in the pilot. Only an issue that names one of them gets spec tests. |
quality.specTests.agent | string | "spec-tests" | The test agent's name, used as the author of the spec-test commit. Must not be the coding agent's id. |
quality.specTests.model | string | unset | Model the test agent uses. Unset: the claude command's default. |
quality.specTests.maxCostPerIssue | number (up to 100) | 2 | Most the test agent may spend on one issue, in US dollars. Past it, it stops and leaves a note on the issue. |
quality.specTests.maxMinutes | number (1–120) | 20 | Most minutes the test agent may run for one issue. Past it, it stops and leaves a note on the issue. |
requests
Open requests: what you asked an agent for is recorded and followed until it is done, declined or dropped. Off by default.
When it is on, AgentX notes every message you send to an agent. A message the agent simply answers leaves nothing behind. A request is kept open when its work goes on after the answer, or goes wrong:
- The agent handed the work to another agent.
- The run failed or hit its time limit.
- A restart cut the run off.
An open request that fails, times out, is cut off and not picked up again, or has no activity for staleAfterHours is marked as needing attention. You are told once, through your normal notifications, which are held while Focus is on. A request stopped by a usage limit or a restart is first sent back to its agent once (autoResend); you are told only if that does not fix it.
One case is closed instead of coming back to you: a request whose handed-on work all came back done, and that nobody closed within staleAfterHours. It is closed as done. The proof is the first link in the other agent's answer. With no link, it is marked unproven. Turn this off with settleHandedBack: false. A hand-off that failed or timed out does not hold the request once a later hand-off to the same agent came back done. A hand-off lost in a restart does not hold it once one to the same agent that started after it came back done, even if the two ran side by side. A request raised only because a hand-off failed or was lost is closed the same way.
When you write again in a chat, the requests of that agent waiting on your answer there go back to work, whether or not the agent's question was caught. A request waiting on a decision card you have not decided keeps waiting for the card. The quiet and settle rules follow them from there. Turn this off with releaseOnOwnerTurn: false.
A request whose home is a GitHub or GitLab issue, pull request or merge request also closes when that home closes. The daemon reads the home as often as the loop checks run (checkers.checkEveryMinutes). A merged pull or merge request, or an issue closed as completed, closes the request as done and checked, with who closed it and when. The home must have closed after you asked, and after you last sent the request back. A tracked plan stops with it, and the evidence names the steps it had left.
These stay as they are:
- requests waiting on you, promises, and requests with a check of their own
- pull or merge requests closed without merging
- issues closed as not planned or as a duplicate
- homes the daemon cannot read, and GitHub homes when there is no GitHub token
Turn this off with homeCloses: false.
Who counts as you on this computer's own surfaces (voice, the phone app, the dashboard) is proven, not declared: the daemon marks the turns it starts itself, and the dashboard presents the key in .agentx/operator.key for the phone app. The daemon creates that file next to agentx.json at start, readable by your user only. A call to POST /task that names one of those channels without the key runs as an ordinary turn and is not recorded as your request. When the phone app talks to an agent on another computer, the computer it is paired with checks its own key on the forward and tells the other one the turn is yours; that other computer believes it only from a request that carries one of its mesh.peers[].token values and comes from another machine, never from a caller on the same machine or a bare header. A computer you let vouch is trusted for more than the list: the turn is yours for people limits too. When the whole mesh shares one token, every computer in it can vouch, so share a token only between computers you own.
While requests are on, or follow-up workflows are (workflows.enabled and workflows.followUp.enabled), or every task runs through a workflow (workflows.required), the daemon adds its own tool server (agentx serve --stdio) to every agent's .mcp.json at start, as agentx, so each agent can close its requests with the agentx_request tool. An agentx entry you declared in the agent's mcp block, or a .mcp.json you wrote by hand, wins. Agents on a claude-code engine do not depend on that file: every session the daemon starts for them loads the agentx tool server through its own start flags, so the agentx_request and agentx_approval tools are there whether or not requests are on.
How to see, close and drop requests, step by step: Keep track of what you asked for.
To turn it on by hand:
- Open
agentx.json. - Add
"requests": { "enabled": true }. - To count your messages on a channel other people can also write on (Telegram, WhatsApp, Slack, Discord, GitLab, GitHub), add your id on that channel to
from, aschannel:id: your login on GitLab and GitHub, your numeric id on Telegram, your number on WhatsApp. For example"from": ["telegram:123456789", "github:your-login"]. - Save the file. The running daemon picks the change up; no restart is needed.
| Key | Type | Default | What it does |
|---|---|---|---|
requests.enabled | boolean | false | Records and follows your requests. |
requests.channels | list of strings | [] | Channels to record on. Empty: every channel a person writes on (telegram, whatsapp, slack, discord, gitlab, github, app, voice, dashboard, webrtc). |
requests.from | list of strings | [] | Who counts as you on channels other people can reach: your id on that channel, as channel:id. That is your login on GitLab and GitHub, and the sender id everywhere else (the numeric id on Telegram, the number on WhatsApp). An entry only applies to its own channel. Usernames beside an id and display names are not matched, because the person chooses them. Empty: only this machine's own surfaces count (voice, app, dashboard, webrtc). |
requests.staleAfterHours | number (up to 8760) | 24 | Hours without activity before an open request comes back to you. |
requests.settleHandedBack | boolean | true | A request in progress whose handed-on work all came back done, and that has no activity for staleAfterHours, is closed as done instead of coming back to you. The proof is the other agent's link, or the request is marked unproven. Promises, requests with a check or a due time, and tracked plans are never closed this way. |
requests.settleOwnerWait | "off" | "warn" | "warn" | A request whose last reply asked you with tap answers, when none of them came back in that chat, is not closed by settleHandedBack. warn leaves it open and logs it; it comes back to you once quiet. A request waiting on you is never closed this way, whatever this says. |
requests.homeCloses | boolean | true | An open request with no check of its own, whose home is a GitHub or GitLab issue, pull request or merge request, is closed as done once that home is merged or closed as completed. Requests waiting on you and promises are left. |
requests.releaseOnOwnerTurn | boolean | true | When you write again in a chat, that agent's requests waiting on you there go back to work. Promises and requests with an undecided decision card are left. |
requests.autoResend.enabled | boolean | true | A request that needs attention because a usage limit or a restart stopped it is sent back to its agent once, on its own. You are told only if it stops again. Promises, tracked plans, requests with a check, and requests whose agent is not on this computer are left. See Resend once. |
requests.autoResend.afterMinutes | number (0 to 1440) | 5 | Minutes after it stopped before it is resent. A usage limit also waits until it has reset. |
requests.autoResend.holdMaxHours | number (up to 168) | 12 | Hours your notice waits for the resend. Past it, you are told as before. |
requests.jobs.enabled | boolean | follows requests.enabled | Keep one job for every run that is not your own turn too: hand-offs between agents, issue mentions, schedules, workflow steps. Not set: on when requests.enabled is on, off when it is off. true: jobs are kept even while requests.enabled is off; your own requests then leave no record. false: off. See Jobs. |
requests.jobs.wake.enabled | boolean | true | The daemon starts the next run of a job that said it would continue, and marks an open job that nothing holds as stalled. Off: processPool.maxBackgroundSeconds is not used either. See How a job keeps going. |
requests.jobs.wake.maxWakes | whole number (1 to 500) | 20 | How many times the daemon wakes one job. Past it the job is stalled, not woken. |
requests.jobs.wake.maxCostUsd | number (up to 1000) | 10 | What one job may cost, in US dollars, before the daemon stops waking it: its runs, and the replies the agent writes on its own when background work ends. |
requests.jobs.wake.graceMinutes | number (1 to 1440) | 10 | Minutes an open job may sit with no run, no wake and nobody it waits on before it is marked stalled. |
requests.jobs.wake.maxBackgroundMinutes | number (1 to 1440) | 180 | Minutes a job waits on background work its run left (a script, a build) before it is marked stalled. |
requests.ownerCheck.enabled | boolean | false | Read every request close you did not make yourself against your own words. A close that does not deliver what you asked opens again as needing attention, and you are told once. See the owner-words check. |
requests.ownerCheck.provider | string | "claude-code" | Provider for the check's call. Use one you already set up. |
requests.ownerCheck.model | string | "claude-sonnet-5-5" | Model that reads each close. |
requests.ownerCheck.perCheck | number (1 to 20) | 2 | Closes read per requests check, once a minute. |
requests.ownerCheck.maxAgeHours | number | 48 | Closes older than this are not read. |
requests.ownerCheck.timeoutSeconds | number (5 to 300) | 60 | How long one call may take before it is tried again at the next check. |
requests.closeProof.mode | "off", "warn" or "block" | "off" | Proof for each thing you asked for, before a check closes the request (retro:01M70Z38BBZYRBBCZW2T1S3T3K). When it is not "off", the words of open requests that can close on their own go to the ownerCheck model once, before any close, to list what they ask for. "warn" closes and records one signal; "block" keeps the request open and tells the agent once. See Proof for each thing you asked for. |
requests.closeProof.perCheck | number (1 to 20) | 2 | Requests whose words are read per requests check, once a minute. |
requests.closeProof.askPerCheck | number (1 to 20) | 3 | Agents told per requests check which items need a link. |
requests.flow.timeZone | string | "Africa/Tunis" | The time zone whose day the daily flow rate counts by (agentx requests flow). |
requests.flow.days | whole number (1 to 90) | 7 | Days the flow rate shows when none are asked for. |
requests.promises | object | {} | One record for everything someone owes: proof on close, a fact when it closes. See A promise closes with proof. |
requests.promises.requireProof | boolean | true | An agent's done on a promise needs a proof: a link, a passing test run, an output, or a check that ran. false: any evidence closes it. |
requests.promises.facts | boolean | true | A promise closed with a proof writes a checked fact to the wiki's fact ledger (agentx wiki facts list). |
requests.promises.factTtlDays | number (up to 3650) | 7 | Days that fact stays trusted before it shows as stale. |
requests.promises.watchers | boolean | true | A task watcher that fires raises the request that follows its task, or opens a promise for it, and you are told once through the requests check. false, or an address in watchers.owner: the watcher tells you itself. |
requests.promises.cards | boolean | false | A decision card raised outside a request is a promise you owe, closed when you decide it. |
requests.catchPromises | object | {} | Catch "I'll do X": at the end of each of your turns, one short model call reads the agent's reply. A firm promise becomes a promise of that agent; a reply that asks you leaves the request waiting on you. See Promises caught in a reply. |
requests.catchPromises.enabled | boolean | true | Reads the replies. On by default wherever requests are on; it spends one model call on most of your turns, bounded by dailyCap. Also agentx requests settings --catch on|off. |
requests.catchPromises.dailyCap | number (1 to 10000) | 300 | Model calls a day (UTC), across all agents. Past it, replies are not read until the next day. Also agentx requests settings --catch-cap <n>. |
requests.catchPromises.waitingOwner | boolean | true | A reply that asks you for an answer leaves its request waiting on you, with the question. false: only promises are caught. |
requests.catchPromises.provider | string | "claude-code" | Engine for the call. claude-code uses the sign-in this computer already has (subscription or API key). |
requests.catchPromises.model | string | "claude-haiku-4-5-20251001" | Model for the call. |
requests.catchPromises.timeoutSeconds | number (5 to 120) | 30 | How long the call may take. A call that fails or runs out leaves the turn as if nothing was caught. |
requests.retentionDays | number (up to 3650) | 90 | Days a closed request is kept before it is deleted. Open requests are never deleted. |
requests.plans | object | {} | Tracked plans: a request of two or more steps, each with an owner agent, followed until every step is done. Needs requests.enabled. See Follow a request of several steps. |
requests.plans.enabled | boolean | true | Agents may make plans, and the daemon follows them. |
requests.plans.stallMinutes | number (up to 10080) | 30 | Minutes without progress before a step's agent is nudged. |
requests.plans.maxNudges | whole number (0 to 20) | 3 | Nudges per step before it counts as blocked and you are told. |
requests.plans.approveKinds | list of strings | ["message"] | Step kinds you approve once, on a decision card, when the plan is made. An approved message step is sent by the daemon without asking again. |
requests.plans.disabledAgents | list of strings | [] | Agents that may not make a plan. |
requests.plans.requireForWork | list of strings | ["code"] | Kinds of work an agent must plan before it starts. The agent is told to plan first: its accept without steps is turned down. While this list or requireOverMinutes is set, an accept without steps must name its work. Covers recorded requests only. []: no kind needs a plan. See Plan before starting. |
requests.plans.requireOverMinutes | number (0 to 10080) | 30 | Work the agent estimates at more than this many minutes needs a plan. 0 turns this off. |
requests.plans.continue | object | {} | Keep a moving step going: when a turn on a plan step ends and the step moved (its count went down, or new progress was reported), the next turn starts at once instead of after a nudge. See Keep a moving step going. |
requests.plans.continue.enabled | boolean | false | Start those turns. |
requests.plans.continue.only | list of strings | [] | Only plans whose request id or goal id is listed. Empty: every plan. |
requests.plans.continue.maxTurnsPerDay | whole number (1 to 200) | 10 | Such turns per goal (or per request without a goal) per UTC day. At the cap you are told once, and the nudges take over. |
requests.plans.continue.maxCostUsdPerDay | number (up to 1000) | 5 | What those turns may cost per goal per UTC day, in USD. |
requests.sprints | object | {} | Sprint lanes: a lead agent hands AgentX lanes of issues, and AgentX gives each lane its next issue when the lane's turn ends. Needs requests.enabled. See Run a sprint in lanes. |
requests.sprints.enabled | boolean | true | Agents may start sprints, and the daemon follows them. |
requests.sprints.idleMinutes | number (up to 10080) | 30 | Minutes a lane may sit idle with issues left before you are told. A sprint can set its own. |
requests.checkers | object | {} | Checks that close a request or a promise on evidence (closeWhen). See Close on evidence, not on a claim. |
requests.checkers.enabled | list of strings | all four | Checks agents may use: url, issue, git-ancestor, reply. A request whose check is not on the list is unverified. |
requests.checkers.checkEveryMinutes | number (up to 1440) | 10 | Minutes between two runs of a request's check. |
requests.checkers.repos | object | {} | Local copies of repositories the git-ancestor check may read, by name: { "app": "/srv/app" }. Agents give the name, never a folder. |
requests.checkers.github | object | — | The issue check's GitHub access: apiUrl (default https://api.github.com) and token. Unset: channels.github.token (or tokenFile). |
requests.checkers.gitlab | object | — | The issue check's GitLab access: url and token. Unset: channels.gitlab.host and channels.gitlab.token. |
requests.statusDrift | object | {} | Tells you when an issue's status label is behind the work: merged but still Doing, live but not Done, Done but not live. See When an issue's status is behind the work. |
requests.statusDrift.enabled | boolean | true | Runs the check. It reads nothing until projects lists one. |
requests.statusDrift.checkEveryMinutes | number (5 to 1440) | 30 | Minutes between two checks. |
requests.statusDrift.lookbackDays | number (1 to 60) | 7 | How far back merged merge requests are read. |
requests.statusDrift.projects | list | [] | The projects read: { "provider": "gitlab", "project": "group/app", "live": ["self", "https://app.example.com/health"], "repo": "app" }. live: every place where the running commit is read: self (this computer's build) or a health address. Empty: live is not known, and only "merged, not in Review" is told. repo: a name from requests.checkers.repos, so the live check uses a local copy. |
requests.statusDrift.liveField | string | "commit" | The field of a health address's JSON that holds the running commit. A dotted path works. |
requests.statusDrift.labels | object | To Do, Doing, Review, Done (also Status:: scoped) | The status labels for todo, doing, review and done, any case. The first done label is the one written. |
requests.statusDrift.doneNotLiveAfterHours | number (0 to 720) | 24 | "Done, not live" is told only once a merge has waited this many hours to go live. A forge closes the issue when the change merges, before any deploy. |
requests.statusDrift.write | boolean | false | Write mode: an issue whose work is live gets its Done label, loses its other status labels and gets a comment with the proof. It is never closed. Needs the project in writeProjects too. |
requests.statusDrift.writeProjects | list of strings | [] | The projects write mode may change. Leave clients' projects out. |
requests.headlines | object | {} | Headlines: a few words that say what a request is, used as the title of its card, its notification and its Desk line instead of your own words. The agent writes them; when it did not, AgentX writes the headline once with one short model call. See What a request's card shows. |
requests.headlines.enabled | boolean | true | Writes the missing headlines. Off: a card is titled with the start of your words, as before. Also agentx requests settings --headlines on|off, or the box Write a headline when the agent gave none on the Approvals page. |
requests.headlines.provider | string | "claude-code" | Engine for the call. claude-code uses the sign-in this computer already has (subscription or API key); no new paid account is used. |
requests.headlines.model | string | "claude-haiku-4-5-20251001" | Model for the call. A small, fast model is enough. |
requests.headlines.timeoutSeconds | whole number (5 to 120) | 30 | Longest wait for one headline. A request whose headline could not be written keeps your words as its title and is not asked about again. |
numbers
Tracked numbers and their readings. See Track numbers over time. Empty by default: nothing changes until a number exists.
| Key | Type | Default | What it does |
|---|---|---|---|
numbers.items | object | {} | Numbers you set up, by id. Agents cannot change or archive them. |
numbers.items.<id>.name | string (up to 120 characters) | required | What the number counts, in plain words. |
numbers.items.<id>.owner | string (agent id) | — | The agent that looks after it. |
numbers.items.<id>.unit | string (up to 30 characters) | — | views, clients, %… |
numbers.items.<id>.target | number | — | The value it should reach. |
numbers.items.<id>.direction | up or down | up | up: higher is better. down: lower is better. Needs target. |
numbers.items.<id>.rhythm | daily, weekly or monthly | weekly | How often it gets a reading. UTC; weeks start on Monday. |
numbers.items.<id>.tags | list of strings | [] | Such as channel:video. One word each, up to 20. |
numbers.items.<id>.source | object | {"kind": "manual"} | Where readings come from: manual, count, http-json (with headers allowed here) or command. See Where the values come from. |
numbers.retryMinutes | whole number (5 to 1440) | 60 | Minutes before a failed read is tried again. |
numbers.missedTwiceCard | boolean | true | A number that misses its target twice in a row raises one decision card for its owner agent. false: no card; agentx numbers review still lists it. See When a number misses twice. |
numbers.reviewer | string (agent id) | unset | An agent that checks the owner's follow-up on a missed-twice card. It is told when you say yes, and gets the card itself when the number has no owner agent on this computer. |
watchers
Task watchers: when a task starts (a message to an agent, a hand-off from one agent to another, a scheduled run), AgentX decides whether something should watch it. A watched task that passes its due time with no done signal, or that ends without a result, is reported to the agent that handed it over, and then to you. Off by default.
The decision is the task-watch decision seat: it gives the chance that the task carries a deadline, a promise to you, or a hand-off. A watcher is attached unless the seat is active and the chance is below noBelow. A seat that is off, failed, in shadow mode or unsure attaches one. How it works, step by step: Watch tasks that must finish.
| Key | Type | Default | What it does |
|---|---|---|---|
watchers.enabled | boolean | false | Runs the check at every task start and follows the watchers. |
watchers.skipChannels | list of strings | [] | Channels whose tasks are never checked, for example ["voice"]. The watchers' own alert turns (channel watchers) never are. |
watchers.defaultDueMinutes | number (up to 43200) | 120 | Minutes from the start of a task to its due time, when the task gives none. A caller gives one as dueAt (an ISO date or milliseconds) in the task's context. |
watchers.noBelow | number (0 to 1) | 0.2 | A chance below this is a confident "no". Only an active seat skips the watcher on it. |
watchers.yesAt | number (0 to 1) | 0.7 | A chance at or above this is recorded as "yes". Between noBelow and yesAt it is "uncertain", which attaches a watcher. |
watchers.escalateAfterMinutes | number (up to 10080) | 30 | Minutes after the agent that handed the task over is told before you are told too, if the task is still not done. |
watchers.owner.channel | string | — | Channel you are told on. Unset: your default notification channel. |
watchers.owner.chatId | string | — | Chat on that channel. Unset: default. |
watchers.retentionDays | number (up to 3650) | 30 | Days a finished watcher is kept before it is deleted. Watchers still watching are never deleted. |
watchers.doneSignal | "result" or "explicit" | "result" | What closes a watcher. result: the agent's run ends with a reply, or the delegation answers. explicit: only POST /watchers/<id>/done, so a reply that only promises ("I'll publish at 18:00") keeps the watcher open until its due time. A run that ends without a result fires at once in both modes. |
watchers.evidence.<type> | object | — | Proof a done needs for tasks of this type. The type is the task's taskType (from POST /task, POST /send/agent, the agentx_send_agent and agentx_task tools, or a cron job's taskType), else the watcher's kind: dispatch, delegation or cron. A task of a type with a rule is never closed by its reply, only by a done whose evidence the rule accepts; anything else is refused. A cron or dispatch run with a rule is told in its own instructions how to close its watcher. The proof is what the agent reports: AgentX checks its shape, not that it is true. Types with no rule close as doneSignal says. See Require proof of done. |
watchers.evidence.<type>.accept | list of "test", "output", "link" | required | The kinds of proof that count; any one of them closes the task. test: at least one test passed and none failed. output: the text the task produced. link: an http or https address. |
watchers.evidence.<type>.minOutputChars | number (1 to 2000) | 40 | The shortest output accepted. |
watchers.evidence.<type>.linkHosts | list of strings | [] | Sites a link must be on, for example ["example.com"] (its subdomains count too). Empty: any site. |
requestStatus
Request status: a person who asks an agent for work in a GitLab or GitHub thread sees the state of that request in the same thread. Off by default. It works on its own; requests.enabled does not have to be on.
When it is on for a channel, AgentX posts one comment for each request and edits that same comment as the work moves. It is never posted twice. The comment shows one of these states:
| State | When |
|---|---|
| Queued | The agent is busy with an earlier message in the same thread. |
| Working | The agent's turn started. |
| Waiting on agent | The agent handed the work to another agent and waits for its answer. |
| Waiting on an answer from the owner | The agent raised a decision card and waits for it. The comment does not show the question. |
| Done | The turn ended and nothing it handed out is still open. |
| Failed | The turn, or work it handed out, ended with an error. Also a queued message whose turn could not start. |
| Timed out | The turn, or work it handed out, hit its time limit, or a decision card expired without an answer. |
| Stopped | Someone stopped the run. |
| Cut off by a restart | A restart stopped the run and it was not picked up again. Written after the daemon is back. |
The comment names the agent that was asked, the state, the time (UTC) and, while waiting, the agent the work waits on. It never shows an error text, a file path, a machine name or anything about other requests.
Every event that starts a turn in an issue, a merge request or a pull request gets a status comment: a comment from a person, and also an assignment or a newly opened issue or pull request. An event with no thread to comment on, such as a pipeline or a push, gets none.
When the comment cannot be written (the token is refused, the issue was deleted), AgentX tries again once a minute and stops after five failed tries. It tries once more each time the state changes.
While it is on for GitLab, an agent that is assigned an issue or a merge request is no longer asked to write its own acknowledgement comment: the status comment is the acknowledgement.
To turn it on:
- Open a terminal in the folder that holds
agentx.json. - Run
agentx request-status gitlab on(orgithub). The running daemon picks the change up; no restart is needed. - Or, in the browser: Settings › Channels, open GitLab or GitHub, and switch Request status on.
| Key | Type | Default | What it does |
|---|---|---|---|
requestStatus.channels | list of strings | [] | Channels that show request status: gitlab, github. Empty: off. Ended requests are forgotten after requests.retentionDays. |
In a mesh, an edit is made with the same agent account that wrote the comment. When that account's token lives on another machine, the edit is sent there; that machine must run a version that has request status, or the comment stays at its first state.
qualityReport
The weekly quality report posted on a GitHub issue every Monday, and the gates it reports on. Off by default. Turn it on on one computer only. See post a weekly quality report.
| Key | Type | Default | What it does |
|---|---|---|---|
qualityReport.enabled | boolean | false | Posts the report every week. Needs repo and issue. |
qualityReport.repo | string owner/name | — | The GitHub repository of the issue. |
qualityReport.issue | number | — | The issue the report is posted on. |
qualityReport.time | string HH:MM | "08:00" | When the report is due on Monday. A daemon that was off then posts later that week. |
qualityReport.timezone | string | — | The timezone time is read in, for example Europe/Paris. Unset: this computer's. |
qualityReport.command | list of strings | ["agentx", "quality", "report", "--public"] | The command whose output is posted, shown as a fixed-width block. AgentX adds --repo <repo> (unless the command already has one), --since <Monday> --until <Sunday> for the week and --compare <baseline>. A leading agentx runs the same AgentX install as the daemon, whatever its PATH. The week is also in AGENTX_QUALITY_WEEK, AGENTX_QUALITY_FROM and AGENTX_QUALITY_TO, and the repository in AGENTX_QUALITY_REPO. |
qualityReport.baseline | string | "baseline" | The baseline saved with agentx quality report --save-baseline. Each week is compared with it, and the verdict quotes its fix share. |
qualityReport.timeoutSeconds | number (10–3600) | 600 | Time limit for the command. |
qualityReport.gates | list | [] | The gates and when they were on, shown in each comment. |
qualityReport.gates[].id | string | required | Short name, used by agentx quality verdict --gate. |
qualityReport.gates[].label | string | — | Name shown in the comment. Unset: id. |
qualityReport.gates[].since | string YYYY-MM-DD | required | The day the gate went on. The verdict is due three weeks after the first gate's since. |
qualityReport.gates[].until | string YYYY-MM-DD | — | The day the gate went off. |
improve
Self-improvement from failure signals. Counting the signals is always on and costs nothing. Everything that uses an AI model is off until improve.enabled, and then held to a daily limit in dollars and in cards. See see what keeps going wrong.
| Key | Type | Default | What it does |
|---|---|---|---|
improve.enabled | boolean | false | Lets the nightly pass use an AI model. Off: it only ranks, at no cost. |
improve.dailyUsd | number (0–50) | 3 | Dollars the nightly pass may spend in any 24 hours. A call that would go past it is not started. A call whose cost is not reported is counted at a high estimate. |
improve.maxCardsPerDay | number (0–3) | 1 | Decision cards the self-improvement pass may raise in any 24 hours. The retro's own limit of three a day still holds. |
improve.mergeModel | string | "haiku" | The small model that merges problems worded differently, once a day. Empty: no merge. |
improve.minRefs | number (2–50) | 3 | A problem is ranked only once it came from this many separate requests, hand-offs or runs. |
shutdown
How a daemon stop treats tasks that are still running. See restart without losing work.
| Key | Type | Default | What it does |
|---|---|---|---|
shutdown.drainTimeoutSeconds | number (0–86400) | — | How long a stop waits for running tasks before stopping them. Unset: AGENTX_DRAIN_TIMEOUT_MS from .env, else 300. An agent's own drainTimeoutSeconds can make the wait longer. Keep the service's stop time above it. |
shutdown.restart.allowBy | string (regular expression) | — | Who may ask for "restart when idle" right away, matched against the request's by (for example ^(operator|restart-window)). Requests from anyone else are held until window, or refused when there is no window. Unset: anyone. |
shutdown.restart.window | string HH:MM (local time) | — | When held requests start their wait for an idle moment. |
shutdown.restart.windowWaitMinutes | number (1–1440) | 180 | How long that wait lasts before it gives up without restarting. |
shutdown.restart.forbidOnTimeoutRestart | boolean | false | Turns every request into an idle-only one: a wait that runs out gives up instead of restarting over running work. |
resume
What happens to work a restart cut off. Chat messages are picked up again in their chat; schedules never are, because their next run covers them. See restart without losing work.
| Key | Type | Default | What it does |
|---|---|---|---|
resume.enabled | boolean | true | Picks up cut-off work after a restart. |
resume.maxAgeMinutes | number (1 or more) | 30 | Work older than this is reported, not picked up. |
resume.maxAttempts | number | 1 | How many times a run is picked up again if it keeps getting cut off. |
resume.reportOnlyChannels | list of strings | [] | Channels whose runs are only reported, even from a chat. |
resume.directChannels | list of strings | [] | Other channels (voice, webhooks, the API) whose runs are picked up again. Their answer is not delivered anywhere. An agent-to-agent run that names the agent which asked is always picked up: its answer goes to that agent. |
resume.crashLoop | object | {} | Stops picking up work when the daemon keeps restarting. |
resume.crashLoop.restarts | number (1 or more) | 3 | This many restarts… |
resume.crashLoop.windowMinutes | number | 10 | …within this many minutes pauses picking up work. |
resume.timeLimit | object | {} | Work stopped at its agent's time limit (maxExecutionMinutes). See work that runs past its time limit. |
resume.timeLimit.enabled | boolean | true | Picks the work up again in the same conversation, with a note that it hit its time limit. Scheduled jobs and workflow steps never are. |
resume.timeLimit.maxContinuations | number (0–3) | 1 | How many times one request is picked up again after its time limit. |
jobState
| Key | Type | Default | What it does |
|---|---|---|---|
jobState.enabled | boolean | true | A run of agent work ends by stating its job's state: done, continue, waiting or blocked. See Say where the work stands when a run ends. |
jobState.channels | list of strings | ["a2a", "cron", "reminder", "events"] | Channels whose runs must state it. Chat with a person is never checked. |
quality
Release quality gates. Each one has its own switch and is off unless you turn it on.
quality.canary holds a release back from a second machine until it has run on this one for a while without new trouble. See soak a release before deploying it.
| Key | Type | Default | What it does |
|---|---|---|---|
quality.canary.enabled | boolean | false | Makes agentx daemon deploy refuse a release that has not passed its soak. Only the literal true turns it on. Off: deploys work as before. Other ways of shipping a release are not gated. |
quality.canary.soakMinutes | number (1–10080) | 120 | How long a release must run on this daemon. |
quality.canary.thresholds.maxRestarts | number | 1 | Restarts allowed during the soak, not counting the one that started it. |
quality.canary.thresholds.maxCrashes | number | 0 | Stops without being asked to (crash, forced kill) allowed during the soak. |
quality.canary.thresholds.maxFailedTasks | number | 3 | Failed or timed-out tasks allowed during the soak. Stopped tasks do not count. |
quality.canary.thresholds.maxErrorRateIncrease | number (0–1) | 0.1 | How much the share of failed tasks may rise over the release before, as a fraction: 0.1 is 10 percentage points. |
quality.canary.thresholds.minTasksForRate | number | 10 | Fewer tasks than this during the soak skips the error-rate check. |
A crash loop (resume.crashLoop above) during the soak always fails it.
signals
Pausing a running task with a resume plan, and resuming it later. You may always pause or resume; an agent may pause or resume a task it handed out. See Pause a task and resume it later.
| Key | Type | Default | What it does |
|---|---|---|---|
signals.enabled | boolean | true | Turns pausing and resuming on. Off: every signal is refused, yours included. |
signals.windDownSeconds | number (10–1800) | 120 | How long a paused agent gets to write its resume plan. Past it, the plan-writing turn is stopped and AgentX writes the plan from the run's trace. A task with background builders first gets up to 60 more seconds to save their work on WIP branches. |
signals.allowAgents | list of strings | [] | Agents that may pause or resume any task on this machine. "*" allows every agent. An agent never pauses its own task. |
signals.allowPeers | list of strings | [] | Mesh machines (their node names) whose signals this machine accepts, including a stop-all order (agentx signal stop --all --mesh). A machine using its own token from mesh.peers is that machine, with or without naming itself. The list does not hold for the shared MESH_TOKEN: such a machine is believed about its name, and counts as the owner when it names none. Use per-peer tokens in mesh.peers if machines are not equally trusted. |
signals.maxPerRoot | number (1–100) | 6 | Loop brake: most signals from agents and other machines one request (one root id) may carry in a day. The owner's are never counted. |
signals.saveBuilderWork | boolean | true | When a stop stops a task with background builders, save the changes they left uncommitted as one commit on a local agentx/wip/<taskId> branch in each git folder, without touching the checkout or pushing. false: nothing is written in those folders, each one with changes is listed as not saved, and the stop does not add the 60 seconds for saving. |
reminders
Hands due Apple Reminders back to the agent that created them. macOS only, off by default. See Hand due reminders back to agents.
| Key | Type | Default | What it does |
|---|---|---|---|
reminders.enabled | boolean | false | Turns the hand-back on. Ignored, with a log line, on machines other than a Mac. |
reminders.lists | list of strings | ["AgentX"] | Reminders lists to watch. |
reminders.pollSeconds | number (15 or more) | 60 | How often the lists are read. |
reminders.lookbackHours | number | 24 | A reminder overdue by more than this (the daemon was off) is reported to its agent, not run. |
reminders.command | string | "remindctl" | The remindctl program, or its full path when the daemon can't find it. |
native
How AgentX uses the apps that come with the operating system, such as Reminders and Notification Center. All of this goes through one adapter per operating system. agentx doctor shows a "Native" line that says what this machine offers.
| Key | Type | Default | What it does |
|---|---|---|---|
native.adapter | "auto" or "none" | "auto" | "auto" picks the adapter for this operating system. "none" turns it off on this machine. A machine with no adapter yet gets "none" either way. |
native.mirror.enabled | boolean | false | Puts each waiting card and request in Reminders with a due time. See See waiting decisions in Reminders and Calendar. |
native.mirror.list | string | "AgentX Desk" | The Reminders list. Must not start with -, and must not be one of reminders.lists or approvals.checkin.lists. |
native.mirror.dueAfterMinutes | number (0–1440) | 5 | How long after a card is raised its reminder falls due. Never later than the card expires. |
native.mirror.include | list of "card", "request" | ["card", "request"] | What is mirrored: decision cards, requests waiting on you, or both. |
native.mirror.answerUrl | URL | — | The address in each reminder where you answer. Unset: http://localhost:<dashboard.port>/hub#status=open&view=decide (Needs you on the Hub). |
native.forwardTo | string | — | The mesh peer with the owner's notes app, for a machine without one. Unset: approvals.forwardTo. |
native.notes.enabled | boolean | false | Lets agents put ideas in Apple Notes with agentx_note. See Get agents' ideas in Apple Notes. |
native.notes.folder | string | "AgentX" | The Notes folder. Created the first time. |
native.notes.perAgentPerDay | number (1–50) | 10 | Most notes one agent may add in a day. |
wiki
Settings for the shared wiki. See Let agents keep the wiki up to date.
| Key | Type | Default | What it does |
|---|---|---|---|
contributions.schedule | schedule | "40 22 * * *" | When each agent with agents.<id>.wiki.contribute.enabled reviews its day (the wiki-contribute job). |
contributions.mergeSchedule | schedule | "20 23 * * *" | When the queued suggestions are applied (the wiki-contribute-merge job). |
contributions.timezone | string | "UTC" | Time zone of both schedules. |
contributions.maxCostUsd | number (0–20) | 0.5 | Model spend per agent per run, in dollars, for agents that set no limit of their own. |
contributions.model | string | "sonnet" | Model for the daily run, for agents that name none. |
query.shared | boolean | true | Wiki searches also read other agents' pages the agent may see, and the shared lessons. |
query.method | "auto", "summaries" or "catalog" | "auto" | How a wiki question picks its pages. summaries: from the one-line page summaries, then a live read. catalog: from page titles, then along the links between pages. auto: summaries once at least 80% of the agent's own pages have a summary. See Get wiki answers checked at the source. |
query.candidates | number (1–50) | 12 | How many of the agent's own pages the picking model sees. |
query.sharedCandidates | number (0–50) | 4 | How many of other agents' pages it sees beside them. |
query.maxPages | number (1–10) | 3 | Most pages opened for one answer. |
query.pageChars | number (200–40000) | 4000 | Characters of each opened page given to the answer. |
query.linkedPages | number (0–10) | 0 | Pages linked from the picked pages that are also opened, best summary line first. 0 opens none. |
query.linkedChars | number (200–40000) | 6000 | Characters all the linked pages together give to the answer. |
query.navigatorModel | string | "haiku" | Model that picks the pages. |
query.answerModel | string | "sonnet" | Model that writes the answer. |
query.notes.enabled | boolean | false | The summaries method also searches the asking agent's own notes. Only that agent's notes, never another agent's. Through the agentx_wiki_query tool, only for the agent the tool runs as. Notes can hold contact details, so turn this on only for agents whose answers go back to the same agent. See Search the agent's own notes. |
query.notes.types | list of strings | ["project", "reference"] | Note types searched. |
query.notes.candidates | number (1–50) | 4 | How many of the agent's notes the picking model sees beside its pages. |
query.live.enabled | boolean | true | The live read before the answer. false switches it off. |
query.live.maxReads | number (0–20) | 6 | Most reads for one question. |
query.live.timeoutMs | number (1000–120000) | 15000 | How long one request to a source may take, in milliseconds. A deploy read makes up to four rounds of requests, so it can take up to four times this. |
query.live.plannerModel | string | "haiku" | Model that names the reads. |
query.live.sources | list | [] | Where a live read may read from. Empty: no live read runs. |
query.live.sources[].type | "github", "gitlab" or "agentx" | — | The kind of system. |
query.live.sources[].repos | list | — | github and gitlab: the repositories that may be read, each "owner/name" or an object with repo and about. At least one. |
query.live.sources[].repos[].repo | string | — | The repository, as owner/name or a GitLab project path. |
query.live.sources[].repos[].about | string | unset | What lives there, so the model names the right repository. |
query.live.sources[].apiUrl | string | "https://api.github.com" | github: the API address. |
query.live.sources[].url | string | channels.gitlab.host, or this machine | gitlab: the host. agentx: the daemon to ask. |
query.live.sources[].tokenEnv | string | unset | github and gitlab: name of the environment variable that holds a read token. |
query.live.sources[].tokenFile | string | unset | github and gitlab: a file whose first line is the read token. |
query.live.sources[].peers | boolean | true | agentx: also ask each machine connected to the daemon. |
summaries.model | string | "haiku" | Model that writes the one-line page summaries. |
summaries.batchSize | number (1–50) | 20 | Pages per model call. |
summaries.maxWords | number (5–120) | 35 | Longest summary, in words. |
summaries.schedule | schedule | unset | When agentx wiki summarize --all runs on its own (the wiki-summarize job). Unset: no job. |
summaries.timezone | string | "UTC" | Time zone of that schedule. |
summaries.agent | string | unset | Agent the job is listed under. Unset: node.defaultAgent, else the first agent. |
The two contribution jobs exist only while at least one agent is switched on. A job you define under crons with the same id (wiki-contribute, wiki-contribute-merge or wiki-summarize) replaces the built-in one.
Check it worked
- Terminal: in the folder with
agentx.json, runagentx config check. It prints✓ Config valid. - Terminal: run
agentx config get <path>for the key you changed, for exampleagentx config get workflows.matching.mode. It prints the new value. - Terminal: for a job, run
agentx schedule list. The job appears with its schedule.
If something is wrong
config checksays a cron needs a prompt or a command: add one of them to that job.config checkrejectsautonomyon a job: the job has acommand. Removeautonomyor the command.- A webhook is refused with 401: the entry has
secretEnv, but that variable is missing from.envor holds a different secret. Fix it and restart the daemon. config checkrejectsexpectExitZeroon a job: the job has acommand, which already fails on a non-zero exit. RemoveexpectExitZero.- A job with
expectExitZerofails with "did not report the command's exit code": the agent's answer had noEXIT=<code>line. Read the run's answer; if the agent never ran the command, make the prompt name it plainly. - A job stopped running: it may have been turned off after 3 failures (
onErrorincludesdisable). Fix the cause, then setenabledback totrue.
