Skip to content

Approvals — every decision waiting for you, in one place ​

Some actions wait for your yes or no before an agent goes ahead: the kinds below. Everything else an agent does without asking; Keep it safe › What always waits for you has the full list. It is one list of everything waiting for you, most urgent first: Needs you on the Hub. You can answer there, from the terminal, or from the phone app. The phone app doesn't show this page: on the phone, the same list is under Activity › Needs you (Fleet and Activity on your phone).

The list brings together these kinds of item:

KindWhat it isYes doesNo does
CardA question an agent asked you directly (a decision card, explained below)Tells the agent yesTells the agent no
ScheduleA schedule an agent asked to create or remove (schedules from chat)Turns it on, or removes itDrops the request, or keeps the schedule
Memory factSomething an agent learned from an outside source (review what agents learn)Lets the agent use itKeeps it out for good
Wiki lessonA lesson proposed for the shared wikiWrites the articleDeclines it
Wiki questionTwo values for the same fact that disagree, for example two different billing statuses for one account. The card offers bothRecords the value you pick as confirmed by youDismisses the question; the wiki keeps its value
New agentAn agent another agent created (Org). It starts nothing until you answerLets it runRemoves it, and the schedules that came with it, from agentx.json; its folder is kept
WhatsApp replyA reply an agent drafted for a watched WhatsApp chat (watch a WhatsApp chat)Sends it through wacli (the WhatsApp tool AgentX uses)Drops the draft; nothing is sent
Email replyA reply an agent wrote to a customer's email (answer customer email). The text is in a box you can editSends it, as you edited it, into the customer's threadDrops the reply; nothing is sent
PostA LinkedIn or X post an agent drafted in your voice, with the past posts it followed (draft posts in your voice)Posts it through the agent's connector, or saves it as a file ready to paste when there is noneDrops the draft; nothing is published
RequestSomething you asked an agent for that failed, ran out of time, was cut off or went quiet (keep track of what you asked for)Hands it back to the agentDrops the request

Answering here is the same as answering with the older commands (agentx schedule approve, agentx memory facts approve, agentx wiki proposals approve, agentx wiki facts proposals approve, agentx wiki answer). They keep working, and both ways stay in step.

Wiki claims and other wiki questions ​

Some wiki items wait in the thousands on a busy computer, so they are not cards:

  • Wiki claims: facts an agent read in a session summary, waiting for someone to check them at their source. They show as one line under the list, for example 2,199 wiki claims wait for a check (96 new today). That line is not in the count, the daily digest or the pushes. To see and answer them:
    1. Terminal: run agentx wiki facts proposals list.
    2. Terminal: answer one with agentx wiki facts proposals approve <id> or reject <id>. agentx approvals approve fact:<id> works too.
  • Missing articles and fields (for example No article yet for …): a yes can't fill them in. They stay with agentx wiki questions and are answered with agentx wiki answer <id> "<value>".

What a decision card says ​

An agent that needs you raises a card instead of asking in chat. Every card has:

FieldMeaning
TitleWhat it is, in one line
QuestionThe yes/no question
RecommendsWhat the agent advises, and why, in one line
ExpiresWhen the card decides itself if nobody answers. Every card has one
ThenWhat the agent does at that point: discard, keep or pause. The agent picks it. A card never says yes by itself: approve is not a choice, and an older card that asked for it gets keep
SourceA link to the draft, merge request or issue
FromThe agent that asked

When you answer, or when a card expires, the agent that asked gets a message with the result and can carry on.

Only you can answer. Agents can raise cards and read the list, but nothing they can reach approves anything, and a card that expires never counts as a yes.

Answer on the Hub ​

Only the owner answers: the Hub asks for the dashboard key.

  1. Browser: open the dashboard and select Needs you in the nav. The line under the title says how many wait for you and how many you put off. It is the same count as the phone app's Desk and the daily digest.
  2. Browser: the tabs are Waiting, Put off (what you answered Later) and Answered (your yes and no answers, newest first, and the cards an agent closed, either after you answered in chat or because it withdrew them; reviews and request replies are not listed). Answered keeps the last 50 and starts empty on the day this version is installed; until then it says when its history starts. Under them, the chips narrow the list to one kind: Decisions (cards and new agents), Schedules, Memory, Wiki, Drafts (WhatsApp and email replies, posts), Requests and Reviews. Reviews are the pending intent graph classifications. They have their own chip and are not in All or the count.
  3. Browser: read the card. It says who asked, on which machine, how long ago, when it expires and what happens then. The agent's advice is under the question. On a card with choices, the advised one is already picked and marked advised. Pick another if you want.
  4. Browser: The draft, and what Yes and No do opens the message the agent gets with your answer (change the wording if you like), exactly what each answer does, and the source link.
  5. Browser: Answering unblocks names the post the card was raised on, how long it has waited, and the workflow runs paused until you answer. Unblocks: nothing waits on it means no post or run waits on it.
  6. Browser: select Yes, No or Later. Memory facts have Keep and Drop. A line opens under the buttons that says exactly what is sent, for example Send Writer: Yes, Tuesday. Select Confirm to send it, or Back to change your mind. Nothing is sent before Confirm.
  7. The note over the list says what happened. The card leaves the list, and the post it was on updates without a reload. Later puts it on Put off for a day; a card still expires on time.

