Skip to content

Configuration: agents and runtime ​

This page lists every setting in agentx.json for the machine (node), model providers, agents, conversation sessions, warm processes and plugins. For the other sections and how to edit the file, see the Configuration reference.

In the tables, "required" means the setting has no default and must be set. "—" means it is unset unless you set it. Paths with <id> stand for a name you choose, such as an agent id.

node ​

The machine this daemon runs on.

KeyTypeDefaultWhat it does
node.idstringrequiredStable id of this machine. Used to label workflow runs and as this node's name on the mesh.
node.namestringrequiredReadable name of this machine, shown in logs and mesh listings.
node.bindstring"127.0.0.1:18800"Address and port the daemon API listens on.
node.defaultAgentstring—Agent used by voice and API calls that do not name one.
node.connectAttemptTimeoutMsnumber (250–60000)5000How long, in milliseconds, the daemon waits for each address of a server to answer before it tries the next one. Raise it on a slow internet link where every outgoing request fails with ETIMEDOUT. Read when the daemon starts, and by every agentx command: from the file given with --config, or else from the config file in the current folder. Write the path as --config <file>, --config=<file> or -c <file>.json; the short form -c counts only when the file name ends in .json, and -c<file> written as one word is not seen.

providers ​

API credentials for agents that call a model directly (the sdk and orchestrator engines). Keyed by provider name, for example providers.claude.

Key (under providers.<name>)TypeDefaultWhat it does
apiKeystring—API key for this provider. Use an ${ENV_VAR} reference rather than the key itself. An sdk agent without a key fails with No API key for provider.
defaultModelstring—Accepted by the validator but not read by the current runtime. Set model on the agent instead.
baseUrlstring—Accepted by the validator but not read by the current runtime. To send the claude provider through a proxy or gateway, set the ANTHROPIC_BASE_URL environment variable instead (for example in .env), the same variable Claude Code reads. The engine then sends every request, including your API key, to that address. If you set ANTHROPIC_BASE_URL only for Claude Code, check that it also suits your claude-provider agents.
thinkingboolean—Turns thinking-mode output on or off for orchestrator agents on backends that support it. Ignored elsewhere.
json
"providers": {
  "claude": { "apiKey": "${ANTHROPIC_API_KEY}" }
}

agents ​

One entry per agent, keyed by agent id (agents.<id>).

Key (under agents.<id>)TypeDefaultWhat it does
namestringrequiredDisplay name of the agent.
workspacestringrequiredFolder the agent works in.
tier"claude-code" | "codex-cli" | "opencode" | "sdk" | "orchestrator""claude-code"Engine that runs the agent: a provider CLI, a direct API call (sdk), or AgentX's own tool loop (orchestrator).
providerstring—Provider name in providers for sdk (default claude) and orchestrator (default claude-code) agents.
modelstring—Model id passed to the engine. Unset uses the engine's default.
systemPromptstring—Extra instructions added to every run of this agent.
mentionslist of string[]Names that route a message to this agent, such as @helper. Spoken questions match them too, without the @, so this is also where spoken aliases go: add a spelling speech to text often writes for the agent's name. See Spoken aliases.
teamstring—The ready-made team this agent was added with, such as client-inbox. Set by agentx team add and agentx team import; agentx team list and agentx team export <name> use it. Lowercase letters, numbers and hyphens. Does not change how the agent runs. See Start from a ready-made team.
intentslist of string[]Intents this agent may handle, such as issue.opened. Empty allows any intent.
maxDelegationDepthnumber (0–50)5Refuses a hand-off to this agent when that many other agents already worked on the same item in a chain. 0 turns the check off.
mcpmap of object—MCP tool servers for this agent, by name. Written to the workspace's .mcp.json when the daemon starts; your own edits to that file are kept. See the table below.
codegraphbooleanfalseAdds the CodeGraph code index to the agent's workspace (tool server, permissions and instructions) and indexes the workspace in the background. For coding agents.
contextStrategy"layered" | "planner"—Overrides session.contextStrategy for this agent.
contextReferencesbooleanfalseAdds a checked list of references from the workspace's references/ registry to the agent's context.
richMessagesbooleantrueLets the agent send buttons, polls and media on chat channels, and also quick replies in the phone app, including replies relayed by mesh delegation or /send. false sends plain text only: no buttons, polls, media or quick replies, and on the phone no pictures inside answers (they show as links) and no files (their names show as text). Speech is not affected.
maxConcurrentnumber1How many runs of this agent can happen at the same time.
maxExecutionMinutesnumber (1–240)20Time limit for one run; the process is stopped when it passes. The work is then picked up once more in the same conversation (resume.timeLimit).
preSpawnTimeoutSecnumber (10–3600)300Time a run may spend getting ready before its agent process starts. Each preparation step also has a short limit of its own (5 to 30 seconds); a step that runs past it is skipped and the run goes on without it. When the whole time passes anyway, the run is stopped, its slot is freed, its record is marked timeout with the step it was stuck on, and the message is tried once more from the start; if that stalls too, the sender is told in plain words to send it again. Applies to every run, whatever started it. See Time limits and cancel.
drainTimeoutSecondsnumber (0–86400)—How long a daemon stop waits for this agent's running tasks, when that is longer than shutdown.drainTimeoutSeconds. For agents whose tasks take long, such as renders. See change how long it waits.
permissionModestring"default"Permission mode for the agent's CLI. The agent runs with nobody to answer, so no step comes to you: in default, acceptEdits and plan a step that needs permission is refused, and bypassPermissions lets it act without asking. See What always waits for you.
billing"subscription" | "api""subscription"For claude-code agents: use the shared sign-in (subscription) or bill ANTHROPIC_API_KEY (api). An api agent with no key fails its run. Use api for every agent that other people reach, such as the agent of a guest grant.
cloudSessions.enabledbooleanfalseSends this claude-code agent's GitHub issue and pull request tasks to Claude cloud sessions (claude --cloud) instead of running them here; the result is a pull request. Needs channels.github.cloudSessions too, and a clone of the repository on this computer. A launch that fails runs locally. See Send coding tasks to Claude cloud sessions.
cloudSessions.maxPerDaynumber0Most cloud sessions this agent may start per day; 0 means no limit. Past it, tasks run locally.
cloudSessions.openHoursnumber (1–168)24How long a started session counts as open: no local run starts for its issue, and comments on the issue are forwarded to it.
cloudSessions.launchTimeoutSecondsnumber (10–600)120How long claude --cloud may take to print the session id before the launch is given up and the task runs locally.
worktrees.enabledbooleanfalseRuns each of this agent's issue tasks (GitHub, GitLab, Linear, Jira) in a git worktree of its own, on the branch agentx/issue-<n>. Pull and merge request tasks keep running in the clone. See Give each coding task its own worktree.
worktrees.rootfolder.agentx-worktrees/<clone name> beside the cloneWhere the worktrees are made.
worktrees.maxAgeDaysnumber (1–365)14A worktree no task used for this many days, with no uncommitted change, is removed. Its branch stays.
wiki.contribute.enabledbooleanfalseOnce a day, the agent reviews its own work and suggests sourced facts for the shared wiki. Adds the daily wiki-contribute and wiki-contribute-merge jobs. See Let agents keep the wiki up to date.
wiki.contribute.maxPatchesnumber (1–200)30Most suggestions one daily run may make.
wiki.contribute.maxCostUsdnumber (0–20)wiki.contributions.maxCostUsdMost model spend one daily run may reach, in dollars.
wiki.contribute.modelstringwiki.contributions.modelModel for this agent's daily run.
wiki.notes.dirstringthe AgentX note store, .agentx/agent-memory/<agent>/The folder wiki query reads this agent's notes from when wiki.query.notes.enabled is on. A relative path is read from the folder that holds agentx.json. See Search the agent's own notes.
wiki.absorb.enabledbooleantruefalse leaves the agent out of agentx wiki absorb unless it is named with --agent. Its conversations are still saved. See Leave an agent out of the wiki absorb.
budget.monthlyUsdnumber (0–1000000)unset (no cap)Most this agent may spend in one calendar month (UTC), in US dollars. At the cap, new runs are refused until the month ends or you raise it. 0 means no cap. Applies on save. See Set a monthly budget for an agent.
budget.warnRationumber (above 0, up to 1)0.8Share of budget.monthlyUsd at which you get one notice for the month.
toolUseRequiredlist of string[]Tool names, such as Write, of which at least one must be used in a run; otherwise the run fails with tool_required_not_called.
gitlabAutoReplyboolean—For this agent, overrides the GitLab or GitHub channel's autoReplyLegacy: true posts the agent's final answer as a comment, false does not.
persistentProcessbooleanfalseKeeps a warm process per conversation for claude-code, codex-cli and opencode agents so replies start faster.
queueMode"collect" | "followup" | "drop""collect"What happens to messages that arrive while the agent is busy: batch them into one turn, run each as its own turn afterwards, or discard them. A held message that waited more than a minute starts with a one-line note giving the time it arrived and the time it runs, so the agent checks again anything that may have changed meanwhile. A busy agent on another node is not an error either: the thread gets no ❌ and no failure comment, and the reply comes when the message runs.
access"private" | "public""private"public lets outside apps message the agent through the public API with a scoped token.
adminboolean—Lets the agent pause, resume and request deletion of schedules created by others. Approval stays with the operator.
subscriptionslist of object[]Events this agent follows, and whether it reads them itself (pull), gets a short list when it starts fresh (digest) or is started by them (wake). Each entry has kinds, agents, nodes, match, delivery, maxPerHour, prompt and maxDelayMin. See Let agents follow events.
heartbeat.enabledbooleanfalseRuns a periodic check-in inside the agent's ongoing session.
heartbeat.intervalMinutesnumber30Minutes between check-ins.
heartbeat.promptstring"Check inbox, pending tasks, and system health. Report anything that needs attention."What the agent is asked at each check-in.
heartbeat.channelstring"heartbeat"Channel name the check-in runs under.
integrationslist of object[]Services this agent has credentials for. See the table below.
voiceobject—How the agent sounds. See the table below.
presenceobject—How the agent's on-screen cursor looks. See the table below.
json
"agents": {
  "helper": {
    "name": "Helper",
    "workspace": "./workspaces/helper",
    "tier": "claude-code",
    "mentions": ["@helper"],
    "maxConcurrent": 2,
    "heartbeat": { "enabled": true, "intervalMinutes": 60 }
  }
}

