AgEnD Tips

Instance = Agent = one AI CLI you can talk to, such as Kiro CLI, Claude Code, Codex, Antigravity, Grok, or OpenCode.

Backend = the AI service that powers an Agent, such as Claude Code, Codex, or Kiro CLI. Different Backends provide different features and models.

One Instance = one separate Agent conversation; another Instance does not automatically know what was discussed here.

Fleet = all Instances managed by the same AgEnD; a fleet-wide restart affects every unpaused Instance, not just the current chat.

General = the coordinator Agent; ask it to choose an Instance, split work, or collect results when a task crosses projects.

A topic, thread, or channel = the chat location bound to an Instance; send the request there to reach that Agent.

Working = the Agent is handling something; Idle = it is ready for the next message.

Paused = the Instance is asleep but keeps its saved session; sending it a new message normally starts waking it.

Stopped = the AI CLI exited normally; Crashed = it exited unexpectedly or repeated recovery did not succeed.

Start a request with the result you want; add limits and output format after that so the Agent sees the main point first.

A good request = goal + important constraints + what counts as done; this reduces extra clarification rounds.

If wording matters, include one short example; an example usually communicates tone faster than a long explanation.

When changing an earlier instruction, name exactly what is replaced; otherwise both old and new instructions may stay in play.

`/steer <message>` = change the direction of work already running; it is supported by Claude Code, Codex, and Grok.

Use `/steer` for a correction to the current task, not for a separate job; unrelated work is clearer as a new message.

`/btw <question>` = ask Claude Code a side question without replacing the main task.

`/btw` and `/steer` are different: BTW opens a side question, while Steer changes the current work direction.

A busy Agent may queue a new message for later; delayed handling does not by itself mean the message was overwritten.

Do not resend a queued request just because the reply is slow; two copies can make the Agent do the same work twice.

Cancel button or `/cancel` = interrupt this run AND discard messages queued before it (messages arriving after the cancel are kept). The user message is already in conversation history; how much work already happened depends on when you cancelled.

AgEnD = the system that connects a Telegram or Discord chat to one or more Agents.

Cancel also clears older deliveries still waiting for that Instance, so queued cross-Instance or scheduled work will not start immediately afterward.

A message sent after Cancel is new work and will not be removed with the older queue.

⏳ = queued, 👀 = delivered, ✅ = turn confirmed, ❌ = failed; these marks describe delivery, not answer quality.

A delivery mark can appear before the Agent replies; it comes from AgEnD, not from the Agent's written answer.

If a message stays on ⏳, wait before resending; it may be waiting for the Agent to become ready.

If a message shows ❌, check the Instance status first; blind retries can hide the real startup, login, or connection problem.

Reply to an earlier message when the Agent must know exactly which text, file, or image the new request refers to.

A quoted reply includes the referenced text; add one sentence explaining what should be done with it.

Related requests work best in one clear message; unrelated requests are easier to track as separate messages.

Put the main request in the first few lines of a long message; details can follow without hiding the goal.

For long work, ask for a short progress update instead of sending the whole request again.

If the Agent asks a question, answer the missing point first; mixing in a new task can leave both requests unclear.

If an answer is wrong, quote the exact sentence or value to change; a precise correction is faster than saying only redo it.

At the end of a long discussion, ask for decisions + unfinished items; that summary is easier to hand to another Instance.

Attach the file and instructions in the same message so the Agent receives them as one request.

For an image, say what to inspect; sending only a picture forces the Agent to guess the question.

For a document, name the page, section, or question that matters; this avoids reading unrelated parts first.

Several attachments = explain each file's role; filenames alone may not reveal which one is input, reference, or expected result.

A Telegram voice message is delivered as audio; if speech-to-text is enabled, the Agent also receives a transcript.

Names, codes, and numbers in voice messages are easy to mishear; type the exact value once when accuracy matters.

A Telegram sticker becomes its emoji when one exists; a sticker without an emoji becomes `[Sticker]`.

A pasted image URL is still only a link; attach the actual image when the Agent must inspect the pixels.

On supported Discord replies, replying to a message with an image also sends that quoted image to the Agent.

Use text for important instructions; an emoji reaction alone may be recorded as feedback without starting work.

In a chat with several bots, mention the intended bot; otherwise the wrong persona may answer or nobody may act.