Needs you on the Hub: the tabs, the kind chips, decision cards with their advice, what one unblocks, and the side column

A card raised while an agent works on a task is also on that task's post, with the same buttons. Reply instead opens that post, so you can answer with a comment.

A request whose agent asked you a question has a reply box. Send reply sends your words to the agent that has it, which goes on with the work. Hand to… gives it to another agent. Done closes it, and Drop drops it. Each one asks you to confirm first. Stalled on you means it has waited on you longer than the quiet time in the requests settings.

On a computer, the side column shows what waits on you (posts paused on an answer, runs held, the oldest wait), Answered today with a link to everything answered, and how new items reach you, with a link to the settings. With the Mac popup on, Show it on the Mac again in a card's details shows the card on your Mac. It shows within a minute.

On a phone, the cards fill the width and the buttons share it:

Needs you on a phone: the tabs, the kind chips and a card with its buttons

Anyone who opens the Hub without the dashboard key sees the same cards without buttons, under the title Needs the owner and the line Only the owner can answer these. You see them read only. The dashboard refuses their answer even if they send one.

Fictional demo data. No real agents, people or messages.

With several machines connected, a card raised on another machine shows from agent on machine and is answered on that machine.

Answer from the terminal ​

  1. Terminal: list what is waiting:
    sh
    agentx approvals list
    Each item starts with a key such as card:2026-01-05-send-the-newsletter-ab12 or schedule:friday-summary. It works from any folder: the daemon records the folder it runs in, and agentx approvals reads the inbox there. Set AGENTX_ROOT to read another install's inbox.
  2. Terminal: answer one, using its key:
    sh
    agentx approvals approve card:2026-01-05-send-the-newsletter-ab12
    Use reject for no, or later to put it off. Add --note "text" to pass a note to the agent with your answer.

Answer from a card on your Mac ​

Mac only. With the popup switched on, your Mac shows a waiting card by itself: a soft chime, one short spoken line, and a small card at the top right of the screen. It follows your light or dark mode.

The Mac card: who is asking, the question, three meeting times with the recommended one picked, and the suggested message

The card shows who is asking, the background (context), the question, the ready-made answers, and the suggested message. When the agent's recommendation starts with one of the answers, that answer carries a dot and is already picked when the card opens, with the agent's reason under the answers. A recommendation that starts any other way picks nothing and is shown whole.

  1. Click an answer, or press its number (1 to 3). The message below fills in with your pick.
  2. Read the message and change the wording if you like. Edited shows next to it once you have, with Reset to put the suggested message back. If you pick another answer after editing, your edits stay and only the pick in the text changes.
  3. Click Send, or press ⌘↩. The agent that asked is told your pick and the exact message, and it does the sending.

Nothing is sent until you click Send. Not now (or Esc), or leaving the card alone, keeps the card waiting in Approvals, where you can still answer it later. A card without a message shows Yes (or Choose, when it offers answers), No and Not now.

The card is a plain web page shown by macOS itself. There is no app to install. The page can't load anything from the network, so it uses the Geist typeface when your Mac has it installed and the system typeface otherwise. Drag the card by its header (the top strip with the sender's name) to move it. Click the small arrow at the right of the header to shrink the card to its title, and again to show it all. A card taller than your screen scrolls in the middle, and its buttons stay in view. The card stays on screen when you click another app, until you answer it, click Not now, or its wait (popup.timeoutSeconds) runs out. If the window can't open, you get the plain macOS dialogs instead: pick an answer and click Next, then Send. Set popup.style to "dialog" to always use the dialogs.