A top-level budget with the same two keys caps all agents together: "budget": { "monthlyUsd": 200 } next to agents. Reaching it pauses every agent until the month ends or you raise it. A project's budget sits on its entry in dashboard.wall.projects. All three can also be set on the Hub's Cost page (Set a monthly budget from the Cost page).

Instructions AgentX adds for coding agents ​

A claude-code or codex-cli agent gets two short rules in its system prompt, on top of its own systemPrompt. There is no setting for them.

RuleEnginesWhy
Read the code before trusting an issue thread or earlier comments.claude-code, codex-cliThreads can hold wrong guesses; the code is the source of truth.
Change files with the Edit tool, not with sed, awk or a shell rewrite.claude-codeA multi-line sed that misses leaves the file broken and costs extra rounds with the model. In a test on a bug fix across six files, runs that needed extra rounds fell from 7 in 20 to 0 in 20, and tokens fell 13 percent. Edits spell out the old and new text, so the cost per run rose about 4 percent.

MCP servers ​

Each entry under agents.<id>.mcp.<name> is either a local command or an HTTP server.

KeyTypeDefaultWhat it does
type"stdio" | "http""stdio"Kind of server. Leave it out for a local command.
commandstringrequired for stdioProgram to start.
argslist of string[]Arguments for command.
envmap of string—Environment variables for command.
urlstringrequired for httpAddress of the HTTP server.
headersmap of string—HTTP headers sent to the server, written as is. Do not put a key here: a ${VAR} in agentx.json is filled in when AgentX starts, and the value lands in the workspace's .mcp.json. Use headersEnv for keys.
headersEnvmap of string—HTTP headers whose value is kept in an environment variable. Each entry is a header name and the variable's name, such as { "x-api-key": "CONNECTOR_API_KEY" }. The variable holds the whole header value. AgentX reads it when it connects, and .mcp.json only holds ${CONNECTOR_API_KEY}, which Claude Code fills in itself. HTTP servers only.
allowToolslist of string—The only tools of this server the agent may use, by the name the server gives them. * is a wildcard, so GET_* allows every tool whose name starts with GET_. Left out, every tool is allowed; an empty list allows none. See Limit a tool server.
readToolslist of string—Tools on allowTools that only read, though their names do not say so. They run without asking you first. Same patterns as allowTools. Only used with allowTools. See Write tools ask you first.

Limit a tool server ​