Tool progress = a short history of what the Agent is doing; when enabled, the button disappears after completion but the history remains.

Verbose progress can include command previews; check screenshots for private paths or values before sharing them.

An interactive prompt = the AI CLI is waiting for a password, permission, Y/N, or Enter; AgEnD will notify General instead of guessing.

AgEnD never types a password automatically; review the prompt before approving anything.

`/web` = a sign-in link and a one-time code for the web dashboard (web chat, View, Settings); it is an admin command because the code signs a browser in.

`http://localhost:19280` = the web dashboard and web chat by default; localhost means it normally opens only on the AgEnD machine, so a phone needs a way in first (SSH, Tailscale or a tunnel).

View shows Instance state, Context percentage when available, and live terminal output; use it to check whether work is actually moving.

View's AI Usage panel = subscription usage for Backends that currently have an Instance; unused Backends stay hidden.

`/usage` = show available AI subscription usage in the chat without opening View.

No data in `/usage` does not always mean zero quota; the account may be signed out, refreshing a token, or not exposing usage data.

Usage data is cached briefly to avoid provider limits; use Refresh in View when the latest number matters.

Quota = the amount included with an account or subscription; a warning may allow the current answer but block later work.

`/status` = the fleet overview, including Instance state and key health information.

`/sysinfo` = AgEnD, operating-system, runtime, and process details; use it when reporting an environment problem.

Context = how much of the current conversation the Agent can remember. When it fills up, use `/compact` to compress it or `/clear` to start over.

Context near full = older details may be compacted or lost; ask for a handover summary before a long task reaches the limit.

For a long Claude Code session, check `/ctx`; use `/compact` or write a handover summary before the limit to reduce lost details.

Codex normally manages conversation compaction itself, but important decisions should still be summarized instead of assuming every detail will survive.

`/compact` = shorten the current conversation while keeping useful Context where the Backend supports it; behavior differs by Backend.

`/model` = show models discovered for the current Backend; choosing one changes that Instance's model and saves the choice for restart.

The model list is probed when AgEnD starts; if a new model is missing, restart AgEnD, or use Discord's `/model refresh` to refresh it directly.

`/effort` = reasoning strength for supported models; higher effort may improve hard work but usually takes more time and quota.

`/save <name>` = export the current conversation for later reference; AgEnD supports it with Kiro CLI and Claude Code.

Discord Kiro ClassicBot `/load <name>` = load a conversation previously saved by Kiro; it is not a general restore command for every Backend.

Claude Code `/save` exports a Markdown file for reference; there is no matching AgEnD `/load` that restores it as a Claude session.

Kiro `/save` maps to `/chat save`; Discord `/load` works later only in the Kiro ClassicBot workflow.

Admin `/update` = install the latest AgEnD release from the current stable or beta channel, then restart the fleet.

Admin `/restart` = gracefully restart the whole Fleet, not only the current Instance.

Restarting wakes every unpaused Instance; startup takes time, and later recovery or summary work may use extra tokens, so avoid repeated fleet restarts.

Pause unused Instances before an update or restart if they do not need to come back immediately; paused Instances are skipped during fleet startup.

Admin `/pause` = put an Instance to sleep; `/wake` = start it again. General itself cannot be paused.

Settings can set automatic pause time; `0` means disabled, and sleeping unused Instances reduces background processes and restart load.

Changing auto-pause, progress detail, display name, description, tags, or log level is hot-reloaded and does not restart the Instance.

Backend, working-directory, or tool-set changes in Settings—and Backend options changed in config—are cold changes that restart the Instance.

ClassicBot = an Agent living in an ordinary Discord server/channel or Telegram group, rather than a pre-created Fleet topic.

ClassicBot does not interrupt every conversation by default; use `/chat`, while a bot mention also triggers it in Telegram groups or collaboration chats.

ClassicBot includes recent chat-log context before the triggered message; the default is the latest five lines, not the entire channel history.

To use ClassicBot, invite the bot to the Discord server or Telegram group, then an administrator runs `/start` in the target chat.

ClassicBot `/start` creates or resumes the chat's Instance with the ClassicBot default Backend; Settings can change the Backend afterward.

ClassicBot `/stop` removes that chat binding; use it only when the channel should no longer have its Agent.

