Skip to content

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.

KeyTypeDefaultWhat it does
enabledbooleantrueTurns the job on or off without deleting it.
schedulestringrequiredWhen the job runs, as a cron expression such as 0 7 * * 1.
timezonestring"UTC"The timezone the schedule is read in, for example Europe/Paris.
agentstringrequiredThe agent that runs the prompt. For a command job, the agent told when it fails.
promptstring""What the agent is asked to do. A job needs a prompt or a command.
commandstring—A shell command run directly instead of an agent: no model, no tokens.
timeoutnumber600Time limit in seconds. Agent jobs get at least 2 hours; see time limits.
modelstring—Model for this job only, instead of the agent's model.
maxOutputTokensnumber (50–8000)—Asks the agent to keep its answer under about this many tokens. A soft cap added to the prompt.
taskTypestring (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.
requireSourcesboolean—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.
expectExitZeroboolean—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.
valueobject—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.whystring (1–200 characters)requiredWhy the job runs, for example Keeps the support queue answered overnight.
value.metricstring (1–200 characters)requiredThe number that proves it, for example Tickets older than 12 h each morning: 0. AgentX does not measure it.
value.numberstring (number id)—The tracked number that measures it, for example video-views. See Track numbers over time.
goalstring (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.
notifyobject—Where this job's messages go: the answer from each successful run, and failure messages.
notify.channelstringrequiredChannel for the job's messages, for example telegram.
notify.chatIdstringrequiredThe chat on that channel.
notify.accountIdstring—Which account on that channel, when you have more than one.
deliverResultbooleantrueSends 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.
fireTokenstring—Secret that lets another system start the job now. See fire a routine.
createdBystring—The agent that created the job from chat. Set by AgentX; an agent may only manage jobs it created, unless it is an admin.
approvalobject—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"requiredWhat the agent asked for. A job waiting on create never runs.
approval.requestedBystringrequiredThe agent that asked.
approval.requestedAtstringrequiredWhen it asked (date and time).
json
"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.

  1. Editor: if the job only runs the command, move it from prompt to command. No agent and no tokens are used.
  2. Editor: if the agent must read or act on the result, keep the prompt and add "expectExitZero": true to the job.
json
"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.

KeyTypeDefaultWhat it does
exceptionsDigest.enabledbooleanfalseTurns the digest on.
exceptionsDigest.timestring (HH:MM, 24-hour)"09:00"When it goes out each day.
exceptionsDigest.timezonestring—Time zone time is read in, for example Europe/Paris. Unset: this computer's.
exceptionsDigest.destinationobject—Where it goes: channel, chatId and optional accountId. Unset: notifications.destination.
json
{
  "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.

KeyTypeDefaultWhat it does
wikiNotes.enabledbooleanfalseTurns wiki notes on for this node. Needs wikiNotes.inbox.
wikiNotes.inboxstring—Agent that runs the wiki observe/sweep schedule. Notes are kept on its node; other nodes forward theirs to it.
wikiNotes.cronsstring[][]Schedule ids (keys of crons) that read the inbox when they start. Each must run as the inbox agent.
wikiNotes.absorbAgentstring—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.maxNotesPerRunnumber (1-100)20Most notes one run is given, open notes before deferred ones. The rest wait for the next run.
wikiNotes.maxDeferralsnumber (1-20)3A note deferred this many times expires and is no longer offered.
json
{
  "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.

KeyTypeDefaultWhat it does
namestringrequiredName shown in lists and logs.
triggerslist of objectsrequiredPatterns that start the service.
patternstringrequiredA trigger's regular expression, matched against the message text, ignoring case.
channelstring—Limits a trigger to one channel, for example whatsapp.
allowedContactslist of strings—Only these senders can start the service. Unset: anyone.
agentstringrequiredThe agent that runs the prompt.
promptstringrequiredThe prompt sent to the agent when a trigger matches.
schedulestring—A cron expression kept with the service. The daemon does not run services on a schedule yet; use crons for timed work.
timezonestring"UTC"Timezone for schedule.
notifyobject—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.

KeyTypeDefaultWhat it does
idstringrequiredShort name for the entry: lowercase letters, digits, - and _.
sourcestringrequiredThe sending system, for example github, gitlab or stripe.
agentIdstringrequiredThe agent that handles the event.
secretEnvstring—Name of the environment variable that holds the signing secret. When set, unsigned or wrongly signed requests are refused.
descriptionstring—A note for people reading the list.
enabledbooleantrueA disabled entry is ignored.
nodestring—Sends the event to this mesh peer instead of running it on this machine.
triggersmap 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.
defaultWorkflowstring—Workflow started when no triggers key matches. Unset: the agent handles the event itself.
json
"webhooks": [
  { "id": "repo-events", "source": "github", "agentId": "reviewer", "secretEnv": "GITHUB_WEBHOOK_SECRET",
    "triggers": { "pull_request.opened": "review-pr" } }
]

workflows ​

The workflow engine. See Workflows.

KeyTypeDefaultWhat it does
workflows.enabledbooleanfalseTurns the workflow engine on.
workflows.dirstring".agentx/workflows"Folder that holds workflow definitions.
workflows.n8nobject{"baseUrl":"","apiKey":""}Connects your n8n instance so the builder can list its workflows as steps.
workflows.n8n.baseUrlstring""Address of your n8n instance. Empty: not connected.
workflows.n8n.apiKeystring""n8n API key. Use an environment reference such as ${N8N_API_KEY}.
workflows.matchingobject{}Matching incoming messages to a workflow.
workflows.matching.enabledbooleanfalseChecks 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.autoRunThresholdnumber (0–1)0.85In auto mode, how confident a match must be to run the workflow.
workflows.matching.suggestThresholdnumber (0–1)0.65How 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.followUpobject{}Workflows that agents start for your requests and AgentX follows to the end. See Let a workflow follow a request.
workflows.followUp.enabledbooleantrueAgents may start follow-up workflows, and are told when a saved workflow fits a request. Needs workflows.enabled.
workflows.followUp.agentsobject{}Per agent, by id: false turns follow-up workflows off for that agent.
workflows.followUp.stallMinutesnumber30Minutes without progress before an agent step gets a reminder (a nudge). At most 10080 (7 days).
workflows.followUp.maxNudgesinteger (0–20)2Nudges 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.requiredobject{}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.enabledbooleanfalseOn for every agent. Needs workflows.enabled.
workflows.required.agentsobject{}Per agent, by id: true or false wins over enabled.
workflows.required.exemptQuestionsbooleantrueA plain question (no plan, only tools that change nothing) leaves no run.
workflows.required.retentionDaysnumber30Task 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.

KeyTypeDefaultWhat it does
procedures.enabledbooleantrueTurns procedures on.
procedures.dirstring".agentx/procedures"Folder that holds procedures.
procedures.extractionobject{}Settings for finding new procedures.
procedures.extraction.enabledbooleanfalseTurns finding new procedures on.
procedures.extraction.onTaskCompletionbooleanfalseCounts repeated patterns after each finished task. Uses no model.
procedures.extraction.minOccurrencesnumber (2 or more)3How often a pattern must repeat before it becomes a draft.
procedures.extraction.sinceDaysnumber (1 or more)7How many days of past work to look at.
procedures.extraction.maxClustersnumber (1 or more)5Most drafts made in one run.
procedures.extraction.viastring—Agent whose session writes the drafts.
procedures.injectionobject{}Giving procedures to agents.
procedures.injection.enabledbooleantrueAdds matching procedures to a new agent conversation as guidance.
procedures.injection.maxProceduresnumber (1 or more)2Most procedures added at once.
procedures.injection.minScorenumber (0–1)0.5How closely a procedure must match the request to be added.

notifications ​

Messages about finished, failed or long tasks. See get notified.

KeyTypeDefaultWhat it does
notifications.longTaskThresholdnumber30Seconds a task must run before you are told about it. 0 turns this off.
notifications.destinationobject—Where task messages go. Unset: no task messages.
notifications.destination.channelstringrequiredChannel, for example telegram or push.
notifications.destination.chatIdstringrequiredThe chat on that channel.
notifications.destination.accountIdstring—Which account on that channel.
notifications.channelstring—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.publicUrlstring—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.onobject{}Which events send a message.
notifications.on.taskCompletebooleantrueA long task finished.
notifications.on.taskErrorbooleantrueA task failed.
notifications.on.taskQueuedbooleanfalseA task had to wait in the queue.
notifications.localobject{}What agentx notify does on this Mac. macOS only.
notifications.local.bannerbooleantrueShows a desktop banner.
notifications.local.soundbooleantruePlays a sound.
notifications.local.soundNamestring"Glass"A sound from /System/Library/Sounds, without the extension.
notifications.local.volumenumber (0–1)0.4Sound volume.
notifications.local.iconstring—Image for the banner icon (.png, .jpg or .icns). Unset: the AgentX logo. Applied by agentx desktop install.
notifications.local.quietWaitSecondswhole number (0–120)15Seconds 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.toldobject{}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.enabledbooleantrueRecords and checks every message to your own addresses.
notifications.told.repeatWindowHoursnumber (up to 720)24Hours 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.channelslist of strings["push", "ntfy"]Channels that only ever reach you. Every message on them goes through the record.
notifications.told.addresseslist of strings[]Your other private chats, as channel:chatId, for example telegram:123456789.
notifications.told.digestNagsbooleantrueSystem 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.reachobject{}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.enabledbooleanfalseAn urgent message goes where you were seen last and, unseen, once to the next address.
notifications.reach.escalateAfterMinutesinteger (1 to 1440)10Minutes an urgent message waits to be seen or answered before it is sent once to the next address.
notifications.reach.ladderlist 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.deskobject{}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"unsetThe 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.

KeyTypeDefaultWhat it does
calls.allowstring[][]Agents that may call you, or ask to see: ids, or "*" for every agent. Empty: nobody.
calls.maxPerHournumber (1–60)3Most calls and camera asks one agent may place in an hour, together.
calls.ringSecondsnumber (10–300)45Seconds a call rings, or a camera ask waits on the phone, before it counts as missed.
calls.maxCallMinutesnumber (1–240)30An 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.ringSoundstring"Submarine"The ring: a sound from /System/Library/Sounds, without the extension.
calls.summarybooleantrueAfter hang-up, the agent writes a short summary, filed in the dashboard's Ask history.
calls.busy.retryMinutesnumber (1–60)5While 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.maxWaitMinutesnumber (1–240)10The longest a call waits. Still busy then, it counts as missed.
calls.busy.titlestring"Call waiting: {agent}"Title of the call-waiting notice. {agent} becomes the caller's name.
calls.busy.noticestring"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.appUrlstring (an origin)unsetThe 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.

KeyTypeDefaultWhat it does
approvals.defaultExpiryDaysnumber (up to 365)3Days a decision card waits when the agent gave no expiry.
approvals.maxExpiryDaysnumber (up to 365)30The longest any card may wait.
approvals.laterHoursnumber (up to 720)24Hours Later hides an item.
approvals.notifyAgentbooleantrueTells the agent that raised a card when it is decided or expires.
approvals.forwardTostring—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.digestobject{}One reminder a day of what is waiting.
approvals.digest.enabledbooleantrueSends the daily reminder.
approvals.digest.timestring"09:00"Time of day, 24-hour HH:MM.
approvals.digest.timezonestring—Timezone for time, for example Europe/Paris. Unset: this machine's.
approvals.digest.destinationobject—Where the reminder goes. Unset: notifications.destination.
approvals.digest.destination.channelstringrequiredChannel for the reminder.
approvals.digest.destination.chatIdstringrequiredThe chat on that channel.
approvals.digest.destination.accountIdstring—Which account on that channel.
approvals.popupobject{}Shows waiting cards on this Mac. macOS only. See Answer from a card on your Mac.
approvals.popup.enabledbooleanfalseShows 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.speakbooleantrueSpeaks one short line when the card opens.
approvals.popup.voicestring—A macOS voice for the spoken line. Unset: the system voice.
approvals.popup.soundstring"chime""chime" (the card's soft chime), a sound from /System/Library/Sounds such as "Glass", or "" for none.
approvals.popup.volumenumber (0 to 1)0.4Sound volume.
approvals.popup.timeoutSecondsnumber (10 to 3600)600How long the card waits for an answer. After that the card stays in the inbox.
approvals.checkinobject{}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.enabledbooleanfalseRuns check-ins.
approvals.checkin.dailyAtstring (HH:MM)"09:00"The daily check-in: every open reminder.
approvals.checkin.timesstring[] (HH:MM)["11:00", "14:00", "17:00"]The other check-ins: reminders due soon.
approvals.checkin.timezonestring—IANA time zone for the times. Unset: this machine's.
approvals.checkin.listsstring[]["Reminders"]Your Reminders lists to look at.
approvals.checkin.agentstring—The agent that writes cards for reminders without an agentx: line. Unset: those reminders are skipped.
approvals.checkin.dueWithinHoursnumber24A normal check-in takes reminders due within this many hours, or overdue.
approvals.checkin.maxAsksPerPassnumber (1 to 20)5Most agents one check-in asks to write a card, whatever they answer.
approvals.checkin.composeTimeoutSecondsnumber (30 to 3600)300How 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.

KeyTypeDefaultWhat it does
quality.specTests.enabledbooleanfalseA 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.pathslist of strings["src/daemon"]Folders in the pilot. Only an issue that names one of them gets spec tests.
quality.specTests.agentstring"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.modelstringunsetModel the test agent uses. Unset: the claude command's default.
quality.specTests.maxCostPerIssuenumber (up to 100)2Most the test agent may spend on one issue, in US dollars. Past it, it stops and leaves a note on the issue.
quality.specTests.maxMinutesnumber (1–120)20Most 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:

  1. Open agentx.json.
  2. Add "requests": { "enabled": true }.
  3. 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, as channel:id: your login on GitLab and GitHub, your numeric id on Telegram, your number on WhatsApp. For example "from": ["telegram:123456789", "github:your-login"].
  4. Save the file. The running daemon picks the change up; no restart is needed.
KeyTypeDefaultWhat it does
requests.enabledbooleanfalseRecords and follows your requests.
requests.channelslist of strings[]Channels to record on. Empty: every channel a person writes on (telegram, whatsapp, slack, discord, gitlab, github, app, voice, dashboard, webrtc).
requests.fromlist 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.staleAfterHoursnumber (up to 8760)24Hours without activity before an open request comes back to you.
requests.settleHandedBackbooleantrueA 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.homeClosesbooleantrueAn 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.releaseOnOwnerTurnbooleantrueWhen 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.enabledbooleantrueA 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.afterMinutesnumber (0 to 1440)5Minutes after it stopped before it is resent. A usage limit also waits until it has reset.
requests.autoResend.holdMaxHoursnumber (up to 168)12Hours your notice waits for the resend. Past it, you are told as before.
requests.jobs.enabledbooleanfollows requests.enabledKeep 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.enabledbooleantrueThe 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.maxWakeswhole number (1 to 500)20How many times the daemon wakes one job. Past it the job is stalled, not woken.
requests.jobs.wake.maxCostUsdnumber (up to 1000)10What 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.graceMinutesnumber (1 to 1440)10Minutes an open job may sit with no run, no wake and nobody it waits on before it is marked stalled.
requests.jobs.wake.maxBackgroundMinutesnumber (1 to 1440)180Minutes a job waits on background work its run left (a script, a build) before it is marked stalled.
requests.ownerCheck.enabledbooleanfalseRead 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.providerstring"claude-code"Provider for the check's call. Use one you already set up.
requests.ownerCheck.modelstring"claude-sonnet-5-5"Model that reads each close.
requests.ownerCheck.perChecknumber (1 to 20)2Closes read per requests check, once a minute.
requests.ownerCheck.maxAgeHoursnumber48Closes older than this are not read.
requests.ownerCheck.timeoutSecondsnumber (5 to 300)60How 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.perChecknumber (1 to 20)2Requests whose words are read per requests check, once a minute.
requests.closeProof.askPerChecknumber (1 to 20)3Agents told per requests check which items need a link.
requests.flow.timeZonestring"Africa/Tunis"The time zone whose day the daily flow rate counts by (agentx requests flow).
requests.flow.dayswhole number (1 to 90)7Days the flow rate shows when none are asked for.
requests.promisesobject{}One record for everything someone owes: proof on close, a fact when it closes. See A promise closes with proof.
requests.promises.requireProofbooleantrueAn 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.factsbooleantrueA promise closed with a proof writes a checked fact to the wiki's fact ledger (agentx wiki facts list).
requests.promises.factTtlDaysnumber (up to 3650)7Days that fact stays trusted before it shows as stale.
requests.promises.watchersbooleantrueA 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.cardsbooleanfalseA decision card raised outside a request is a promise you owe, closed when you decide it.
requests.catchPromisesobject{}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.enabledbooleantrueReads 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.dailyCapnumber (1 to 10000)300Model 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.waitingOwnerbooleantrueA reply that asks you for an answer leaves its request waiting on you, with the question. false: only promises are caught.
requests.catchPromises.providerstring"claude-code"Engine for the call. claude-code uses the sign-in this computer already has (subscription or API key).
requests.catchPromises.modelstring"claude-haiku-4-5-20251001"Model for the call.
requests.catchPromises.timeoutSecondsnumber (5 to 120)30How long the call may take. A call that fails or runs out leaves the turn as if nothing was caught.
requests.retentionDaysnumber (up to 3650)90Days a closed request is kept before it is deleted. Open requests are never deleted.
requests.plansobject{}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.enabledbooleantrueAgents may make plans, and the daemon follows them.
requests.plans.stallMinutesnumber (up to 10080)30Minutes without progress before a step's agent is nudged.
requests.plans.maxNudgeswhole number (0 to 20)3Nudges per step before it counts as blocked and you are told.
requests.plans.approveKindslist 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.disabledAgentslist of strings[]Agents that may not make a plan.
requests.plans.requireForWorklist 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.requireOverMinutesnumber (0 to 10080)30Work the agent estimates at more than this many minutes needs a plan. 0 turns this off.
requests.plans.continueobject{}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.enabledbooleanfalseStart those turns.
requests.plans.continue.onlylist of strings[]Only plans whose request id or goal id is listed. Empty: every plan.
requests.plans.continue.maxTurnsPerDaywhole number (1 to 200)10Such 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.maxCostUsdPerDaynumber (up to 1000)5What those turns may cost per goal per UTC day, in USD.
requests.sprintsobject{}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.enabledbooleantrueAgents may start sprints, and the daemon follows them.
requests.sprints.idleMinutesnumber (up to 10080)30Minutes a lane may sit idle with issues left before you are told. A sprint can set its own.
requests.checkersobject{}Checks that close a request or a promise on evidence (closeWhen). See Close on evidence, not on a claim.
requests.checkers.enabledlist of stringsall fourChecks agents may use: url, issue, git-ancestor, reply. A request whose check is not on the list is unverified.
requests.checkers.checkEveryMinutesnumber (up to 1440)10Minutes between two runs of a request's check.
requests.checkers.reposobject{}Local copies of repositories the git-ancestor check may read, by name: { "app": "/srv/app" }. Agents give the name, never a folder.
requests.checkers.githubobject—The issue check's GitHub access: apiUrl (default https://api.github.com) and token. Unset: channels.github.token (or tokenFile).
requests.checkers.gitlabobject—The issue check's GitLab access: url and token. Unset: channels.gitlab.host and channels.gitlab.token.
requests.statusDriftobject{}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.enabledbooleantrueRuns the check. It reads nothing until projects lists one.
requests.statusDrift.checkEveryMinutesnumber (5 to 1440)30Minutes between two checks.
requests.statusDrift.lookbackDaysnumber (1 to 60)7How far back merged merge requests are read.
requests.statusDrift.projectslist[]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.liveFieldstring"commit"The field of a health address's JSON that holds the running commit. A dotted path works.
requests.statusDrift.labelsobjectTo 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.doneNotLiveAfterHoursnumber (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.writebooleanfalseWrite 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.writeProjectslist of strings[]The projects write mode may change. Leave clients' projects out.
requests.headlinesobject{}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.enabledbooleantrueWrites 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.providerstring"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.modelstring"claude-haiku-4-5-20251001"Model for the call. A small, fast model is enough.
requests.headlines.timeoutSecondswhole number (5 to 120)30Longest 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.

KeyTypeDefaultWhat it does
numbers.itemsobject{}Numbers you set up, by id. Agents cannot change or archive them.
numbers.items.<id>.namestring (up to 120 characters)requiredWhat the number counts, in plain words.
numbers.items.<id>.ownerstring (agent id)—The agent that looks after it.
numbers.items.<id>.unitstring (up to 30 characters)—views, clients, %…
numbers.items.<id>.targetnumber—The value it should reach.
numbers.items.<id>.directionup or downupup: higher is better. down: lower is better. Needs target.
numbers.items.<id>.rhythmdaily, weekly or monthlyweeklyHow often it gets a reading. UTC; weeks start on Monday.
numbers.items.<id>.tagslist of strings[]Such as channel:video. One word each, up to 20.
numbers.items.<id>.sourceobject{"kind": "manual"}Where readings come from: manual, count, http-json (with headers allowed here) or command. See Where the values come from.
numbers.retryMinuteswhole number (5 to 1440)60Minutes before a failed read is tried again.
numbers.missedTwiceCardbooleantrueA 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.reviewerstring (agent id)unsetAn 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.

KeyTypeDefaultWhat it does
watchers.enabledbooleanfalseRuns the check at every task start and follows the watchers.
watchers.skipChannelslist of strings[]Channels whose tasks are never checked, for example ["voice"]. The watchers' own alert turns (channel watchers) never are.
watchers.defaultDueMinutesnumber (up to 43200)120Minutes 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.noBelownumber (0 to 1)0.2A chance below this is a confident "no". Only an active seat skips the watcher on it.
watchers.yesAtnumber (0 to 1)0.7A chance at or above this is recorded as "yes". Between noBelow and yesAt it is "uncertain", which attaches a watcher.
watchers.escalateAfterMinutesnumber (up to 10080)30Minutes after the agent that handed the task over is told before you are told too, if the task is still not done.
watchers.owner.channelstring—Channel you are told on. Unset: your default notification channel.
watchers.owner.chatIdstring—Chat on that channel. Unset: default.
watchers.retentionDaysnumber (up to 3650)30Days 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>.acceptlist of "test", "output", "link"requiredThe 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>.minOutputCharsnumber (1 to 2000)40The shortest output accepted.
watchers.evidence.<type>.linkHostslist 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:

StateWhen
QueuedThe agent is busy with an earlier message in the same thread.
WorkingThe agent's turn started.
Waiting on agentThe agent handed the work to another agent and waits for its answer.
Waiting on an answer from the ownerThe agent raised a decision card and waits for it. The comment does not show the question.
DoneThe turn ended and nothing it handed out is still open.
FailedThe turn, or work it handed out, ended with an error. Also a queued message whose turn could not start.
Timed outThe turn, or work it handed out, hit its time limit, or a decision card expired without an answer.
StoppedSomeone stopped the run.
Cut off by a restartA 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:

  1. Open a terminal in the folder that holds agentx.json.
  2. Run agentx request-status gitlab on (or github). The running daemon picks the change up; no restart is needed.
  3. Or, in the browser: Settings › Channels, open GitLab or GitHub, and switch Request status on.
KeyTypeDefaultWhat it does
requestStatus.channelslist 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.

KeyTypeDefaultWhat it does
qualityReport.enabledbooleanfalsePosts the report every week. Needs repo and issue.
qualityReport.repostring owner/name—The GitHub repository of the issue.
qualityReport.issuenumber—The issue the report is posted on.
qualityReport.timestring HH:MM"08:00"When the report is due on Monday. A daemon that was off then posts later that week.
qualityReport.timezonestring—The timezone time is read in, for example Europe/Paris. Unset: this computer's.
qualityReport.commandlist 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.baselinestring"baseline"The baseline saved with agentx quality report --save-baseline. Each week is compared with it, and the verdict quotes its fix share.
qualityReport.timeoutSecondsnumber (10–3600)600Time limit for the command.
qualityReport.gateslist[]The gates and when they were on, shown in each comment.
qualityReport.gates[].idstringrequiredShort name, used by agentx quality verdict --gate.
qualityReport.gates[].labelstring—Name shown in the comment. Unset: id.
qualityReport.gates[].sincestring YYYY-MM-DDrequiredThe day the gate went on. The verdict is due three weeks after the first gate's since.
qualityReport.gates[].untilstring 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.

KeyTypeDefaultWhat it does
improve.enabledbooleanfalseLets the nightly pass use an AI model. Off: it only ranks, at no cost.
improve.dailyUsdnumber (0–50)3Dollars 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.maxCardsPerDaynumber (0–3)1Decision cards the self-improvement pass may raise in any 24 hours. The retro's own limit of three a day still holds.
improve.mergeModelstring"haiku"The small model that merges problems worded differently, once a day. Empty: no merge.
improve.minRefsnumber (2–50)3A 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.

KeyTypeDefaultWhat it does
shutdown.drainTimeoutSecondsnumber (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.allowBystring (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.windowstring HH:MM (local time)—When held requests start their wait for an idle moment.
shutdown.restart.windowWaitMinutesnumber (1–1440)180How long that wait lasts before it gives up without restarting.
shutdown.restart.forbidOnTimeoutRestartbooleanfalseTurns 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.

KeyTypeDefaultWhat it does
resume.enabledbooleantruePicks up cut-off work after a restart.
resume.maxAgeMinutesnumber (1 or more)30Work older than this is reported, not picked up.
resume.maxAttemptsnumber1How many times a run is picked up again if it keeps getting cut off.
resume.reportOnlyChannelslist of strings[]Channels whose runs are only reported, even from a chat.
resume.directChannelslist 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.crashLoopobject{}Stops picking up work when the daemon keeps restarting.
resume.crashLoop.restartsnumber (1 or more)3This many restarts…
resume.crashLoop.windowMinutesnumber10…within this many minutes pauses picking up work.
resume.timeLimitobject{}Work stopped at its agent's time limit (maxExecutionMinutes). See work that runs past its time limit.
resume.timeLimit.enabledbooleantruePicks 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.maxContinuationsnumber (0–3)1How many times one request is picked up again after its time limit.

jobState ​

KeyTypeDefaultWhat it does
jobState.enabledbooleantrueA 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.channelslist 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.

KeyTypeDefaultWhat it does
quality.canary.enabledbooleanfalseMakes 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.soakMinutesnumber (1–10080)120How long a release must run on this daemon.
quality.canary.thresholds.maxRestartsnumber1Restarts allowed during the soak, not counting the one that started it.
quality.canary.thresholds.maxCrashesnumber0Stops without being asked to (crash, forced kill) allowed during the soak.
quality.canary.thresholds.maxFailedTasksnumber3Failed or timed-out tasks allowed during the soak. Stopped tasks do not count.
quality.canary.thresholds.maxErrorRateIncreasenumber (0–1)0.1How much the share of failed tasks may rise over the release before, as a fraction: 0.1 is 10 percentage points.
quality.canary.thresholds.minTasksForRatenumber10Fewer 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.

KeyTypeDefaultWhat it does
signals.enabledbooleantrueTurns pausing and resuming on. Off: every signal is refused, yours included.
signals.windDownSecondsnumber (10–1800)120How 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.allowAgentslist of strings[]Agents that may pause or resume any task on this machine. "*" allows every agent. An agent never pauses its own task.
signals.allowPeerslist 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.maxPerRootnumber (1–100)6Loop 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.saveBuilderWorkbooleantrueWhen 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.

KeyTypeDefaultWhat it does
reminders.enabledbooleanfalseTurns the hand-back on. Ignored, with a log line, on machines other than a Mac.
reminders.listslist of strings["AgentX"]Reminders lists to watch.
reminders.pollSecondsnumber (15 or more)60How often the lists are read.
reminders.lookbackHoursnumber24A reminder overdue by more than this (the daemon was off) is reported to its agent, not run.
reminders.commandstring"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.

KeyTypeDefaultWhat 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.enabledbooleanfalsePuts each waiting card and request in Reminders with a due time. See See waiting decisions in Reminders and Calendar.
native.mirror.liststring"AgentX Desk"The Reminders list. Must not start with -, and must not be one of reminders.lists or approvals.checkin.lists.
native.mirror.dueAfterMinutesnumber (0–1440)5How long after a card is raised its reminder falls due. Never later than the card expires.
native.mirror.includelist of "card", "request"["card", "request"]What is mirrored: decision cards, requests waiting on you, or both.
native.mirror.answerUrlURL—The address in each reminder where you answer. Unset: http://localhost:<dashboard.port>/hub#status=open&view=decide (Needs you on the Hub).
native.forwardTostring—The mesh peer with the owner's notes app, for a machine without one. Unset: approvals.forwardTo.
native.notes.enabledbooleanfalseLets agents put ideas in Apple Notes with agentx_note. See Get agents' ideas in Apple Notes.
native.notes.folderstring"AgentX"The Notes folder. Created the first time.
native.notes.perAgentPerDaynumber (1–50)10Most notes one agent may add in a day.

wiki ​

Settings for the shared wiki. See Let agents keep the wiki up to date.

KeyTypeDefaultWhat it does
contributions.scheduleschedule"40 22 * * *"When each agent with agents.<id>.wiki.contribute.enabled reviews its day (the wiki-contribute job).
contributions.mergeScheduleschedule"20 23 * * *"When the queued suggestions are applied (the wiki-contribute-merge job).
contributions.timezonestring"UTC"Time zone of both schedules.
contributions.maxCostUsdnumber (0–20)0.5Model spend per agent per run, in dollars, for agents that set no limit of their own.
contributions.modelstring"sonnet"Model for the daily run, for agents that name none.
query.sharedbooleantrueWiki 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.candidatesnumber (1–50)12How many of the agent's own pages the picking model sees.
query.sharedCandidatesnumber (0–50)4How many of other agents' pages it sees beside them.
query.maxPagesnumber (1–10)3Most pages opened for one answer.
query.pageCharsnumber (200–40000)4000Characters of each opened page given to the answer.
query.linkedPagesnumber (0–10)0Pages linked from the picked pages that are also opened, best summary line first. 0 opens none.
query.linkedCharsnumber (200–40000)6000Characters all the linked pages together give to the answer.
query.navigatorModelstring"haiku"Model that picks the pages.
query.answerModelstring"sonnet"Model that writes the answer.
query.notes.enabledbooleanfalseThe 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.typeslist of strings["project", "reference"]Note types searched.
query.notes.candidatesnumber (1–50)4How many of the agent's notes the picking model sees beside its pages.
query.live.enabledbooleantrueThe live read before the answer. false switches it off.
query.live.maxReadsnumber (0–20)6Most reads for one question.
query.live.timeoutMsnumber (1000–120000)15000How 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.plannerModelstring"haiku"Model that names the reads.
query.live.sourceslist[]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[].reposlist—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[].repostring—The repository, as owner/name or a GitLab project path.
query.live.sources[].repos[].aboutstringunsetWhat lives there, so the model names the right repository.
query.live.sources[].apiUrlstring"https://api.github.com"github: the API address.
query.live.sources[].urlstringchannels.gitlab.host, or this machinegitlab: the host. agentx: the daemon to ask.
query.live.sources[].tokenEnvstringunsetgithub and gitlab: name of the environment variable that holds a read token.
query.live.sources[].tokenFilestringunsetgithub and gitlab: a file whose first line is the read token.
query.live.sources[].peersbooleantrueagentx: also ask each machine connected to the daemon.
summaries.modelstring"haiku"Model that writes the one-line page summaries.
summaries.batchSizenumber (1–50)20Pages per model call.
summaries.maxWordsnumber (5–120)35Longest summary, in words.
summaries.schedulescheduleunsetWhen agentx wiki summarize --all runs on its own (the wiki-summarize job). Unset: no job.
summaries.timezonestring"UTC"Time zone of that schedule.
summaries.agentstringunsetAgent 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 ​

  1. Terminal: in the folder with agentx.json, run agentx config check. It prints ✓ Config valid.
  2. Terminal: run agentx config get <path> for the key you changed, for example agentx config get workflows.matching.mode. It prints the new value.
  3. Terminal: for a job, run agentx schedule list. The job appears with its schedule.

If something is wrong ​

  • config check says a cron needs a prompt or a command: add one of them to that job.
  • config check rejects autonomy on a job: the job has a command. Remove autonomy or the command.
  • A webhook is refused with 401: the entry has secretEnv, but that variable is missing from .env or holds a different secret. Fix it and restart the daemon.
  • config check rejects expectExitZero on a job: the job has a command, which already fails on a non-zero exit. Remove expectExitZero.
  • A job with expectExitZero fails with "did not report the command's exit code": the agent's answer had no EXIT=<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 (onError includes disable). Fix the cause, then set enabled back to true.

Released under the MIT License.