A tool server, such as one from a service that connects many outside apps, can offer tools that read and tools that change things (post, upload, delete). Use allowTools and headersEnv to give an agent only the tools it needs, without writing the server's key in a file.

  1. Terminal: add the server's key to the .env file in your AgentX folder, as one line such as CONNECTOR_API_KEY=<your key>.

  2. Terminal: open agentx.json and add the server under the agent:

    json
    "mcp": {
      "connector": {
        "type": "http",
        "url": "https://connector.example.com/mcp",
        "headersEnv": { "x-api-key": "CONNECTOR_API_KEY" },
        "allowTools": ["GET_PAGE_INSIGHTS", "QUERY_*"]
      }
    }
  3. Terminal: run agentx daemon restart.

How the list is applied depends on the agent's engine:

EngineTools not on the list
orchestratorNever shown to the agent.
claude-codeShown, but every call to one is refused by the AgentX guard, with the reason.
codex-cli, opencodeNot checked. Set the same list on the tool server itself, when it offers one.

When the service lets you choose which tools a server offers, set the same list there too, so the limit holds on both sides.

Write tools ask you first ​

On a server with an allowTools list, a tool that changes something in the outside service (posts, uploads, deletes, sends a message) does not run straight away. AgentX shows you one Approvals card first, and the agent waits for your answer. A tool that only reads runs as before, with no card. Servers without an allowTools list are not affected.

AgentX tells the two apart by the tool's name. A name whose first action word reads, such as GET_PAGE_INSIGHTS, list_posts or QUERY_ANALYTICS, is a read, as long as no word that writes (create, delete, send, upload and the like) follows. Every other name counts as a write, including a name with no action word AgentX knows. When in doubt, AgentX asks.

  1. Agent: the agent calls a write tool, for example CREATE_POST on the connector server.
  2. Browser: open Approvals on the dashboard. A card titled <agent> wants to write with connector: CREATE_POST shows what the agent wants to send.
  3. Browser: click Yes to let the call run, or No to stop it.

If nobody answers within 3 minutes, the call does not run and the card closes. A late yes on a closed card is refused. The agent is told the call was stopped and is asked not to try another way.

This means write tools only work while you are around to answer. If nobody is watching Approvals, every write is stopped after 3 minutes. Plan write tasks for times when you can answer, or move a tool that only reads to readTools.

If a tool only reads but its name does not show it (for example SUMMARIZE_WEEK), add it to readTools so it runs without a card:

json
"connector": {
  "type": "http",
  "url": "https://connector.example.com/mcp",
  "allowTools": ["GET_*", "CREATE_POST", "SUMMARIZE_WEEK"],
  "readTools": ["SUMMARIZE_WEEK"]
}

This applies to the orchestrator and claude-code engines. codex-cli and opencode agents are not checked.

The org chart tool (agentx_org) ​

Every agent gets the agentx_org tool on its agentx tool server. It lets an agent turn your request in chat into a change to the org chart that waits for your yes; see Change the org chart by chat.

ActionWhat it does
show (default)Lists every member with its ref (agent:<id> or person:<id>), every line, and the agents and people not in the chart yet.
proposeSends 1 to 5 changes (the same ones the org editor makes: add-member, set-role, remove-member, add-relation, remove-relation, set-schedule), an optional newAgent (id, name, role, reportsTo) and an optional why. The daemon checks them and makes one Approvals card. Nothing is written before your yes; then the daemon applies them all or none.

Only a turn you started may propose: anyone else, a schedule or another agent is refused with "Only the owner can change the org chart." Proposals are kept in .agentx/org-proposals/, one file per card.

Integrations ​

Each item in agents.<id>.integrations declares one service. Secrets never go in agentx.json: credentials name an environment variable (uppercase, such as HELPER_CRM_TOKEN) or the system keyring.

KeyTypeDefaultWhat it does
kindstringrequiredService, such as telegram-bot, gitlab-user, gmail, hubspot, linkedin, x or custom. agentx doctor warns on unknown kinds. A linkedin or x entry lets approved posts go out; see Draft posts in your voice.
labelstringrequiredReadable name, unique per agent and kind.
credentialsobject{}Where the secret lives. Only the keys below are accepted.
credentials.tokenEnvstring—Environment variable holding the main token.
credentials.privateAppTokenEnvstring—Environment variable for a private app token.
credentials.apiKeyEnvstring—Environment variable for an API key.
credentials.refreshTokenEnvstring—Environment variable for an OAuth refresh token.
credentials.clientIdEnvstring—Environment variable for an OAuth client id.
credentials.clientSecretEnvstring—Environment variable for an OAuth client secret.
credentials.auth"keyring"—The credential is in the system keyring instead of an environment variable. connect stores its sign-in this way, under the name integration:<agent>:<kind>:<label>.
credentials.sessionDirstring—Folder holding a login session, for services such as WhatsApp.
metadatamap of string, number or boolean{}Non-secret details (username, host, account id), shown in the dashboard and to skills.
metadata.readsstring—For a service you sign in to with connect: the reads the agent may run, comma-separated. Unset allows every read. See Let agents read data from outside services.
metadata.page_id, metadata.ig_user_idstring—For kind: "meta": the Facebook Page and Instagram account the agent reads by default, so it does not have to name them. The pages read lists both. See Facebook and Instagram.
metadata.oauthScopes, metadata.oauthConnectedAt, metadata.oauthExpiresAtstring, number—Written by agentx agent integrations connect: the permissions granted, when, and when a token that cannot renew itself runs out. Not secret.
enabledbooleantrueTurns the integration off without removing it.

Voice ​

agents.<id>.voice overrides the global voice settings for one agent (AgentX Voice).

KeyTypeDefaultWhat it does
voice.provider"system" | "elevenlabs"—Speech engine for this agent. Unset uses the global voice.provider.
voice.systemstring | map of string—macOS voice name, system for the OS default, or one voice per language such as { "en": "Samantha" }. Unset picks a free voice.
voice.fallbacksstring[]—Voices to try in order when voice.system is not installed. Unset picks the best installed voice of the same language and gender.
voice.elevenlabsVoiceIdstring—ElevenLabs voice id.
voice.gender"female" | "male" | "neutral"—Guides which voice is picked when none is set.
voice.stylestring—A few words on manner, such as "warm, calm".
voice.introstring—One-line self-introduction used on first contact.
voice.narrate"off" | "on" | "all"—Speaks short updates while the agent works: on for all but scheduled jobs, all includes them.

Presence ​

agents.<id>.presence sets the agent's own cursor, drawn by the Mac helper.