A ClassicBot chat and a Fleet topic are routed differently; always run commands in the chat that owns the intended Instance.

Several bots in one collaboration chat = mention the right persona or use its slash command; each bot can own a different ClassicBot Instance.

A login-expired message = sign in to that Backend again; retrying the same request before login is fixed usually repeats the failure.

A model-not-supported message = the selected Backend or account rejected that model; choose another listed model instead of expecting a silent fallback.

A password or Y/N prompt that sits still will trigger a General notification; AgEnD will not answer it automatically.

For a bug report, include time + Instance name + what you sent + what happened; those four facts make logs much easier to match.

A screenshot from the View page shows the live Agent screen; check it for project names, paths, or secrets before sharing.

AI answers can be wrong; verify commands, prices, permissions, and other high-impact facts before acting.

Sensitive work = share only the files and values needed for this request; chat exports and screenshots may contain more than expected.

`/tips` = show another available Tip in the current chat; it does not have to be run in General.

✅ I know this = keep the Tip text but remove its buttons and stop showing that Tip again.

❓ I don't understand = keep the Tip text, record feedback, and allow that Tip to appear again later.

`/clear` = erase the current Context after confirmation; it cannot be undone, but project files and AgEnD instructions remain.

A useful Tip should tell you what changes for you; press I don't understand when the wording does not make the consequence clear.

Web chat = talk to an Agent from a browser; it is the same conversation as that Agent's Telegram or Discord chat, so you can switch between phone and computer mid-conversation.

Opening web chat = an admin sends `/web`, opens the sign-in link and types the one-time code; that browser then stays signed in, so you do not repeat this every time.

Files in web chat = attach with 📎, paste, or drop them on the chat; the Agent receives them exactly like files sent from Telegram (up to 5 files, 10 MB each).

Stop in web chat = interrupt the Agent's current reply, like the cancel button in Telegram; messages still waiting are dropped, but the Agent itself keeps running.

An Instance is one independent Agent. Each instance keeps its own conversation and can be assigned a different project.

A Fleet is the group of instances managed together by AgEnD. Fleet-wide actions can affect every running Agent.

General is the coordinator Agent that manages work. Ask General to choose a suitable instance, divide independent tasks, or manage the Fleet.

A Backend determines which AI service an instance uses, such as Claude Code, Codex, Kiro CLI, Grok, Antigravity, or OpenCode.

Context is the amount of information the AI can keep from the current conversation. It is limited and is not permanent project storage.

MCP is the channel that lets an AI use reply, file, and collaboration tools. Users normally ask for an outcome rather than operate MCP directly.

A Model is the particular AI selected inside a backend. Leaving it unset normally uses the fleet or account default.

A Session is a backend's saved conversation state. Whether it resumes after a restart depends on that backend's session support.

A working directory is the project folder an instance reads and edits. Separate instances may share one, but simultaneous edits can conflict.

ClassicBot is the mode that creates an ongoing Agent in an ordinary Telegram or Discord conversation, rather than a preconfigured Fleet conversation.

An Adapter is AgEnD's connection to one messaging bot account. In a multi-bot setup, an instance can be bound to a specific bot identity.

Telegram separates fleet conversations with topics; Discord may use channels or threads. These spaces serve the same routing purpose in AgEnD.

A Tool is an action an AI can call, such as reading a file or sending a reply. Tool availability depends on the backend and permissions.

A delivery queue holds messages until they can safely enter a busy Agent. A queued message is delayed, not necessarily lost.

Idle means an instance appears ready for input; Working means AgEnD sees it processing a turn. These states are observations, not guarantees about answer quality.

Paused means AgEnD intentionally stopped the Agent's CLI process while preserving its configuration for a later wake.

Stopped is an orderly exit; Crashed indicates an unexpected exit or repeated recovery failure. General can help inspect either state.

Settings is the browser editor for common AgEnD options. Hot settings apply immediately; cold settings change startup behavior and restart the affected instance.

View is the browser page that mirrors an instance's live terminal screen. It is useful when a prompt or progress display needs visual inspection.

A CLI is an AI program that runs from a computer terminal, and a TUI is the text-based screen it displays there. AgEnD sends messages into that screen, which users can inspect through View or from a computer terminal.