The popup behaves like your other notifications:

  • Focus and calls are respected. While a Focus mode (Do Not Disturb) or the widget's hold is on, or while you are in a call, nothing pops up. The card appears within a minute after the Focus or the call ends. See Hold messages during Focus and calls.
  • It doesn't take the keyboard. The card floats over the app you are using, and that app keeps the keyboard, so you can finish the sentence you are typing. One click on the card answers it.
  • The screen gate. A card goes on your screen only if it asks one question, its title is at most 120 characters and says what it is in words, its question is at most 300, and it offers at most 3 answers. A title that is only a reference, such as #402, a link, a commit hash or a request id, is refused; a reference next to words, such as Approve the login fix (#402), is fine. A new card that breaks one of these rules is refused when the agent raises it, and the agent is told why. An older card that breaks one is not shown: it stays in Approvals, unchanged, and the agent that raised it is told why, once. A card you ask for with Show on Mac always shows.
  • One at a time, oldest first. Each new card pops up once, and again at each check-in.
  • Cards you put off with Later pop up when they come back. Cards older than a day don't pop up by themselves, so switching the popup on doesn't replay a backlog. Check-ins bring them back.

To switch it on:

  1. Terminal: turn the popup on:
    sh
    agentx approvals settings --popup on
  2. Terminal: optionally choose the sound, the voice and the colours, or silence the spoken line:
    sh
    agentx approvals settings --popup-sound Glass --popup-voice Samantha --popup-theme dark
    agentx approvals settings --popup-speak off
    --popup-sound chime is the card's own soft chime (the default). Any name from /System/Library/Sounds also works, and none is silence. say -v '?' lists the voices on your Mac.
  3. Terminal: run agentx approvals settings to see what is set.

To see the card without raising one:

  1. Terminal: run agentx approvals popup --sample. It shows the sample above; your click is printed and nothing is recorded.

To show one real card now:

  1. Terminal: run agentx approvals popup <key>, using a key from agentx approvals list.

Run inside an agent's session (AGENTX_AGENT_ID set), the command never records an answer: it prints the card in the terminal. Add --dry-run to show the window without recording, or --print (anyone) to print the card and open nothing. Each run prints a line starting [approvals] popup (<who> (terminal)) saying who ran it and what happened; an answer recorded this way is marked operator (popup, terminal).

An option that means no counts as a no whichever button sent it. An option whose label starts with Don't, Do not, No, Not, Never, Cancel, Skip, Decline or Reject is recorded as no, with the option kept and the message dropped, and the agent is told NO, never "send exactly this".

You can also answer a card with choices from the terminal: agentx approvals approve <key> --choice 2, and add --text "…" to change the message. A plain agentx approvals approve <key> (no --choice) takes the agent's suggested choice, the one its recommendation starts with, and the agent is told it was a plain yes. When the recommendation names no choice, a plain yes is refused with the list of choices. A plain yes means yes to the advice, so on a card whose choices are Yes and No and whose recommendation starts with "No: …", a plain yes records the choice No. The dashboard and the phone app let you pick a choice and edit the message too: see Answer on the Hub and the phone app.

Agents on another machine ​

With a second machine in your mesh, its agents raise cards too, but that machine has no screen of yours: its cards would sit in its own inbox, unseen. Tell it to send them here instead. Its daemon then hands every card to this machine's inbox and popup, and your answer travels back to the agent that asked, on its own machine.

  1. Terminal, on the machine with your screen: make sure the other machine is a peer here. agentx mesh list shows it with its name.
  2. Terminal, on the other machine: send its cards to this machine, using the name this machine has in that machine's peer list (agentx mesh list there shows it):
    sh
    agentx approvals settings --forward-to studio-mac
    The setting is refused for a name that is not a peer. The daemon picks the change up by itself.
  3. Terminal, on the other machine: raise a test card, as in For agents: raise a card. It is listed as raised on the peer.
  4. Browser or Mac, on the machine with your screen: the card is in Approvals, shown as from <agent> on <machine>, and the Mac card opens for it like any other. Answer it.
  5. Within a minute the other machine's daemon gets the answer and runs the agent's short turn on the approvals channel.

The same mesh token that protects the rest of the mesh protects this: the forwarding machine sends the card with its peer token, and it accepts an answer only from a request that carries one of its own mesh tokens, never from a program on the same machine. When an agent on the other machine has the same id as an agent on this one, its card is listed as raised on the other machine only if that machine sends it with its own peer token (its token in mesh.peers); with the shared MESH_TOKEN the card is taken as this machine's agent's. agentx doctor warns about a peer that has no token of its own. Agents on the other machine keep agentx_approval and the status check: a status check for a forwarded card is answered from this machine. If this machine is unreachable when a card is raised, the agent is told so and nothing is lost in between; if it is unreachable when you answer, the answer is sent again every minute for a day. To keep cards on the other machine again, run agentx approvals settings --forward-to none there.