KeyTypeDefaultWhat it does
presence.colorstring (#RRGGBB)from the agent idCursor colour.
presence.initialstring (up to 2 letters)from the nameLetters on the cursor.
presence.labelstringthe agent's nameName shown under the cursor.
presence.allowActionsboolean—Lets the agent click and type for you. Without it, "act" falls back to "teach".

people ​

The humans who talk to your agents, one entry per person. A task started by a listed person is stamped with their id on every channel. Empty by default: your own machine's surfaces are recorded as the built-in person owner and other senders are unknown. Steps and examples: Tell agents who is who.

json
"people": [
  { "id": "anis", "name": "Anis", "role": "owner", "identities": ["telegram:123456789", "github:your-login"] },
  { "id": "sara", "name": "Sara", "identities": ["gitlab:sara.b", "whatsapp:21620123456"] }
]
KeyTypeDefaultWhat it does
people[].idstringrequiredShort name you choose: lower-case letters, digits, - and _, up to 40 characters. Each id appears once. owner is kept for a person with the owner role.
people[].namestringrequiredThe person's name, for you to read.
people[].saystring—How the person's name is said aloud, for example "Shiv-awn Oh-kah-for" for "Siobhan Okafor". Only speech changes; the written name stays. With as many words as the name, each name word written with its capital is covered too. See Say a word the way it is said.
people[].roleowner, member, client or guestmemberA single owner is also the person at this machine's own surfaces (voice, phone app, dashboard), and their turns on other channels count as yours for requests. A client (someone you do work for) opens Your project on a paired machine instead of a teammate's My work (Give a client a page of their own). guest is a label for another organisation's operator.
people[].identitieslist of strings[]Where the person writes from, each as channel:id: a GitLab or GitHub login, a Telegram id or username, a WhatsApp number. Display names are not matched. An identity belongs to one person only.
people[].agentslist of strings[]The agents this person may reach, by id. Empty: every agent. A message to any other agent, on this node or on another, is answered with a note and no run starts. The limit follows the person's work through delegations. Ignored for an owner.
people[].deny.toolslist of strings[]Tools this person's work may not use, such as Bash, WebFetch or mcp__mail__*. Names match without case; * is a wildcard. Every tool call of their runs is checked, and a denied one is blocked. Needs a claude-code agent; another tier refuses their messages. Follows delegations. Ignored for an owner.
people[].deny.skillslist of strings[]Skills this person's work may not load, by name. A denied skill is not offered to the agent for their messages, and loading it is blocked. Same rules as deny.tools.

members ​

Teammates' and clients' machines paired to their own page (Invite a teammate to their work page, Give a client a page of their own).

SettingTypeDefaultWhat it does
members.logRetentionDaysnumber90Days the per-person trail in .agentx/members-log.jsonl (invites, pairings, approvals, refusals, sign-ins, removals, messages to an agent the person may not reach) is kept. Older lines are dropped, at most once an hour, when a new line is written. 1 to 3650.

session ​

When a conversation's memory is rotated or treated as stale.

KeyTypeDefaultWhat it does
session.staleMinutesnumber (1–1440)720Minutes of silence after which a conversation starts fresh.
session.maxTurnsPerSessionnumber (2–200)40Turns after which the conversation is rotated to a new session.
session.tierTwoThresholdTokensnumber (50000–200000)180000Context size, in tokens, at which the conversation is rotated.
session.tierTwoThresholdTokensByChannelobject of channel → number (50000–200000){}Overrides the context rotation limit for selected channels, for example {"voice": 60000, "github": 80000}. Other channels use the global limit. Applies to native Claude, Codex and OpenCode sessions; existing history seeds the next session. Requires a daemon restart.
session.contextStrategy"layered" | "planner""layered"How context is built: all layers every turn, or a small model picks what to retrieve first.
session.maxClaudeCodeDispatchesPerHournumber (0–10000)unset (off)Optional local ceiling on new claude-code runs across the machine in one hour. The plan's own limit is read from Claude Code and needs no setting. Warm sessions still go through. Applies on save.
session.maxClaudeCodeDispatchesPer5hnumber (0–50000)unset (off)The same optional ceiling over five hours.
session.continuityStateTurnsnumber (0–5)0Extra earlier requests shown to the session-continuity decision. 0 keeps the default two messages.
session.profileByChannelobject of channel → "full" | "lean"{}How much a session is given when it starts, per channel. A channel you do not list keeps the built-in default: github, a2a, workflow and cron are lean, every other channel is full. See Lean sessions.
session.lean.mcpServerslist of string["agentx"]Tool servers from the workspace's .mcp.json that a lean session keeps, by name. agentx is always kept.
session.lean.settingSourceslist of "user" | "project" | "local"["project", "local"]Which Claude Code settings a lean session reads. Without user, the global CLAUDE.md, user skills, plugins and user-level tool servers stay out. project is the agent's workspace.
session.lean.contextOnDemandbooleantrueLeave the agent landscape, the chat history and the cross-chat context out of the prompt, and name the tools that fetch them instead. false pushes them as a full session does.
session.lean.toolslist of string[]Built-in Claude Code tools a lean session gets, such as Bash, Read, Edit. Empty keeps every built-in tool. A short list is what brings a lean start under 20k tokens; an agent that lacks a tool it needs fails mid-task. The agentx tools are not affected. claude-code agents only. See Fewer built-in tools.
session.lean.toolsByChannelobject of channel → list of string{}The same list per channel. A channel's own list wins over session.lean.tools; an empty list falls back to it.
session.lean.agentxToolslist of string[]The agentx_ tools a lean session is told about, such as agentx_channel_reply. Empty lists every agentx tool. Saves little while ToolSearch is on. A name that is not an agentx tool fails agentx config check. agentx_approval, agentx_request, agentx_events, agentx_attach_next, agentx_workflow, agentx_waiting and agentx_job_state are always kept, and so are agentx_agents, agentx_recent, agentx_wiki_query and agentx_lookup while session.lean.contextOnDemand is on. claude-code agents only. See Fewer agentx tools.
session.lean.agentxToolsByChannelobject of channel → list of string{}The same list per channel. A channel's own list wins over session.lean.agentxTools; an empty list falls back to it.
session.midTurnMessagesbooleantrueA message that arrives while an agent works in the same conversation is read by that run after its next step, instead of waiting for the next turn. claude-code agents only. See Talk to an agent while it works.
session.triage.models.claude-codestringunset (off)A cheaper Claude model, such as claude-haiku-4-5-20251001, for runs a GitHub triage event started. See A cheaper model for triage events.
session.triage.models.codex-clistringunset (off)The same for codex-cli agents, such as a gpt- model.
session.triage.actionslist of string["labeled", "unlabeled", "closed"]GitHub issue and pull request actions that count as triage. A run uses the triage model only when every event it collected is in this list.
session.memoryIndexMaxCharsnumber0Longest the agent-memory index may be where every session loads it: in the workspace CLAUDE.md and in the system prompt. 0 keeps the whole index. The cut keeps whole lines and ends with a line counting the entries left out; the full index stays in .agentx-memory.md in the workspace. See A shorter memory index.
session.observationPack.enabledbooleanfalseKeep large tool results out of the conversation: the agent sees the start and the end of the result and the path of a file with the exact original. See Large tool results. Turning it on takes a daemon restart; turning it off applies on save.
session.observationPack.limitBytesnumber (1024–1048576)10240A text result larger than this many bytes is replaced by an excerpt.
session.observationPack.headBytesnumber (0–65536)1024Bytes of the start of the original the agent sees.
session.observationPack.tailBytesnumber (0–65536)1024Bytes of the end of the original the agent sees.
session.observationPack.toolslist of string["Bash", "Grep", "Read", "WebFetch", "mcp__.*"]Tools whose results are packed. Each entry must match the whole tool name and may be a regular expression. Requires a daemon restart.
session.observationPack.retentionDaysnumber (0–3650)0Days a saved original is kept. 0 keeps every original.
session.resumeGate.mode"off" | "shadow" | "active""off"Before an earlier conversation is picked up again, compare its price with a fresh start and start fresh when that is clearly cheaper. shadow only writes what it would do to the daemon log. See Resume or start fresh. Applies on save.
session.resumeGate.freshTokensnumber (1000–200000)30000Tokens a fresh lean session starts with.
session.resumeGate.cacheTtlMinutesnumber (1–1440)60Minutes the saved conversation is assumed to stay in the provider's cache.
session.resumeGate.cacheWriteFactornumber (1–4)2Price of writing to the cache, as a multiple of the normal input price. 2 for the one-hour cache, 1.25 for the five-minute one.
session.resumeGate.marginnumber (1–10)1.5How many times cheaper a fresh start must be before the gate picks it.

Lean sessions ​

A session's first turn carries a lot before the agent reads the task: every tool server (MCP server) the computer's user has connected, every user-level skill and plugin, the global CLAUDE.md, plus what AgentX adds, such as the list of agents (the landscape), today's history of the chat and a summary of the agent's other chats. A GitHub label event or a one-line answer to another agent pays for all of it, on every new session.

A lean session gets only what the task needs up front. The rest is one tool call away:

What a full session getsWhat a lean session gets instead
Every connected tool server, and the agentx tool server with themOnly the agentx tool server, plus the ones named in session.lean.mcpServers.
User-level settings: global CLAUDE.md, user skills, pluginsOnly the workspace's own settings and skills (session.lean.settingSources).
The landscape in the promptThe agentx_agents tool with landscape: true.
Today's history of this chat in the promptThe agentx_recent tool with the chat's channel and chatId.
A summary of the agent's other chats todayThe agentx_recent tool without a chatId.
(both) Stored knowledge, as beforeThe agentx_wiki_query tool, as before.
(both) What a colleague is on, or where a piece of work standsThe agentx_lookup tool. See Look it up instead of asking.

Both kinds of session send a claude-code agent's project CLAUDE.md once: Claude Code reads it from the workspace, and AgentX does not add a second copy. Both kinds also load the agentx tool server (the agentx_approval, agentx_request, agentx_recent and other agentx_ tools): a full session gets it next to the tool servers the workspace and the computer's user connect, a lean one gets it in their place. An agentx entry in the workspace's .mcp.json is used as written.

The prompt keeps one line, [Context on demand], naming these tools. Chat channels (Telegram, WhatsApp, voice, the dashboard and the phone app) are not changed: they stay full unless you list them. Only claude-code and codex-cli agents have a lean start; other engines always start full. The daemon log shows session profile for github: lean (…) when a lean session starts.

To make one channel full again, list it:

json
"session": {
  "profileByChannel": { "github": "full" }
}

To make a chat channel lean, or keep a second tool server in lean sessions:

json
"session": {
  "profileByChannel": { "telegram": "lean" },
  "lean": { "mcpServers": ["agentx", "codegraph"] }
}

To see what a session on a channel is handed, before and after:

  1. Terminal: in the AgentX source folder, run pnpm bench:profiles --channels github. It prints a table with one row per prompt section, full against lean, and the saving. No model is called.
  2. Terminal: run pnpm bench:context --channel github --sections --config agentx.json --agent <your agent id> to measure a real agent of yours.

Fewer built-in tools ​

Even a lean session carries the descriptions of every built-in Claude Code tool, about 14k tokens of a first turn. The lowest first turn with every tool, and none of your own files loaded, measured about 27k tokens. Getting under 20k means giving the session a shorter list of tools. This is off until you set it, because an agent that needs a tool it does not have fails in the middle of its task.

To give lean sessions a short tool list:

  1. Terminal: look at what the agent's tasks on that channel use. Run agentx trace show <taskId> on a few recent runs; the tool_use steps name the tools.

  2. Terminal: open agentx.json and set the list, for all lean channels or for one:

    json
    "session": {
      "lean": {
        "tools": ["Bash", "Read", "Edit", "Write", "Grep", "Glob"],
        "toolsByChannel": { "cron": ["Bash", "Read"] }
      }
    }
  3. Terminal: run agentx daemon restart --when-idle. The daemon log line for the next lean session ends with tools=Bash+Read+….

The list applies to claude-code agents on lean channels only, and never to the agentx tools, which stay available. An empty list means every tool: there is no way to start a session with no tools at all, because Claude Code then loads every tool server's full description instead, which costs more, not less.

AgentX always adds ToolSearch to the list, even when you leave it out. ToolSearch is the Claude Code tool that looks up a tool's full description when the agent first needs it. While it is there, the session starts with only the names of the agentx tools. Without it, Claude Code puts the full description of all agentx tools into every first turn: about 9k tokens, measured on Claude Code 2.1.291, which is more than a short list saves.

Fewer agentx tools ​

You can also tell lean sessions about fewer of the agentx_ tools, the AgentX tools the agent uses to reply, send messages and look things up. On most setups this saves very little, so leave it off unless you have measured a reason.

  • While ToolSearch is in the session (always, see above), Claude Code sends only the agentx tool names in the first turn. A list of nine tools instead of all 29 saved about 330 tokens of an 8,000-token first turn, measured on Claude Code 2.1.291.
  • It saves more, about 5,500 tokens, only where Claude Code's tool search is off, for example when ENABLE_TOOL_SEARCH=false is set or ANTHROPIC_BASE_URL points to a server other than Anthropic's. Then Claude Code sends every tool's full description.
  • The cost: a tool left off the list is gone for that session. The agent cannot find it, not even with ToolSearch.

Some tools are always kept, because AgentX's own messages to the agent ask for them by name: agentx_approval, agentx_request, agentx_events, agentx_attach_next, agentx_workflow, agentx_waiting and agentx_job_state, plus agentx_agents, agentx_recent and agentx_wiki_query while session.lean.contextOnDemand is on.

To tell lean sessions about fewer agentx tools:

  1. Terminal: look at what the agent's tasks on that channel use. Run agentx trace show <taskId> on a few recent runs; the tool_use steps name each one as mcp__agentx__agentx_….

  2. Terminal: open agentx.json and set the list, for all lean channels or for one. Use the names without the mcp__agentx__ start:

    json
    "session": {
      "lean": {
        "agentxTools": ["agentx_channel_reply", "agentx_channel_label"],
        "agentxToolsByChannel": { "a2a": ["agentx_send_agent"] }
      }
    }
  3. Terminal: run agentx config check. It prints ✓ Config valid. A misspelt name stops here with not an agentx tool: ….

  4. Terminal: run agentx daemon restart --when-idle. The daemon log line for the next lean session ends with agentx-tools=N, the number of agentx tools it was told about.

The list applies to claude-code agents on lean channels only. It works when the agentx tool server is started as a command, which is the default. If the workspace's .mcp.json points agentx at a web address ("type": "http") instead, the session still gets every agentx tool.

A shorter memory index ​

The index of what an agent remembers (agentx memory index) is loaded on every session, twice: merged into the agent's workspace CLAUDE.md, and inlined in the system prompt. An agent with many memories pays for the whole list on every task. session.memoryIndexMaxChars caps it:

  1. Terminal: run agentx memory index --agent <agent id> and look at its length.
  2. Terminal: open agentx.json and set the cap, for example "session": { "memoryIndexMaxChars": 4000 }.
  3. Terminal: run agentx daemon restart --when-idle. The prompt uses the cap at once; the CLAUDE.md block is rewritten at the restart and after every memory change.

The cut keeps whole lines, in the index's own order (user, feedback, project, reference), and ends with a line such as _(12 more memories not shown here. The full index is in .agentx-memory.md in this workspace, or run \agentx memory index`.)_`. The file it names always holds the whole index, so the agent can read it when a task needs more.

A cheaper model for triage events ​

A GitHub event such as a label being added or an issue being closed usually needs a short answer, not the agent's strongest model. session.triage sends those runs to a cheaper model you name. It is off until you set a model.

A run counts as triage only when every event it collected is a triage action. AgentX collects the events one issue raises in a few seconds into one run, so an issue that is opened and then labeled keeps the agent's own model. Three more cases keep it too:

  • a model set on the task itself, such as a schedule's model;
  • a follow-up on an issue whose conversation ran within the last hour, because changing model there re-reads the whole conversation at full price;
  • a model that does not fit the agent's engine, such as a gpt- model for a claude-code agent.

An action only reaches an agent when channels.github.issueActions or pullRequestActions (or a project rule) lets it through. labeled and closed are not in the default lists.

To send label and close events to a cheaper model:

  1. Terminal: open agentx.json and set the model, and the actions if you want different ones:

    json
    "session": {
      "triage": {
        "models": { "claude-code": "claude-haiku-4-5-20251001" },
        "actions": ["labeled", "unlabeled", "closed"]
      }
    },
    "channels": {
      "github": { "issueActions": ["opened", "reopened", "assigned", "labeled"] }
    }
  2. Terminal: run agentx config check. It prints ✓ Config valid.

  3. Terminal: run agentx daemon restart --when-idle.

This is a fixed rule. The task-tier decision under decisions.routing is a separate, learned way to pick a cheaper model; when a triage model applies, that decision is not asked.

Large tool results ​

A tool result stays in the conversation, and the model re-reads the whole conversation on every later step of the task. A 20 KB test log read once is paid for again on each of the next thirty steps, although the agent rarely looks at it twice.

With session.observationPack.enabled, a text result larger than limitBytes is saved in full under .agentx/observations/<agent id>/ in the daemon's folder, and the agent gets this in its place:

text
[ObservationPack: this result is 23442 bytes (400 lines). Only its first 1024 and last 1024 bytes are shown.
The exact original is saved at /srv/agentx/.agentx/observations/coder/aa0c…864c.txt
Read that file with offset and limit (line numbers), or grep it, for the part you need. Do not cat it whole: that is packed again. Do not guess at what is not shown.]
(the first 1024 bytes)
[... 21394 bytes not shown ...]
(the last 1024 bytes)

Nothing is lost: the saved file is byte for byte what the tool returned, and the agent reads it back with its own file tool. Reading a saved original is never packed again. When the original is a few very long lines, such as minified JSON, the excerpt tells the agent to read it by byte range instead of by line.

A file the agent reads (the Read tool) is its own original, so no copy is saved. The agent keeps the first and last whole lines that fit in headBytes and tailBytes, and a notice between them names the file and the exact lines left out:

text
(the first 21 lines, with their line numbers)
[ObservationPack: this read is 29889 bytes, lines 1 to 600 of /srv/app/src/server.ts.
Lines 22 to 580 (27870 bytes) are not shown. Lines 581 to 600 follow; the numbers beside them are not the file's.
Read the file again with offset and limit for the lines you need, or Grep it. Do not guess at what is not shown.]
(the last 20 lines)

The agent then reads the lines it needs with offset and limit, which is also how it gets the exact text for an edit. A read that starts at an offset counts its lines from there. Notebooks, PDFs and pictures are never cut.

json
"session": {
  "observationPack": { "enabled": true }
}

What it covers, and what it does not:

Agentsclaude-code agents only. It works through a Claude Code hook (PostToolUse) that AgentX writes into each agent workspace's .claude/settings.json when the daemon starts. Codex and the other engines are not changed.
Agents that ask before actingNot packed. Only an agent with permissionMode: "bypassPermissions" gets the hook: in any other mode Claude Code refuses to open the saved original in a session nobody answers for, and the agent would guess at the part it was not shown. The daemon log says how many agents were left out.
ToolsThe ones in tools. By default: commands (Bash), searches (Grep), file reads (Read), fetched web pages (WebFetch) and every tool server (mcp__.*, which includes the AgentX tools).
Files the agent readsPacked by default (owner decision on #621, 2026-10-05); the replay of three days of logs put the ceiling of cached tokens saved at 7.5% with file reads and 5.5% without. A file over limitBytes is cut to its first and last lines with the file's path and line numbers, and no copy is saved. An agent that edits large files reads the part it changes again in pages; set tools without "Read" to spare it that.
Very large command outputClaude Code itself already replaces command output over 30,000 characters with a 2 KB preview and a saved file. The pack leaves those results to it, and covers the ones between limitBytes and that size.
Pictures, sound and files in base64Never packed. Only text is.
Claude Code versionThe hook answer that replaces a result (updatedToolOutput) was confirmed on Claude Code 2.1.289. A version that ignores it gives the agent the full result, while the original is still saved and counted in index.jsonl.
Event textThe text of the event or message that starts a task is not a tool result and is not packed.
TimingThe excerpt replaces the result at once. The agent never sees the full result unless it reads the saved file.
Sessions outside the workspaceA session whose working folder is not the agent's workspace does not load the workspace's hooks and is not packed.

The saved originals can hold whatever a command printed, including secrets, exactly as Claude Code's own session logs do. Each agent has its own folder, and the read rule AgentX writes into a workspace names that agent's folder only. The folders are readable by the daemon's user only. They grow with use; set retentionDays to delete originals that have not been written or seen again for that many days. An agent that resumes an older session can then no longer read them.

If the daemon is not running, the hook does nothing and the agent gets the full result.

To see what the pack does to your costs:

  1. Terminal: before turning it on, in the folder with agentx.json, run agentx usage channels --from 2026-10-01 --to 2026-10-03 --save before.json with three recent full days. It prints the cost per channel and per task, and saves the figures.
  2. Turn the pack on and restart the daemon. Let it run for a few days.
  3. Terminal: run agentx usage channels --from <first day> --to <last day> --baseline before.json with the days after the restart. It prints both ranges side by side with the change in cost per task.
  4. Terminal: run cat .agentx/observations/*/index.jsonl | wc -l. Each line is one packed result, with its size and what the agent was shown.

The two ranges do not hold the same tasks, so compare the cost per task on the busy channels, not the totals. In the AgentX source folder, python3 bench/observation-pack-replay.py --from <day> --to <day> reads the Claude Code session logs of a range and prints how many tool-result bytes are over the limit, per tool and per channel, without calling a model.

Resume or start fresh ​

A claude-code agent picks an earlier conversation up again by replaying it, and it replays the whole conversation on every step of the new task. The provider keeps a recent conversation in a cache (a short-term store it reads from at a tenth of the normal price). Once the cache has expired, the first step pays to store the whole conversation again, at more than the normal price.

With session.resumeGate.mode set, AgentX compares two prices before it picks a conversation up:

  • Picking it up: the conversation's size, read cheaply if the cache is still there, or stored again if it is not, then read on every later step.
  • Starting fresh: a new session of freshTokens, stored once, then read on every later step.

It counts the steps from the last task in the same conversation. When starting fresh is at least margin times cheaper, the conversation starts fresh, with the same note on what came before that the other rotation rules leave. Starting fresh loses the details of the earlier conversation, which no price shows, so the default margin asks for a clear saving.

The gate runs after the rules that already start a conversation fresh (silence, size near the limit, too many turns), and can only start one sooner. claude-code agents only.

json
"session": {
  "resumeGate": { "mode": "shadow" }
}

To try it without changing anything:

  1. Terminal: in the folder with agentx.json, run agentx usage channels --from 2026-10-01 --to 2026-10-03 --save before.json with three recent full days.
  2. Set session.resumeGate.mode to "shadow" and save. Let it run for a day.
  3. Terminal: run agentx daemon logs | grep "resume gate". Each line says whether the conversation would have started fresh, with both prices.
  4. If the lines that say would start fresh are conversations you would not miss, set the mode to "active" and save.
  5. Terminal: after a few days, run agentx usage channels --from <first day> --to <last day> --baseline before.json and compare the cost per task on the busy channels.

processPool ​

How long warm claude-code processes (persistentProcess) are kept. Codex and OpenCode use fixed limits.

KeyTypeDefaultWhat it does
processPool.maxIdleSecondsnumber (5–86400)30Seconds a process may stay quiet before it is stopped, or stopped to make room when the pool is full. The count starts at its last output, not only at the last question it was asked. A process with background tasks open, or writing a reply nobody asked for, is never idle.
processPool.maxAgeSecondsnumber (60–86400)2700Seconds after the last question it was asked when a process with no work of its own is always stopped.
processPool.maxBackgroundSecondsnumber (60–86400)10800The same limit for a process that still has background work open. Used only while requests.jobs.wake.enabled is on; with it off, maxAgeSeconds applies to every process.
processPool.sweepIntervalSecondsnumber (1–300)5How often the pool is checked.

A warm process answers only the question it was asked. When a background task of the agent ends, Claude Code writes a reply nobody asked for; that reply is never sent as the answer to your next question. When the chat has an open job, the reply wakes that job and the daemon log notes it as passed to its job a reply no question asked for; with no open job it is dropped, and the log says dropped a reply no question asked for.

A process is not stopped for being quiet while it still has work of its own: a background task (for example a helper agent it started to build something) or a reply nobody asked for that it is still writing. That work keeps running past maxIdleSeconds, and the process is not stopped to make room when the pool is full; the new question runs in a separate process instead. While that work is open the upper limit is maxBackgroundSeconds (3 hours by default) in place of maxAgeSeconds: once it passes, the process is stopped anyway, and the daemon log line says how many background tasks were still open.

plugins ​

KeyTypeDefaultWhat it does
pluginslist of string[]Installed npm package names loaded as plugins when the daemon starts.

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 agents.helper.maxConcurrent, using your own agent id. It prints the value you set.
  3. Terminal: run agentx agent list. The agent appears with its engine and model.
  4. Terminal: after a GitHub event or a schedule runs, run agentx daemon logs. A line session profile for github: lean (mcp=agentx settings=project,local context=on-demand) shows the lean start took effect.
  5. Terminal: with session.lean.agentxTools set, after a lean session starts, run agentx daemon logs. The session profile for …: lean (…) line ends with agentx-tools=N.
  6. Terminal: with session.triage.models set, after a label event on an issue nobody has worked on for an hour, run agentx daemon logs. A line triage event (labeled) → <model> shows the cheaper model was used.
  7. Terminal: with session.observationPack.enabled, the daemon log shows ObservationPack: PostToolUse hook written to N workspace(s) at the first start (and N agent(s) not packed for agents outside bypassPermissions), and .agentx/observations/<agent id>/index.jsonl gets a line the first time that agent runs a command with more than 10 KB of output or reads a file of that size. A line with "tool":"Read" has no saved file next to it: the file the agent read is the original.
  8. Terminal: with session.resumeGate.mode set to "shadow", after an agent picks a conversation up, run agentx daemon logs. A line resume gate (shadow) for <channel>:<chat>: would resume: … or would start fresh: … shows both prices. In "active" mode, a line cost rotation for … marks a conversation that started fresh.
  9. Terminal: with headersEnv or allowTools on a tool server, run agentx doctor. A line N MCP server(s) with header variables, all set shows the keys were found. Open the agent's .mcp.json: the header reads ${CONNECTOR_API_KEY}, not the key itself.
  10. Terminal: after a claude-code agent calls a write tool of a server with allowTools, run agentx daemon logs. A line guard: <agent> asked to run mcp__<server>__<tool>: card <card id> waits for the owner shows the card was raised. The card is in Approvals on the dashboard.
  11. Terminal: after an agent proposed an org chart change and you said yes, run agentx daemon logs. A line [org] <card id>: applied: … shows the daemon applied it, and .agentx/org-proposals/<card id>.json says "status": "applied".

If something is wrong ​

  • The daemon log shows [org] <card id>: failed: …: the chart changed between the card and your yes, and the change no longer held. Nothing was saved. Ask the agent again.
  • agentx doctor says MCP server "<name>" of <agent>: header variable(s) not set: add the named variable to .env and restart the daemon. Without it the server gets no key and refuses every call.
  • An agent says a tool call writes data and was not run: the tool was treated as a write and nobody said yes within 3 minutes, or you said no. Ask the agent to try again and answer the card in Approvals. If the tool only reads, add it to that server's readTools and restart the daemon.
  • An agent says a write tool was not run because the confirmation card could not be raised: the agent already has 25 cards waiting. Answer or close some in Approvals, then ask again.
  • A claude-code agent says a tool call was refused with is not on the allowTools list: the tool is left off that server's allowTools. Add its name (as the message prints it) if the agent should use it, then restart the daemon.
  • A claude-code agent says a call was refused because it needs confirmation; the daemon is not answering: the daemon could not be reached, so the guard checked the call locally with the rules only. A rule asks for a confirmation, and only the daemon can show that dialog. Start the daemon (agentx daemon status, then agentx daemon start) and try again.
  • A claude-code agent says a call was refused because the AgentX guard could not check this call: the daemon is not answering, and the local check could not run either. Agent sessions are then refused every call except agentx daemon start|restart|status and the launchctl or systemctl commands that start the daemon. Start the daemon. If the local check keeps failing while the daemon is up, restart the daemon once so it rewrites .agentx/bin/agentx-guard, the link the check runs through. Your own Claude Code sessions are not refused this way.
  • config check names a field: the value has the wrong type or is out of range. Compare it with the table above.
  • On a slow internet link, every message, notification or poll fails with fetch failed or ETIMEDOUT, while curl from the same machine works: the daemon gave up connecting too early. The start of the daemon log shows Connect attempt timeout: N ms. Raise node.connectAttemptTimeoutMs, for example to 10000, and restart the daemon.
  • An sdk agent fails with No API key for provider: set providers.<name>.apiKey, or check that the environment variable it points to is in .env.
  • An agent with persistentProcess answers the question before the one you asked: update AgentX and restart the daemon. Versions up to 0.103.2 sent a background task's reply as the answer to the next question.
  • An agent's background work stops halfway, and the daemon log shows killed idle for that agent a few minutes after its last reply: update AgentX. Earlier versions stopped a warm process maxIdleSeconds after the last question, even while its background tasks were still running. If the log shows killed stale with stale with background work, the work ran longer than processPool.maxBackgroundSeconds (3 hours by default): raise it.
  • A model or engine change is ignored: restart the daemon fully with agentx daemon stop, then agentx daemon start --detach.
  • An agent on GitHub, a schedule or a workflow says it cannot see another agent, an earlier message or a tool it had before: its channel starts lean. Either tell the agent to use the agentx_agents, agentx_recent and agentx_wiki_query tools, add the tool server it misses to session.lean.mcpServers, or set that channel to "full" in session.profileByChannel.
  • A label or close event still runs on the agent's own model: check the daemon log. A run that used the triage model logs triage event (labeled) → <model>. If it is missing, the run also collected another action (such as opened), the issue's conversation ran within the last hour, or the model does not start with claude- (for claude-code agents) or gpt- (for codex-cli agents).
  • The daemon log says N agent(s) not packed: those agents do not run with permissionMode: "bypassPermissions". They could not open a saved original, so they keep getting full results. This is by design; nothing to fix.
  • An agent reads the same large file again and again in pages, or its edit fails with old_string not found right after a read: the read was packed and the agent is fetching the lines it needs. That is expected once per file; if the agent spends most of a task on one large file, set session.observationPack.tools to ["Bash", "Grep", "WebFetch", "mcp__.*"] and restart the daemon, so file reads stay whole.
  • session.observationPack.enabled is on and nothing is packed: restart the daemon; the hook is written into the workspaces at start. Then check that the agent's tier is claude-code, that its permissionMode is bypassPermissions and that the result was over limitBytes.
  • A lean session with session.lean.tools set starts no smaller than one without it: update AgentX. Versions up to 0.115.0 left ToolSearch out of the list, so Claude Code loaded every agentx tool description in full.
  • An agent on a lean channel says it has no tool to reply, label or send a message: that agentx tool is not in session.lean.agentxTools (or the channel's own list). Add it, or empty the list, and run agentx daemon restart --when-idle.
  • agentx config check says not an agentx tool: …: a name in session.lean.agentxTools or agentxToolsByChannel is misspelt, or starts with mcp__agentx__. Use the name exactly as agentx trace show prints it after mcp__agentx__.
  • The daemon log shows no agentx-tools= for a lean session with a list set: the channel's own list in session.lean.agentxToolsByChannel and the shared list are both empty, or the agent's tier is not claude-code.
  • A lean session still loads the user-level skills or the global CLAUDE.md: session.lean.settingSources contains user. Remove it, or check that the agent's tier is claude-code; other engines ignore these settings.
  • session.resumeGate is set and the log has no resume gate line: the line only appears when a claude-code agent picks up an earlier conversation that no other rule ended. A conversation that is new, silent for longer than staleMinutes, near its size limit or past maxTurnsPerSession starts fresh before the gate looks at it.
  • The gate starts conversations fresh that an agent still needed: raise session.resumeGate.margin, for example to 3, or set the mode back to "shadow".
  • Every line says resume: no context reading: the agent's last task ran without per-step usage, so there is nothing to compare. The conversation is picked up as before.

Released under the MIT License.