Use `/ctx` to check the current instance, backend, model, and available context estimate. Some backends cannot report a percentage.

Use `/model` without an argument to open the model selector. Administrators can use `/model <name>` to request a specific model.

AgEnD passes a safely formed model name to the backend even when its local pattern does not recognize it. The backend remains the authority and may reject it.

Use `/effort` without an argument to inspect available reasoning levels. Administrators can use `/effort <level>` when the backend and model support that level.

Reasoning effort changes how much work a supported model spends thinking; it does not change the backend or guarantee a better answer.

Use `/compact` when the context is crowded but the conversation should continue. Backend behavior differs; Antigravity maps this action to a full clear.

Use `/clear` to reset the conversation on a supported backend. It is administrator-only and asks for confirmation because prior context is removed.

Use `/cancel` or the Cancel button to interrupt the current turn. It also discards messages queued before the cancellation, but keeps messages arriving afterward.

Use `/pause` on an idle non-General instance to save resources. General cannot be paused because Fleet coordination must remain available.

Use `/wake` to start a paused instance immediately. Sending a normal message to a paused instance can also begin its wake process.

Use `/restart` only when the entire Fleet should restart. Ask General for an instance-specific restart when one Agent is unhealthy.

Use `/update` after active work reaches a safe point. Updating installs the selected AgEnD release and then restarts the fleet.

Use `/usage` to view available subscription metrics for backends used by running or paused instances. No data can mean unavailable telemetry, not zero usage.

Use `/web` to get a sign-in link and a one-time code. The code works once and expires after 5 minutes; treat it like a password and do not post it where someone else could use it first.

Use `/status` for an administrator-only fleet summary, including running, paused, stopped, and crashed instances.

Use `/sysinfo` to collect host and version details for an environment-specific problem report.

Use `/doctor` in General to check configured Backends. Run `agend doctor` from a trusted computer terminal for broader service and connection checks.

Use `/tips` to request another tip, `/tips off` to stop daily delivery, and `/tips on` to enable it again.

Use `/steer <message>` to redirect an active turn on Claude Code, Codex, or Grok. Unsupported backends return an explicit message.

Use `/btw <message>` for a side question on Claude Code without asking it to abandon the current task. Other backends report it as unsupported.

From General, administrators can use `/pause <instance>` or `/wake <instance>` to target a named Agent instead of opening its conversation first.

Use `/save <name>` only with Kiro CLI or Claude Code. Kiro saves a chat and Claude Code exports a Markdown file; other backends report unsupported.

In a ClassicBot conversation, `/start` creates or resumes its Agent and `/stop` removes that channel binding. Both are administrator actions.

Use `/collab` as an administrator to toggle whether bot messages may participate in a configured fleet conversation. Access rules still apply.

Settings stages edits until Apply is pressed. Review the pending changes before applying them, especially when a cold field will restart an instance.

Backend is a cold setting. Changing it in Settings selects a different Backend and restarts the affected instance.

Working directory is a cold setting. Confirm the destination exists and contains the intended project before applying it in Settings.

Model overrides can be changed with `/model` or Settings. If no override is needed, leave the field unset so normal defaults apply.

Tool progress controls how much live tool history appears under the working message. Choose off, standard, or verbose in Settings; it applies without restarting.

Display name changes how an instance is presented without changing its internal name. It is a hot setting in Settings.

Description and tags document an instance's responsibility and help General choose it. Both can be edited in Settings without a restart.

Auto-pause is an optional idle timer. It is disabled when set to zero and can be enabled or adjusted in Settings without restarting the instance.

Warm cap limits how many non-General instances remain active. Ask General to adjust it, or change `defaults.warm_cap` in fleet.yaml under advanced configuration and reload; existing instances do not need to restart.

Log level controls diagnostic detail. It is a hot setting, but more detailed logs may contain project or routing information.

Channel binding selects which configured bot identity a fleet instance uses. Set it in Settings when several bot accounts share a server or group.

Kiro UI controls whether Kiro starts with its interactive interface. It is backend-specific and changing it restarts the instance.

Terminal columns and rows define the logical screen size seen by the Backend. Change them cautiously because narrow layouts can hide or wrap permission prompts.

Settings reads effective values after defaults are applied, while saved instance entries can omit repeated defaults. Missing repeated fields are not necessarily lost settings.

