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.
| Key | Type | Default | What it does |
|---|---|---|---|
node.id | string | required | Stable id of this machine. Used to label workflow runs and as this node's name on the mesh. |
node.name | string | required | Readable name of this machine, shown in logs and mesh listings. |
node.bind | string | "127.0.0.1:18800" | Address and port the daemon API listens on. |
node.defaultAgent | string | — | Agent used by voice and API calls that do not name one. |
node.connectAttemptTimeoutMs | number (250–60000) | 5000 | How 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>) | Type | Default | What it does |
|---|---|---|---|
apiKey | string | — | 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. |
defaultModel | string | — | Accepted by the validator but not read by the current runtime. Set model on the agent instead. |
baseUrl | string | — | 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. |
thinking | boolean | — | Turns thinking-mode output on or off for orchestrator agents on backends that support it. Ignored elsewhere. |
"providers": {
"claude": { "apiKey": "${ANTHROPIC_API_KEY}" }
}agents
One entry per agent, keyed by agent id (agents.<id>).
Key (under agents.<id>) | Type | Default | What it does |
|---|---|---|---|
name | string | required | Display name of the agent. |
workspace | string | required | Folder 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). |
provider | string | — | Provider name in providers for sdk (default claude) and orchestrator (default claude-code) agents. |
model | string | — | Model id passed to the engine. Unset uses the engine's default. |
systemPrompt | string | — | Extra instructions added to every run of this agent. |
mentions | list 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. |
team | string | — | 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. |
intents | list of string | [] | Intents this agent may handle, such as issue.opened. Empty allows any intent. |
maxDelegationDepth | number (0–50) | 5 | Refuses 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. |
mcp | map 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. |
codegraph | boolean | false | Adds 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. |
contextReferences | boolean | false | Adds a checked list of references from the workspace's references/ registry to the agent's context. |
richMessages | boolean | true | Lets 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. |
maxConcurrent | number | 1 | How many runs of this agent can happen at the same time. |
maxExecutionMinutes | number (1–240) | 20 | Time 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). |
preSpawnTimeoutSec | number (10–3600) | 300 | Time 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. |
drainTimeoutSeconds | number (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. |
permissionMode | string | "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.enabled | boolean | false | Sends 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.maxPerDay | number | 0 | Most cloud sessions this agent may start per day; 0 means no limit. Past it, tasks run locally. |
cloudSessions.openHours | number (1–168) | 24 | How long a started session counts as open: no local run starts for its issue, and comments on the issue are forwarded to it. |
cloudSessions.launchTimeoutSeconds | number (10–600) | 120 | How long claude --cloud may take to print the session id before the launch is given up and the task runs locally. |
worktrees.enabled | boolean | false | Runs 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.root | folder | .agentx-worktrees/<clone name> beside the clone | Where the worktrees are made. |
worktrees.maxAgeDays | number (1–365) | 14 | A worktree no task used for this many days, with no uncommitted change, is removed. Its branch stays. |
wiki.contribute.enabled | boolean | false | Once 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.maxPatches | number (1–200) | 30 | Most suggestions one daily run may make. |
wiki.contribute.maxCostUsd | number (0–20) | wiki.contributions.maxCostUsd | Most model spend one daily run may reach, in dollars. |
wiki.contribute.model | string | wiki.contributions.model | Model for this agent's daily run. |
wiki.notes.dir | string | the 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.enabled | boolean | true | false 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.monthlyUsd | number (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.warnRatio | number (above 0, up to 1) | 0.8 | Share of budget.monthlyUsd at which you get one notice for the month. |
toolUseRequired | list 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. |
gitlabAutoReply | boolean | — | For this agent, overrides the GitLab or GitHub channel's autoReplyLegacy: true posts the agent's final answer as a comment, false does not. |
persistentProcess | boolean | false | Keeps 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. |
admin | boolean | — | Lets the agent pause, resume and request deletion of schedules created by others. Approval stays with the operator. |
subscriptions | list 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.enabled | boolean | false | Runs a periodic check-in inside the agent's ongoing session. |
heartbeat.intervalMinutes | number | 30 | Minutes between check-ins. |
heartbeat.prompt | string | "Check inbox, pending tasks, and system health. Report anything that needs attention." | What the agent is asked at each check-in. |
heartbeat.channel | string | "heartbeat" | Channel name the check-in runs under. |
integrations | list of object | [] | Services this agent has credentials for. See the table below. |
voice | object | — | How the agent sounds. See the table below. |
presence | object | — | How the agent's on-screen cursor looks. See the table below. |
"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.
| Rule | Engines | Why |
|---|---|---|
| Read the code before trusting an issue thread or earlier comments. | claude-code, codex-cli | Threads 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-code | A 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.
| Key | Type | Default | What it does |
|---|---|---|---|
type | "stdio" | "http" | "stdio" | Kind of server. Leave it out for a local command. |
command | string | required for stdio | Program to start. |
args | list of string | [] | Arguments for command. |
env | map of string | — | Environment variables for command. |
url | string | required for http | Address of the HTTP server. |
headers | map 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. |
headersEnv | map 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. |
allowTools | list 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. |
readTools | list 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.
Terminal: add the server's key to the
.envfile in your AgentX folder, as one line such asCONNECTOR_API_KEY=<your key>.Terminal: open
agentx.jsonand 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_*"] } }Terminal: run
agentx daemon restart.
How the list is applied depends on the agent's engine:
| Engine | Tools not on the list |
|---|---|
orchestrator | Never shown to the agent. |
claude-code | Shown, but every call to one is refused by the AgentX guard, with the reason. |
codex-cli, opencode | Not 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.
- Agent: the agent calls a write tool, for example
CREATE_POSTon theconnectorserver. - Browser: open Approvals on the dashboard. A card titled
<agent> wants to write with connector: CREATE_POSTshows what the agent wants to send. - 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:
"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.
| Action | What 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. |
propose | Sends 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.
| Key | Type | Default | What it does |
|---|---|---|---|
kind | string | required | Service, 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. |
label | string | required | Readable name, unique per agent and kind. |
credentials | object | {} | Where the secret lives. Only the keys below are accepted. |
credentials.tokenEnv | string | — | Environment variable holding the main token. |
credentials.privateAppTokenEnv | string | — | Environment variable for a private app token. |
credentials.apiKeyEnv | string | — | Environment variable for an API key. |
credentials.refreshTokenEnv | string | — | Environment variable for an OAuth refresh token. |
credentials.clientIdEnv | string | — | Environment variable for an OAuth client id. |
credentials.clientSecretEnv | string | — | 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.sessionDir | string | — | Folder holding a login session, for services such as WhatsApp. |
metadata | map of string, number or boolean | {} | Non-secret details (username, host, account id), shown in the dashboard and to skills. |
metadata.reads | string | — | 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_id | string | — | 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.oauthExpiresAt | string, number | — | Written by agentx agent integrations connect: the permissions granted, when, and when a token that cannot renew itself runs out. Not secret. |
enabled | boolean | true | Turns the integration off without removing it. |
Voice
agents.<id>.voice overrides the global voice settings for one agent (AgentX Voice).
| Key | Type | Default | What it does |
|---|---|---|---|
voice.provider | "system" | "elevenlabs" | — | Speech engine for this agent. Unset uses the global voice.provider. |
voice.system | string | 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.fallbacks | string[] | — | Voices to try in order when voice.system is not installed. Unset picks the best installed voice of the same language and gender. |
voice.elevenlabsVoiceId | string | — | ElevenLabs voice id. |
voice.gender | "female" | "male" | "neutral" | — | Guides which voice is picked when none is set. |
voice.style | string | — | A few words on manner, such as "warm, calm". |
voice.intro | string | — | 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.
| Key | Type | Default | What it does |
|---|---|---|---|
presence.color | string (#RRGGBB) | from the agent id | Cursor colour. |
presence.initial | string (up to 2 letters) | from the name | Letters on the cursor. |
presence.label | string | the agent's name | Name shown under the cursor. |
presence.allowActions | boolean | — | 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.
"people": [
{ "id": "anis", "name": "Anis", "role": "owner", "identities": ["telegram:123456789", "github:your-login"] },
{ "id": "sara", "name": "Sara", "identities": ["gitlab:sara.b", "whatsapp:21620123456"] }
]| Key | Type | Default | What it does |
|---|---|---|---|
people[].id | string | required | Short 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[].name | string | required | The person's name, for you to read. |
people[].say | string | — | 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[].role | owner, member, client or guest | member | A 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[].identities | list 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[].agents | list 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.tools | list 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.skills | list 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).
| Setting | Type | Default | What it does |
|---|---|---|---|
members.logRetentionDays | number | 90 | Days 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.
| Key | Type | Default | What it does |
|---|---|---|---|
session.staleMinutes | number (1–1440) | 720 | Minutes of silence after which a conversation starts fresh. |
session.maxTurnsPerSession | number (2–200) | 40 | Turns after which the conversation is rotated to a new session. |
session.tierTwoThresholdTokens | number (50000–200000) | 180000 | Context size, in tokens, at which the conversation is rotated. |
session.tierTwoThresholdTokensByChannel | object 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.maxClaudeCodeDispatchesPerHour | number (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.maxClaudeCodeDispatchesPer5h | number (0–50000) | unset (off) | The same optional ceiling over five hours. |
session.continuityStateTurns | number (0–5) | 0 | Extra earlier requests shown to the session-continuity decision. 0 keeps the default two messages. |
session.profileByChannel | object 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.mcpServers | list of string | ["agentx"] | Tool servers from the workspace's .mcp.json that a lean session keeps, by name. agentx is always kept. |
session.lean.settingSources | list 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.contextOnDemand | boolean | true | Leave 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.tools | list 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.toolsByChannel | object 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.agentxTools | list 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.agentxToolsByChannel | object 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.midTurnMessages | boolean | true | A 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-code | string | unset (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-cli | string | unset (off) | The same for codex-cli agents, such as a gpt- model. |
session.triage.actions | list 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.memoryIndexMaxChars | number | 0 | Longest 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.enabled | boolean | false | Keep 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.limitBytes | number (1024–1048576) | 10240 | A text result larger than this many bytes is replaced by an excerpt. |
session.observationPack.headBytes | number (0–65536) | 1024 | Bytes of the start of the original the agent sees. |
session.observationPack.tailBytes | number (0–65536) | 1024 | Bytes of the end of the original the agent sees. |
session.observationPack.tools | list 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.retentionDays | number (0–3650) | 0 | Days 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.freshTokens | number (1000–200000) | 30000 | Tokens a fresh lean session starts with. |
session.resumeGate.cacheTtlMinutes | number (1–1440) | 60 | Minutes the saved conversation is assumed to stay in the provider's cache. |
session.resumeGate.cacheWriteFactor | number (1–4) | 2 | Price 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.margin | number (1–10) | 1.5 | How 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 gets | What a lean session gets instead |
|---|---|
Every connected tool server, and the agentx tool server with them | Only the agentx tool server, plus the ones named in session.lean.mcpServers. |
User-level settings: global CLAUDE.md, user skills, plugins | Only the workspace's own settings and skills (session.lean.settingSources). |
| The landscape in the prompt | The agentx_agents tool with landscape: true. |
| Today's history of this chat in the prompt | The agentx_recent tool with the chat's channel and chatId. |
| A summary of the agent's other chats today | The agentx_recent tool without a chatId. |
| (both) Stored knowledge, as before | The agentx_wiki_query tool, as before. |
| (both) What a colleague is on, or where a piece of work stands | The 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:
"session": {
"profileByChannel": { "github": "full" }
}To make a chat channel lean, or keep a second tool server in lean sessions:
"session": {
"profileByChannel": { "telegram": "lean" },
"lean": { "mcpServers": ["agentx", "codegraph"] }
}To see what a session on a channel is handed, before and after:
- 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. - 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:
Terminal: look at what the agent's tasks on that channel use. Run
agentx trace show <taskId>on a few recent runs; thetool_usesteps name the tools.Terminal: open
agentx.jsonand set the list, for all lean channels or for one:json"session": { "lean": { "tools": ["Bash", "Read", "Edit", "Write", "Grep", "Glob"], "toolsByChannel": { "cron": ["Bash", "Read"] } } }Terminal: run
agentx daemon restart --when-idle. The daemon log line for the next lean session ends withtools=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
ToolSearchis in the session (always, see above), Claude Code sends only theagentxtool 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=falseis set orANTHROPIC_BASE_URLpoints 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:
Terminal: look at what the agent's tasks on that channel use. Run
agentx trace show <taskId>on a few recent runs; thetool_usesteps name each one asmcp__agentx__agentx_….Terminal: open
agentx.jsonand set the list, for all lean channels or for one. Use the names without themcp__agentx__start:json"session": { "lean": { "agentxTools": ["agentx_channel_reply", "agentx_channel_label"], "agentxToolsByChannel": { "a2a": ["agentx_send_agent"] } } }Terminal: run
agentx config check. It prints✓ Config valid. A misspelt name stops here withnot an agentx tool: ….Terminal: run
agentx daemon restart --when-idle. The daemon log line for the next lean session ends withagentx-tools=N, the number ofagentxtools 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:
- Terminal: run
agentx memory index --agent <agent id>and look at its length. - Terminal: open
agentx.jsonand set the cap, for example"session": { "memoryIndexMaxChars": 4000 }. - Terminal: run
agentx daemon restart --when-idle. The prompt uses the cap at once; theCLAUDE.mdblock 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 aclaude-codeagent.
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:
Terminal: open
agentx.jsonand 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"] } }Terminal: run
agentx config check. It prints✓ Config valid.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:
[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:
(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.
"session": {
"observationPack": { "enabled": true }
}What it covers, and what it does not:
| Agents | claude-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 acting | Not 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. |
| Tools | The 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 reads | Packed 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 output | Claude 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 base64 | Never packed. Only text is. |
| Claude Code version | The 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 text | The text of the event or message that starts a task is not a tool result and is not packed. |
| Timing | The excerpt replaces the result at once. The agent never sees the full result unless it reads the saved file. |
| Sessions outside the workspace | A 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:
- Terminal: before turning it on, in the folder with
agentx.json, runagentx usage channels --from 2026-10-01 --to 2026-10-03 --save before.jsonwith three recent full days. It prints the cost per channel and per task, and saves the figures. - Turn the pack on and restart the daemon. Let it run for a few days.
- Terminal: run
agentx usage channels --from <first day> --to <last day> --baseline before.jsonwith the days after the restart. It prints both ranges side by side with the change in cost per task. - 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.
"session": {
"resumeGate": { "mode": "shadow" }
}To try it without changing anything:
- Terminal: in the folder with
agentx.json, runagentx usage channels --from 2026-10-01 --to 2026-10-03 --save before.jsonwith three recent full days. - Set
session.resumeGate.modeto"shadow"and save. Let it run for a day. - Terminal: run
agentx daemon logs | grep "resume gate". Each line says whether the conversation would have started fresh, with both prices. - If the lines that say
would start freshare conversations you would not miss, set the mode to"active"and save. - Terminal: after a few days, run
agentx usage channels --from <first day> --to <last day> --baseline before.jsonand 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.
| Key | Type | Default | What it does |
|---|---|---|---|
processPool.maxIdleSeconds | number (5–86400) | 30 | Seconds 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.maxAgeSeconds | number (60–86400) | 2700 | Seconds after the last question it was asked when a process with no work of its own is always stopped. |
processPool.maxBackgroundSeconds | number (60–86400) | 10800 | The 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.sweepIntervalSeconds | number (1–300) | 5 | How 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
| Key | Type | Default | What it does |
|---|---|---|---|
plugins | list of string | [] | Installed npm package names loaded as plugins when the daemon starts. |
Check it worked
- Terminal: in the folder with
agentx.json, runagentx config check. It prints✓ Config valid. - Terminal: run
agentx config get agents.helper.maxConcurrent, using your own agent id. It prints the value you set. - Terminal: run
agentx agent list. The agent appears with its engine and model. - Terminal: after a GitHub event or a schedule runs, run
agentx daemon logs. A linesession profile for github: lean (mcp=agentx settings=project,local context=on-demand)shows the lean start took effect. - Terminal: with
session.lean.agentxToolsset, after a lean session starts, runagentx daemon logs. Thesession profile for …: lean (…)line ends withagentx-tools=N. - Terminal: with
session.triage.modelsset, after a label event on an issue nobody has worked on for an hour, runagentx daemon logs. A linetriage event (labeled) → <model>shows the cheaper model was used. - Terminal: with
session.observationPack.enabled, the daemon log showsObservationPack: PostToolUse hook written to N workspace(s)at the first start (andN agent(s) not packedfor agents outsidebypassPermissions), and.agentx/observations/<agent id>/index.jsonlgets 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. - Terminal: with
session.resumeGate.modeset to"shadow", after an agent picks a conversation up, runagentx daemon logs. A lineresume gate (shadow) for <channel>:<chat>: would resume: …orwould start fresh: …shows both prices. In"active"mode, a linecost rotation for …marks a conversation that started fresh. - Terminal: with
headersEnvorallowToolson a tool server, runagentx doctor. A lineN MCP server(s) with header variables, all setshows the keys were found. Open the agent's.mcp.json: the header reads${CONNECTOR_API_KEY}, not the key itself. - Terminal: after a
claude-codeagent calls a write tool of a server withallowTools, runagentx daemon logs. A lineguard: <agent> asked to run mcp__<server>__<tool>: card <card id> waits for the ownershows the card was raised. The card is in Approvals on the dashboard. - 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>.jsonsays"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 doctorsaysMCP server "<name>" of <agent>: header variable(s) not set: add the named variable to.envand 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'sreadToolsand 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-codeagent says a tool call was refused withis not on the allowTools list: the tool is left off that server'sallowTools. Add its name (as the message prints it) if the agent should use it, then restart the daemon. - A
claude-codeagent says a call was refused because itneeds 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, thenagentx daemon start) and try again. - A
claude-codeagent says a call was refused becausethe 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 exceptagentx daemon start|restart|statusand thelaunchctlorsystemctlcommands 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 checknames 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 failedorETIMEDOUT, whilecurlfrom the same machine works: the daemon gave up connecting too early. The start of the daemon log showsConnect attempt timeout: N ms. Raisenode.connectAttemptTimeoutMs, for example to10000, and restart the daemon. - An
sdkagent fails withNo API key for provider: setproviders.<name>.apiKey, or check that the environment variable it points to is in.env. - An agent with
persistentProcessanswers 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 idlefor that agent a few minutes after its last reply: update AgentX. Earlier versions stopped a warm processmaxIdleSecondsafter the last question, even while its background tasks were still running. If the log showskilled stalewithstale with background work, the work ran longer thanprocessPool.maxBackgroundSeconds(3 hours by default): raise it. - A model or engine change is ignored: restart the daemon fully with
agentx daemon stop, thenagentx 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_recentandagentx_wiki_querytools, add the tool server it misses tosession.lean.mcpServers, or set that channel to"full"insession.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 asopened), the issue's conversation ran within the last hour, or the model does not start withclaude-(forclaude-codeagents) orgpt-(forcodex-cliagents). - The daemon log says
N agent(s) not packed: those agents do not run withpermissionMode: "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 foundright 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, setsession.observationPack.toolsto["Bash", "Grep", "WebFetch", "mcp__.*"]and restart the daemon, so file reads stay whole. session.observationPack.enabledis on and nothing is packed: restart the daemon; the hook is written into the workspaces at start. Then check that the agent'stierisclaude-code, that itspermissionModeisbypassPermissionsand that the result was overlimitBytes.- A lean session with
session.lean.toolsset starts no smaller than one without it: update AgentX. Versions up to 0.115.0 leftToolSearchout of the list, so Claude Code loaded everyagentxtool description in full. - An agent on a lean channel says it has no tool to reply, label or send a message: that
agentxtool is not insession.lean.agentxTools(or the channel's own list). Add it, or empty the list, and runagentx daemon restart --when-idle. agentx config checksaysnot an agentx tool: …: a name insession.lean.agentxToolsoragentxToolsByChannelis misspelt, or starts withmcp__agentx__. Use the name exactly asagentx trace showprints it aftermcp__agentx__.- The daemon log shows no
agentx-tools=for a lean session with a list set: the channel's own list insession.lean.agentxToolsByChanneland the shared list are both empty, or the agent'stieris notclaude-code. - A lean session still loads the user-level skills or the global
CLAUDE.md:session.lean.settingSourcescontainsuser. Remove it, or check that the agent'stierisclaude-code; other engines ignore these settings. session.resumeGateis set and the log has noresume gateline: the line only appears when aclaude-codeagent picks up an earlier conversation that no other rule ended. A conversation that is new, silent for longer thanstaleMinutes, near its size limit or pastmaxTurnsPerSessionstarts fresh before the gate looks at it.- The gate starts conversations fresh that an agent still needed: raise
session.resumeGate.margin, for example to3, 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.