Requests that are not finished ​

When open requests are on, a request you gave an agent that failed, ran out of time, was cut off or went quiet shows in the inbox as a Request:

  • Yes hands it back to the agent. Within a minute the agent gets the request again, in your words, and works on it.
  • No drops the request. A note you add is kept as the reason.
  • Later puts it off, like any other item.

On Needs you, a request that waits on you is answered in place: see Answer on the Hub. Every request you gave, finished or not, is a post on the Hub, with its headline, what is needed from you, the agent that has it, its plan and its goal (see What a request's card shows). A request that does not wait on you is handed off, closed as done or dropped from its post: see Close or hand off a request. A goal's progress is the Hub's Goal filter, and the request settings are in Settings › Requests.

Check-ins: a few times a day ​

Mac only. Check-ins read Apple Reminders and show Mac cards, so they need a Mac.

Check-ins go through what is open for you on a schedule, and put each item that needs you on a Mac card. They are off until you switch them on, and they need the popup on too.

At each check-in the daemon:

  1. Brings back waiting cards. Every card still waiting shows once more, oldest first, one at a time.
  2. Looks at your open reminders in Apple Reminders (Mac only). A normal check-in takes the ones due in the next 24 hours or overdue. The daily check-in takes every open one, dated or not.
  3. Asks the agent that owns each reminder to write its card. The owner is the agent named in the reminder's agentx: line (reminders agents create through the mac-pim skill have one). For other reminders, it is the agent you choose with checkin.agent. The agent does the homework, such as finding free times in your calendar, and writes the context, the question, two to four answers and a suggested message. It may also say the reminder doesn't need you. It sends nothing. That rule is an instruction in its prompt, not a lock: while it writes the card the agent has its usual tools, the same trust as the reminders poller.
  4. Your click goes back to that agent. It is told your pick, the exact message and the reminder, does what you chose, and ticks the reminder off.

A reminder has one card at a time. If you answer it or the agent says it doesn't need you, and the reminder is still open, it comes back at the next daily check-in.

If writing the card fails, the next check-in tries once more. After a second failure the reminder waits for the next daily check-in. A busy agent is not a failure: the check-in waits for it to be free, up to 25 minutes. A background that runs past 600 characters is cut at the end of a sentence and ends with "…". When a check-in ends with failures and no card, you get one notification that names the reminders and the reason for each.

Each check-in asks at most five agents (checkin.maxAsksPerPass), whatever they answer, so a long list of reminders is spread over several check-ins. Reminders that the reminders poller has already handed to an agent are left to that agent.

The default times are 09:00 for the daily check-in, then 11:00, 14:00 and 17:00. If the Mac was asleep or the daemon was off, a missed time is not replayed: the next one runs as usual, and the daily check-in runs once the Mac is back.

To switch check-ins on:

  1. Terminal: switch the popup and check-ins on, and choose the agent for reminders no agent owns:
    sh
    agentx approvals settings --popup on --checkin on --checkin-agent secretary-agent
  2. Terminal: optionally change the times and the lists:
    sh
    agentx approvals settings --checkin-daily 08:30 --checkin-times 10:00,12:30,15:00,18:00
    agentx approvals settings --checkin-lists "Reminders,Work"
  3. Terminal: run a check-in now to see it work. --daily takes every open reminder:
    sh
    agentx approvals checkin --daily
    The agents need a minute or two to write the cards. agentx approvals list shows them as they arrive, and the Mac card opens for each.

The first time, macOS asks whether AgentX may use Reminders. Click OK. The daemon reads Reminders with remindctl (brew install steipete/tap/remindctl), the same tool as the mac-pim skill.

Get one reminder a day ​

Once a day AgentX sends you one message: how many items are waiting, and the most urgent one. It never sends one message per card. The number is the one next to Needs you on the Hub and under Your turn on the phone app's Desk: the decisions here, plus requests where an agent asked you a question. What you put off with Later is named apart. See One list, one count. To have new items sent to your phone or shown on this computer at once instead, see Choose where new items go. It goes to the same place as your other notifications (notifications.destination, see Get notified) unless you choose another.

To change the time, or where it goes:

  1. Browser: on Needs you, select Change in Settings in the Reaching you box. It opens the Hub's Settings › Inbox; scroll to Approvals.
  2. Browser: change Digest time, or type a destination such as telegram:123456 in Digest goes to.
  3. Browser: select Save.

Settings, the Inbox section, under Approvals: where new cards go, how long they wait, Later, and the daily digest

Or in the terminal:

  1. Terminal: set the time and destination:
    sh
    agentx approvals settings --digest-time 08:30 --digest-to telegram:123456
  2. Terminal: run agentx approvals settings with no options to see what is set.

Settings ​

These live under approvals in agentx.json. Every value shown is the default:

json
"approvals": {
  "defaultExpiryDays": 3,
  "maxExpiryDays": 30,
  "laterHours": 24,
  "notifyAgent": true,
  "digest": { "enabled": true, "time": "09:00" },
  "popup": { "enabled": false, "style": "card", "theme": "system", "speak": true, "sound": "chime", "volume": 0.4, "timeoutSeconds": 600 },
  "checkin": {
    "enabled": false, "dailyAt": "09:00", "times": ["11:00", "14:00", "17:00"], "lists": ["Reminders"],
    "dueWithinHours": 24, "maxAsksPerPass": 5, "composeTimeoutSeconds": 300
  }
}
SettingWhat it doesTerminal option
defaultExpiryDaysDays a card gets when the agent doesn't say--expiry-days
maxExpiryDaysThe longest any card may wait--max-expiry-days
laterHoursHow long Later hides an item--later-hours
notifyAgentTell the agent the result--notify-agent on|off
forwardToThe machine (a mesh.peers name) whose inbox and popup take this machine's cards. Unset: they stay here. See Agents on another machine--forward-to <peer>, --forward-to none
digest.enabledSend the daily message--digest on|off
digest.timeWhen, as 24-hour HH:MM--digest-time
digest.timezoneTime zone for time, such as Europe/Paris. Unset: this machine's--digest-timezone
digest.destinationWhere it goes: { "channel": "…", "chatId": "…" }. Unset: notifications.destination--digest-to channel:chatId
popup.enabledShow waiting cards on this Mac--popup on|off
popup.style"card": the web card. "dialog": plain macOS dialogs--popup-style
popup.theme"system", "light" or "dark"--popup-theme
popup.speakSpeak one short line when it opens. The line waits while you hold the talk key in AgentX Voice, and plays after. Of several request cards within ten minutes, only the first speaks--popup-speak on|off
popup.voicemacOS voice for that line. Unset: the system voice--popup-voice
popup.sound"chime", a system sound such as Glass, or "" for none--popup-sound
popup.volumeSound volume, 0 to 1—
popup.timeoutSecondsHow long the popup waits before it closes; the card stays waiting--popup-timeout
checkin.enabledRun check-ins--checkin on|off
checkin.dailyAtThe daily check-in, 24-hour HH:MM--checkin-daily
checkin.timesThe other check-ins--checkin-times 11:00,14:00
checkin.timezoneTime zone for the times. Unset: this machine's—
checkin.listsYour Reminders lists to look at--checkin-lists
checkin.agentThe agent that writes cards for reminders no agent owns. Unset: those reminders are skipped--checkin-agent
checkin.dueWithinHoursA normal check-in takes reminders due within this many hours—
checkin.maxAsksPerPassMost agents one check-in asks to write a card, whatever they answer—
checkin.composeTimeoutSecondsHow long an agent may take to write one card, counted from the start of its turn. The turn is stopped at the limit—

For agents: raise a card ​

Agents raise cards with the agentx_approval tool. They don't need anything set up. To try the inbox yourself, raise a card from the terminal:

  1. Terminal: raise a card as one of your agents (use a real agent id from agentx agent list):
    sh
    agentx approvals request --agent helper --title "Send the newsletter" \
      --ask "Send the newsletter on Monday?" --recommend "Yes: the draft is reviewed" \
      --if-silent discard --expires 2d

A card can also offer ready-made answers. The popup and agentx approvals approve --choice use them:

FieldMeaning
choicesUp to 3 short answers to pick from, such as three free times
followupMarks a follow-up card: resurface, bring-back, weekly or cleanup. Follow-up cards share a budget of 5 a day, at most 3 of them resurface; past it the card is refused until the next day
draftA suggested message you can edit. {choice} is replaced by your pick
sayThe short line the popup speaks. Default: the title
contextA few lines of background shown above the question, such as what the other person wrote (up to 600 characters)

For example, with two choices and a message:

sh
agentx approvals request --agent helper --title "New meeting date" \
  --ask "Which time should I offer?" --recommend "Thursday: you are free all afternoon" \
  --if-silent discard --choice "Thursday 14:00" --choice "Friday 10:00" \
  --draft "Hello, would {choice} suit you for our meeting?" --say "A client needs a new meeting date" \
  --context "The client asked to move Tuesday's meeting"

When you answer yes, the agent's result message includes Chosen: and the approved message. The agent sends exactly that text.

The daemon also accepts cards over its local API, POST /approvals with the fields title, ask, recommend, if_silent, expires, source, choices, draft, say and context, plus raised_by (the agent id). While a card from an agent is still waiting, a second card from the same agent on the same machine with the same source is refused, and the reply names the open card. A card from another machine of the mesh also carries node, that machine's name; the daemon keeps it only for a name in its peer list. GET /approvals lists what is waiting. POST /approvals/checkin starts a check-in. POST /approvals/<id>/resolve closes a card its own agent already handled (When you answer in chat instead). POST /approvals/result is how the machine that answered a forwarded card hands the answer back; it needs a mesh token. Answering is refused on that API on purpose.

When you answer in chat instead ​

Sometimes you answer the same question in chat while its card is still open, and the agent goes ahead. The agent then closes its own card, so a check-in or the Mac card does not ask you again:

  1. The agent carries out what you approved in chat.
  2. The agent closes the card with the resolve action of agentx_approval, and says why, for example "approved in chat, done".
  3. The card leaves Approvals. Its record keeps the reason and which agent closed it.

Closing a card is not an answer: it approves and rejects nothing. An agent can close only a card it raised itself, and only while it is still waiting. Cards that AgentX acts on by itself, such as a workflow step, a plan step or a retro card, close only when you answer them.

If you do answer No on a card whose work is already done, the agent does not undo anything because of that no alone. It asks you one clear question first.

Over the local API, an agent closes a card with POST /approvals/<id>/resolve and the field reason. The daemon works out which agent is asking from the agent's running turn (the X-AgentX-Task header, or X-AgentX-Channel and X-AgentX-Chat), which the agentx_approval tool sends by itself. A raised_by field is optional and must name that same agent. A call from outside a running turn, or one that names a different agent, is refused with 403 and the card stays open.

A workflow step can close a card too, when the step is an action.run step and the card belongs to the agent the workflow runs for. That agent is the one that started the run, or else the workflow's ownerAgent. While the step runs, the daemon gives its action a one-time proof: a shell action finds it in the environment variable AGENTX_STEP_PROOF, and an http action can put in a header. The action sends it back in the X-AgentX-Step header with the reason. The daemon accepts it only from this machine, only on /approvals/<id>/resolve, and only until the step ends. The proof is hidden in the output saved for the step, and one limit applies on a shared user account. The closed card records the run and the step in closed_via. A proof from another agent's workflow, a proof from a step that has ended, or no proof at all is refused with 403. Cards that a workflow owner.ask step raised are still answered by you only.

A card forwarded from another machine is closed through that machine's daemon, which checks its agent the same way and then passes the request on in its own name. The machine that keeps the card accepts that when the request comes from that peer: it carries the peer's own token from mesh.peers, or it carries the shared MESH_TOKEN (the one secret every machine of the mesh holds) and does not come from this machine's loopback address (127.0.0.1, ::1 or ::ffff:127.0.0.1, the address a program uses to reach its own machine). A request with the shared MESH_TOKEN that comes from the loopback address is refused, because every agent on this machine has that token. This only stops the plain case: an agent on this machine that calls the daemon through the machine's own network or tailnet address looks like a peer and is not refused. The card must also name that machine and that agent, which catches a request sent to the wrong card. Only a peer's own token ties a request to one peer: with the shared MESH_TOKEN, any machine of the mesh that names another peer and its agent can close that peer's card. Closing a card never decides it, and the closer is recorded. Give each peer its own token in mesh.peers if one machine must not close another's cards.

An agent on the machine that keeps the card cannot close a card raised on another machine. It gets an error that names the agent and machine that raised it: that agent closes it, or you answer it in Approvals.

Agents on a claude-code engine get the agentx_approval tool in every session, whichever channel started it: the daemon adds its own tool server to each session it starts, next to the tool servers the workspace and the computer's user already load.

For agents: see what is on your screen ​

Before an agent puts something new in front of you (a card, a notice, a call or a spoken line), it can look at what is already there with the agentx_screen tool. It is in the read tool set: it looks and changes nothing. It lists:

  • decision cards waiting for your answer: title, the agent that raised it, its machine, and when;
  • notices held while you are in Focus or a call: title, who sent it, and when;
  • the line being spoken and the lines waiting to be spoken, each cut to its first words;
  • open requests waiting on you: the request cut to a title, its agent, and since when.

It shows titles only, never a card's question, a notice's message or a request's whole text, and at most 20 of each kind with the full count. The same view is on the daemon's local API as GET /screen. Like GET /approvals, a call from another machine needs a mesh token.

Check it worked ​

  1. Terminal: raise a test card with agentx approvals request as shown above.
  2. Browser: select Needs you on the Hub. The card is in the list with Expires in 2 days, then the agent drops it.
  3. Browser: select No, then Confirm. The note says the agent will be told no, and the card leaves the list. On the Answered tab it is listed as No.
  4. Browser: within a minute, the Hub's Activity page shows a short run for that agent on the approvals channel. That is the agent reading your answer.
  5. Terminal: agentx approvals list says nothing waiting.
  6. Terminal: if agents have proposed wiki claims, agentx approvals list ends with one line starting Also: that gives how many wait, and the count above it does not include them.
  7. Browser: open <dashboard>/approvals, the old address of this page. It opens Needs you on the Hub.

For the popup (Mac):

  1. Terminal: run agentx approvals settings --popup on.
  2. Terminal: raise the meeting card from For agents: raise a card.
  3. Mac: within a minute you hear the chime and the spoken line, and the card opens at the top right of the screen. Click a time. The message fills in with it. Click Send.
  4. Terminal: agentx approvals list no longer shows the card, and the agent's run on the approvals channel starts with your pick.

For a second machine:

  1. Terminal, on the other machine: run agentx approvals settings. The line Cards go to names this machine.
  2. Terminal, on the other machine: raise a test card with agentx approvals request. The confirmation says raised on <machine>.
  3. Browser, on the machine with your screen: select Needs you on the Hub. The card is there, from the agent on the other machine. Select No, then Confirm.
  4. Browser, on the other machine: within a minute, the Activity page of its Hub shows a short run for that agent on the approvals channel, and its daemon log has a line result back from <machine>.

For a card answered in chat:

  1. Chat: ask an agent for something that needs your approval, and wait until it says a decision card is waiting.
  2. Chat: say yes in the same chat, and let the agent do it.
  3. Browser: select Needs you on the Hub. The card is gone.
  4. Terminal: agentx approvals list does not show it, and the next agentx approvals checkin does not ask about it.
  5. Terminal: the daemon log has a line [approvals] <card> closed by <agent>: <reason>.

For check-ins (Mac):

  1. Mac: in Reminders, add a reminder due today to your Reminders list, such as "Reply to the client about the meeting".
  2. Terminal: run agentx approvals checkin.
  3. Terminal: within a few minutes, agentx approvals list shows a card from your checkin.agent for that reminder, and the Mac card opens for it.
  4. Terminal: the daemon log has a line starting [checkin] check pass: with the number of cards raised.

For the screen gate:

  1. Terminal: raise a card that asks two things:
    sh
    agentx approvals request --agent helper --title "Test gate" --ask "Send it? And post it?" \
      --recommend "No: test" --if-silent discard --expires 1h
  2. Terminal: it is refused with ask holds more than one question: one card asks one thing, and agentx approvals list does not show it.
  3. Terminal: run the same command with --title "#402" and --ask "Send it?". It is refused with title is only a reference ("#402").

For what is on your screen:

  1. Terminal: run curl -s http://127.0.0.1:18800/screen.
  2. Terminal: every decision card that agentx approvals list shows is in the cards list, with a title and no ask.

If something is wrong ​

  • Needs you shows nothing, but agentx schedule list shows a request: the dashboard reads the folder it was started in. Start agentx board serve from the same folder as the daemon.
  • A wiki claim or a missing-article question is not a card: that is expected. See Wiki claims and other wiki questions.
  • "Couldn't read …" above the list: one of the sources couldn't be read, so the list may be incomplete. The message says which one; the other kinds still work.
  • unauthorized when you click a button: the dashboard has a login token (dashboard.token). Open the dashboard through its usual address so the page carries it. On another device, sign in first.
  • An agent gets "Decisions are made by the operator only": that is expected. Agents can't answer through the daemon; an agent running the CLI from its shell can, and is recorded (see below).
  • An agent's id shows as who answered on the Answered tab: the agent ran agentx approvals approve or reject from its own shell. Answers given with no agent running the command show as the operator. Answers recorded before this version keep what they say.
  • A card says then: keep although the agent asked for approve: that is expected. A card never approves itself; answer it yourself if the work should go ahead.
  • An agent gets "a card from you on this source is still pending": it already has an open card with the same source link, so the same question would reach you twice. The message names the open card: answer it, or let the agent close it with the resolve action and raise a new one. Cards without a source, and cards from another agent or another machine, are not affected.
  • An agent gets "already has 25 cards waiting": it has too many open questions. Answer or let some expire first.
  • No daily message: check that digest.enabled is on, that the time has passed today, and that notifications.destination or digest.destination is set. Nothing is sent on days when nothing is waiting.
  • No popup appears: check that agentx approvals settings shows Mac popup on, that no Focus mode, widget hold or call is on (agentx notify --status), and that the card is less than a day old. A card that breaks a screen-gate rule is never shown by itself: the daemon log says not shown, back to <agent>. Each card pops up once; use agentx approvals popup <key>, or Show it on the Mac again in the card's details on Needs you, to show it again. The daemon log has a line starting [approvals] popup.
  • A card went away and you don't know why: the daemon log says how each popup ended. left waiting: not now means Not now or Esc, timed out means the wait ran out, and closed means the window was closed. The card is still in Approvals in all three cases.
  • The card window never opens, but the plain dialogs do: the web window couldn't start, so AgentX fell back to the dialogs. Run agentx approvals popup --sample in a terminal to see the error. To keep the dialogs, set --popup-style dialog.
  • Check-ins raise no cards: check that agentx approvals settings shows Check-ins on, that remindctl show today lists your reminders, and that checkin.agent names an agent from agentx agent list. The daemon log lines starting [checkin] say what happened to each reminder: "no agent owns it", "couldn't compose a card", or the pass totals.
  • A card comes back after you already approved it in chat: the agent did not close it. Answer it with what you said in chat (Yes), or tell the agent to close it with the resolve action. Agents whose sessions started before this update need a new session to see that action.
  • An agent gets "only the agent that raised the card can close it": the call did not come from one of that agent's running turns, or it came from another agent. Only the agent that raised a card can close it, while it is working. Answer the card in Approvals instead.
  • An agent on another machine can't close its card ("needs a request from that peer"): the request did not reach this machine with a mesh token over the network. Check that agentx mesh list on the other machine shows this machine as healthy, and that both machines hold the same MESH_TOKEN (or give that peer its own token in mesh.peers, and use the same token for this machine in the peer's mesh.peers). Until then, answer the card in Approvals.
  • An agent gets "card … was raised by another agent (… on node …)": the card came from an agent on another machine. Only that agent can close it, through its own machine. Answer it on Needs you instead.
  • An agent gets "card … is answered by the operator only" when it closes a card: the card belongs to a workflow, a plan or a retro, which act on your answer themselves. Answer it on Needs you.
  • A reminder you already answered comes back: the agent didn't tick it off. It comes back at the next daily check-in while it stays open. Tick it off in Reminders, or tell the agent.
  • No sound or voice: check the Mac's volume, that --popup-sound names a sound in /System/Library/Sounds, and that the voice appears in say -v '?'.
  • "Pick one of the choices first": you clicked Yes on a card with choices without picking one. Click a choice, then Yes.
  • "This card offers choices and suggests none: pick one of …": a plain yes reached the machine, and the agent's recommendation does not start with one of the choices, so there is nothing to take. Pick a choice on the dashboard, or answer with agentx approvals approve <key> --choice <n>.
  • The agent never heard the result: check notifyAgent is on, and that the agent still exists on this machine. The daemon log line starting [approvals] says what happened.
  • An agent on another machine says the agentx_approval tool is missing: its daemon is older than this feature, or the agent is not on a claude-code engine. Update AgentX there and restart its daemon; a session started after that has the tool.
  • A card raised on another machine never shows here: on that machine, agentx approvals settings must say Cards go to this machine, and agentx mesh list must show this machine as healthy. Its daemon log says forwarded to <machine> for each card it sent, or names the machine it could not reach. approvals.forwardTo names "…", which is not in mesh.peers means the name is wrong: use the name from that machine's agentx mesh list.
  • unknown node when a card is forwarded: this machine does not list the other one as a peer, or knows it under another name. Pair in this direction too, as in Add a second machine.
  • The answer never reached the other machine's agent: this machine's daemon log says couldn't send … to <machine> with the reason, and tries again every minute for a day. a card result needs a mesh token means the two machines hold different mesh tokens.

Released under the MIT License.