A Schedule is a message delivered later or repeatedly. Ask General to create it for the instance responsible for the work.

A recurring schedule uses a cron expression, which describes a pattern such as every day at 09:00. A one-time schedule uses an ISO date and time, such as `2026-08-25T09:00:00+08:00`; use only one form per schedule.

A timezone tells a recurring schedule which local clock to follow. For example, `Asia/Taipei` makes “every day at 09:00” mean 09:00 in Taiwan rather than the server's local time.

A silent schedule hides the trigger message from the conversation, but the assigned Agent may still post a result when the task requires one.

A Team is a reusable group of instances for recurring collaboration, such as implementation plus review. Ask General to manage team membership.

A shared Decision records an agreed Fleet-wide choice so Agents can reuse it after restarts. Ask General to record durable architectural decisions.

Instances can exchange selected questions and results, but their full conversation histories and working directories are not automatically shared.

Ask General to parallelize only independent work. Two Agents editing the same files should coordinate ownership or work in separate copies.

A sender-side timeout—a notice that waiting for a reply took too long—does not prove a cross-instance message failed. Avoid resending solely because the sender stopped waiting.

When an Agent waits for a password or confirmation, AgEnD can notify General. Review the visible prompt before authorizing any manual input.

Do not send passwords, access tokens, or private keys through chat. Enter secrets only in a trusted terminal when an authorized prompt requires them.

Delivery-status reactions mean ⏳ queued, 👀 delivered, ✅ turn confirmed, and ❌ failed. They describe transport, not whether the answer is correct.

Avoid using 👀, ⏳, ✅, or ❌ as ordinary reactions because AgEnD reserves them for delivery status.

Replying to an earlier message gives the Agent quoted Context. Supported Discord replies can also include images from the referenced message.

Attachments are copied to a local inbox before delivery. The Agent receives a local file path, so sensitive files should be shared only with an appropriate instance.

A permission prompt is a safety boundary from the Backend. Read the requested file or command scope before approving it.

After sixty intermediate tips are dismissed, AgEnD offers an Advanced Tips unlock button. An administrator can also enable them with `/tips advanced on`.

Claude Code supports subagents, which are focused helper AIs inside the same CLI. They can research or review while the main agent coordinates the result.

Claude Code permission modes decide whether file and command actions are allowed, denied, or require approval. Choose a mode that matches the project's risk.

Claude Code can resume saved sessions, but continuity depends on the same project path and available session data.

Claude model families usually trade capability, speed, and cost differently. Use the current account selector for exact availability rather than relying on a static list.

Opus is generally aimed at demanding work, Sonnet at balanced work, and Haiku at lighter faster work. Current provider documentation remains authoritative.

Codex uses a sandbox, which is a boundary around model-generated commands. Sandbox scope and approval policy are separate controls.

Codex accepts queued input while it is working. Follow-up messages can enter its native queue instead of waiting for an idle gap.

Codex Skills are reusable instruction packages discovered when relevant. They keep detailed workflows outside the always-loaded conversation.

A custom provider is an alternate model service configured in Codex. AgEnD can select it, while its URL and credential environment variable remain in Codex configuration.

Custom Codex models may show a metadata warning because built-in model details are absent. The provider's actual response determines whether the model works.

Kiro Specs are project documents that organize requirements, design, tasks, and execution. They are useful when a feature benefits from an explicit plan.

Kiro Steering files are persistent project guidance. They can keep conventions available without repeating them in every conversation.

Kiro Skills use progressive disclosure: the CLI first sees a short description and loads detailed instructions only when relevant.

Kiro's `auto` model mode lets the CLI choose dynamically. Set `model: auto` explicitly only when it should override a fleet-level model default.

Grok can provide web search and page retrieval when enabled by the installed CLI, account, and policy. Availability should be checked in the current environment.

Grok supports steering through `/steer`, but its available models and tools can vary by account. Treat the CLI's current list as authoritative.

OpenCode distinguishes primary agents for main work from subagents for focused tasks. Project configuration can change which agents and permissions are available.

OpenCode model names commonly use a provider/model form. Check OpenCode's current model list instead of assuming that a bare model name is accepted.

OpenCode provider definitions belong in its own configuration. AgEnD selects a model from what OpenCode exposes rather than storing provider credentials.

OpenCode does not currently expose an AgEnD `/effort` mapping. Use model or agent settings supported by OpenCode instead.

Antigravity supports multi-step work and tool calls through its terminal interface. Its account and installed version determine available models and integrations.

Antigravity has no separate summarizing compact command in AgEnD. Both `/compact` and `/clear` use its full conversation-clear action.

Different GPT variants can target different capability, latency, and cost points. The names visible to the current CLI account are the source of truth.

Automatic model selection may choose differently between turns. Pin a model only when repeatability matters more than flexibility.

A model available to one account may be unavailable to another. Verify access with the target backend before changing several instances at once.

Before a migration or bulk edit, copy fleet.yaml and classicBot.yaml outside the working path. Keep the backup until a representative restart and message round trip succeed.

Instance entries may omit values inherited from defaults. Compare effective configuration, not only raw YAML, when diagnosing what a daemon received.

AgEnD removes redundant default-valued leaves when saving fleet.yaml, while retaining identity fields such as backend, model, working_directory, topic_id, and backend_options.

Lossless YAML editing preserves unrelated structure and comments where possible, but a comment attached only to a removed node may have no node to remain on.

Run `agend validate` after manual YAML edits and before reload. Validation catches schema errors without requiring a fleet restart.

Hot fields are reconciled in place, while cold fields restart affected instances. Check the Settings change summary before applying a mixed patch.

A SIGHUP reload updates the running fleet from validated configuration; it is not equivalent to restarting every CLI process.

Backend, working_directory, tool_set, lightweight, and backend_options are cold instance fields. Changing them can recreate the affected CLI process.

Tool progress, display name, description, tags, log level, and auto-pause settings are designed for hot reconciliation. Verify the daemon acknowledged the update when diagnosing stale behavior.

Use per-instance overrides only when behavior must differ from defaults. Fewer duplicated values make later default changes and reviews easier to reason about.

A backend option is interpreted only by its matching backend. For example, `backend_options.codex.provider` selects a provider but does not define that provider's endpoint or credentials.

Codex custom-provider definitions belong in Codex config, and secrets should be referenced through environment variables available before the fleet service starts.

OpenCode provider definitions belong in opencode.json, while AgEnD's model field should use the identifier exposed by OpenCode, commonly `provider/model`.

Treat model-name compatibility checks as hints. The CLI remains the source of truth, so AgEnD passes configured model names through instead of silently falling back.

An unset instance model first inherits defaults.model. To request a backend's own default while a fleet model default exists, configure the backend-specific default explicitly where supported.

Kiro's `auto` is an explicit model choice. Set it on the instance when it must override a non-auto defaults.model value.

Model failover reacts to supported usage telemetry and applies on a later rotation. It cannot replace a model safely in the middle of an active turn.

Cost guards are limited by provider telemetry. Missing, cached, or delayed usage data reduces enforcement precision and should be visible in operational expectations.

Usage results are cached to reduce provider calls. Use the View panel's Refresh control when an immediate post-login or post-renewal fetch is required.

A provider absent from `/usage` may simply have no running or paused instance. Usage visibility follows effective backends, not every installed CLI.

Keep bot tokens, dashboard tokens, provider keys, and exported sessions out of repositories and shared workspaces; each requires its own rotation procedure.

When a CLI supports an environment-key reference, store the secret in the service environment rather than fleet.yaml or a provider config committed to source control.

Files such as web.token and per-instance state should remain readable only by their owner. Copying them into a project can expose them through backups, diffs, or agents.

A browser stays signed in to the dashboard across fleet restarts (up to 48 hours by default). Send `/web revoke`, or run `agend web-token rotate` on the host, to sign every browser out at once; a running fleet applies it without a restart.

A dashboard URL is usable only after the health server is listening. A port conflict should fail closed instead of publishing a URL backed by the wrong process.

Channel allowlists are authorization boundaries, not display filters. After changing access rules, test both an allowed identity and a rejected identity.

Before changing a locked channel's allowed_users, ensure at least one administrator remains. An empty locked allowlist can remove every administrative path.

Nonce-bound confirmation buttons are tied to their adapter, chat, thread, message, and administrator identity. A copied callback should not authorize another context.

In a multi-world fleet, assign channel_id explicitly to General and fleet-topic instances when the first configured adapter is not the intended persona.

ClassicBot routing is keyed by its own channel records. Do not apply fleet-topic adapter canonicalization to ClassicBot replies in multi-bot collaboration channels.

Terminal columns and rows affect both TUI layout and captured wrapping. After changing geometry, verify ready, permission, and error detection against real pane samples.

The terminal validator enforces conservative geometry bounds because very narrow panes can wrap permission prompts beyond recognition.

AgEnD pins tmux window size and attaches control clients with size ignored; both protections are needed to keep logical geometry stable across reconnects.

Mouse mode is enabled only in AgEnD's tmux session. It allows scrollback after attach without changing unrelated user sessions.

`capture-pane` observes physical screen lines unless wrapping is joined. Width changes can therefore change parser input even when the logical text is identical.

Ready, busy, and error patterns are heuristics over terminal text. Preserve anonymized real samples and add production-path tests before changing a pattern.

A false idle can retire controls or deliver input too early. A false working can delay messages and trigger hang notifications.

Periodic statusline redraws are not necessarily work. Backend-specific pane handling should distinguish cosmetic redraws from changed task content.

Tune hang_detector from observed silent-work intervals, not from an arbitrary short timeout. Inspect pane and process evidence before restarting.

Interactive-prompt alerts require both a prompt-like pattern and stable output time, reducing false alerts when an agent merely discusses passwords or confirmations.

Administrator-only `/raw <text>` sends text directly to the backend without AgEnD's normal inbound wrapper. Use it only when that wrapper would change an intentional CLI command.

A writable tmux control client is required for special-key delivery. Treat a failed Enter or interrupt command as a command failure rather than waiting for a later timeout.

pasteLock serializes terminal writes even for backends with native input queues; native queuing does not make overlapping PTY pastes safe.

Codex accepts busy-time input into its own queue, so AgEnD bypasses the idle gate for Codex while retaining first-delivery startup settling.

Cancel uses a delivery epoch to invalidate messages already queued before the cancellation. Messages arriving afterward carry the new epoch and remain deliverable.

A message transport timeout does not prove non-delivery. Check delivery logs or idempotency evidence before retrying an external or cross-instance send.

A replaced IPC client must lose listeners and have its socket destroyed. Removing only the map entry can leave an orphan processing outbound messages.

Disconnect, overflow, and close events should converge to one disconnect per client lifecycle, with reconnect serialized per instance.

If duplicate replies persist across simple messages, inspect client and socket counts before blaming rich-message rendering or the model.

Schedule-trigger metadata must include the instance's configured adapter identity; otherwise a reply after restart can fall back to the wrong bot persona.

The fleet singleton lock protects manager startup, not individual instance restarts. Per-instance restart serialization remains a separate requirement.

When two fleet processes appear, collect PID, parent PID, command line, lock owner, service state, and listening ports before terminating either process.

A service-managed fleet should fail closed when the user service manager is unreachable, rather than starting an untracked detached duplicate.

On Linux over SSH, a missing D-Bus session can make `systemctl --user` unavailable even when the unit file exists.

Treat `active` and `activating` as occupied service states. An uncertain service query should not authorize a second startup.

A health-port conflict may indicate a stale manager or another service. Identify the listener before changing the port or stopping a process.

Recovery paths should serialize per instance so health checks, MCP recovery, manual restart, and config reconciliation cannot create competing replacements.

Crash-loop protection stops automatic recovery after bounded repeated failures and reports crashed rather than idle; successful recovery must clear stale crash markers.

Restart backoff limits resource use when a CLI repeatedly fails during startup. Disabling retries can be appropriate while diagnosing a deterministic configuration error.

MCP auto-restart waits for an eligible idle state and deduplicates restart requests. It restarts the instance because the CLI owns the MCP child connection.

Configure mcp_proxy_reply only for panes whose visible text is safe to relay. Regex redaction cannot guarantee removal of every project-specific secret.

Proxy replies are a last-resort channel path after MCP loss, not a source-of-truth transcript. Inspect them for terminal chrome or incomplete output.

Session resume is backend-owned. AgEnD can preserve identifiers, workspace paths, and markers, but it cannot guarantee semantic continuity after a CLI upgrade.

OpenCode resume should use a recorded session identifier. Global `--continue` can select the latest session from an unrelated directory.

Claude Code project-session lookup depends on encoded workspace paths. Renaming or moving a workspace can make an existing session appear absent.

Per-instance Codex homes isolate MCP configuration and instance decisions. Writing those entries to a shared Codex config creates a cross-instance authorization risk.

SQLite database files must not be separated from active WAL, SHM, or rollback-journal sidecars. A sidecar linked from another home can make the private database unusable.

When a database base file is intentionally symlinked, verify where SQLite creates sidecars with the library version in production rather than assuming path behavior.

scheduler.db contains schedules, decisions, task state, and tip state. Take a consistent backup before direct maintenance and avoid writes while the fleet is active.

A runtime schema audit should compare CREATE statements, every referenced column in queries, and the actual schema from the deployed SQLite files.

Adjust startup concurrency according to available memory and measured CLI startup cost. Raising concurrency can increase contention and make total startup slower.

Use startup stagger delay to spread process creation and authentication load. Persisted paused instances are excluded before stagger slots are assigned.

warm_cap is a fleet-wide capacity limit, while auto_pause_after is a per-instance idle-time policy. Observe workload patterns before combining them.

A zero warm_cap means unlimited, and a zero auto_pause_after disables time-based pausing. General is excluded from automatic pause and warm-cap eviction.

Many resident CLIs consume substantial memory while idle, although idle state alone does not spend model tokens. Measure RSS before setting a warm cap.

Lightweight mode omits backend-dependent transcript, context-guardian, and error monitors to reduce overhead. Enable it only when those missing observations are acceptable.

Every exposed MCP tool schema consumes model context. Use minimal or standard tool sets for narrowly scoped workers and broader profiles only when required.

General receives the coordinator tool profile when tool_set is inherited. Explicitly setting standard or minimal can remove tools required for coordination.

Verbose tool progress may retain command previews in channel history. Use standard or off when operational details should not be exposed to channel readers.

Raise log verbosity only for a bounded diagnostic window. Restore the normal level afterward and review logs before external sharing.

Bundled skills are role-filtered before CLI startup: General receives all eligible skills, workers receive shared or worker skills, and ClassicBot is skipped.

The managed-skill manifest distinguishes AgEnD-owned copies from user content. A missing legacy manifest requires conservative adoption to avoid freezing old managed skills.

Instances sharing one workspace also share backend-native skill directories. Mixed roles or backend families can contend over managed files, so separate workspaces are safer.

Use separate git worktrees for parallel write tasks. A detached checkout used for inspection should remain read-only.

Templates define repeatable groups of instances, but deployment still needs explicit branch, workspace, ownership, and teardown expectations.

Teams are routing groups, not shared memory. Each member retains its own context, session, and workspace boundary.

A silent schedule injects work without requiring a channel reply. Use it only when the absence of user-visible output is intentional.

Schedule timezone is part of execution semantics. Verify daylight-saving transitions when the selected IANA zone observes them.

Schedules that trigger after a restart still need the target instance's effective adapter and delivery epoch so routing and cancellation remain correct.

Fleet decisions preserve durable architectural context. Supersede or retire stale decisions so later agents do not receive conflicting instructions.

Event logs support diagnosis but are not substitutes for source configuration, provider audit records, or raw process evidence.

Chat exports can include names, project details, tool summaries, and quoted messages. Review and redact them before external sharing.

Installation prompts for sudo passwords or confirmations require human review. Non-interactive automation should fail clearly rather than guessing an answer.

`agend doctor` distinguishes backend availability from service, D-Bus, fleet, tmux, and IPC health; read each section rather than treating one green check as fleet health.

After an update, canary one representative instance per backend before resuming the full workload. Include ready, permission, error, reply, and context checks.

Keep the previous package version and compatible configuration backup until update health checks and representative canaries pass.

When rewriting Git history to remove secrets, preserve a mirror backup, verify all refs and tags, and rotate exposed credentials even after blobs are removed.

A safe rollback restores compatible code and configuration together. Reverting only one side can leave a schema or behavior mismatch.

Before destructive cleanup, resolve exact paths and owners with read-only checks. Prefer recoverable moves or backups when practical.

For difficult incidents, preserve synchronized timestamps, fleet logs, process trees, socket counts, service state, and pane captures before restarting away the evidence.