Agents and Profiles

An agent is Kandev's integration with a coding-agent CLI. A profile is its reusable launch configuration. Create separate profiles when model, credentials, or permissions need different trust boundaries.

The composer model picker shows the session's agent CLI logo beside the selected model and beside Model in the open popover. This identifies the CLI running the session, even when it supports models from several vendors.

Agent authentication is separate from repository and integration credentials.

Quick path

1. Rescan or install the agent on the host running Kandev.
2. Authenticate it as the same operating-system user.
3. Create a profile and verify model, mode, permissions, environment, and executor compatibility.
4. Use the advanced sections only when you need passthrough, MCP, or custom launch behavior.

Install or detect an agent

Open Settings > Agents (/settings/agents). Kandev scans the host on which its backend runs, not the browser computer.

The production registry currently shows Auggie, Claude, Codex, Copilot, Gemini, OpenCode, Amp, Qwen, iFlow (beta), Droid, Kilocode, Pi, Cursor, Kimi, Kiro, Qoder, Trae, omp, Devin, Grok, Hermes, Goose, Muse, and Antigravity. An entry is usable only when its executable is supported on the current platform and available to the Kandev process. Development and E2E profiles can add mock agents that are not product integrations.

Hermes launches with hermes acp. Install the required hermes executable from its Settings > Agents card, which runs the official Hermes installer. Hermes currently supports task and workspace sessions. Office-assigned skill injection is not yet supported.

Goose launches with goose acp. Its Settings > Agents card runs only the official download_cli.sh installer. Homebrew (block-goose-cli) and pip (pip install goose-ai) are manual alternatives. Configure your model provider with goose configure. Goose currently supports task and workspace sessions.

Antigravity has no automated install: Google distributes agy_acp_server.par (agy_acp_server.exe on Windows) and its localharness_external or localharness sibling (localharness_external.exe or localharness.exe on Windows) as a signed archive through the ACP registry rather than npm, so extract both files into one directory and add it to PATH yourself. Kandev fails discovery closed when the harness sibling is missing or not executable, so a partial extraction reports as not installed rather than as a broken session.

Muse command surfaces

Muse Code has no native ACP server, so Kandev runs it through the community @bex-co/muse-code-acp adapter, which is not affiliated with Meta:

• Structured ACP sessions and one-shot inference use npx --yes --prefer-offline @bex-co/muse-code-acp@<effective-version>, which needs Node.js 22 or later.
• The adapter drives the native muse executable through muse serve; CLI Passthrough starts muse directly.
• On POSIX hosts, the Muse install action runs the official https://dev.meta.ai/install.sh installer into the first writable directory on the backend's PATH. Windows has no automated Muse install action because the official installer is a POSIX shell script.

Kandev detects Muse when muse is on the PATH of the backend process and responds to --version. Sign in with muse login, or set META_API_KEY for headless and remote executors. Muse keeps sessions under ~/.local/share/muse, which Kandev uses for session resume. Kandev removes XDG_CONFIG_HOME and XDG_DATA_HOME overrides from Muse processes so credentials and sessions use these managed paths. Executors use an isolated home directory for both ~/.config/muse and ~/.local/share/muse; the real host home directory is not mounted.

The adapter starts sessions on the model in Muse's ~/.config/muse/settings.json and falls back to its own default otherwise, while the interactive muse CLI falls back to Meta's catalogue default. To pin one model for both, set it there, for example {"schema_version": 1, "model": "muse-spark-1.3"}.

Pi command surfaces

Pi uses separate executables for its two Kandev modes:

• Structured ACP sessions and one-shot inference use npx --yes --prefer-offline pi-acp@<effective-version>.
• CLI Passthrough starts the globally installed pi executable.
• The Pi install action runs npm install -g --ignore-scripts @earendil-works/pi-coding-agent.

After installation, select Rescan. Kandev detects Pi when pi is on the PATH of the backend process and responds to the non-interactive --version check. The pi-acp adapter is not the interactive terminal CLI, and managed ACP runtime selection does not replace the passthrough command.

1. Select Rescan after installing or updating a CLI.
2. If the card offers an install action, review the command before running it. Installation runs on the Kandev host.
3. If the card reports that login is required, open its login terminal or authenticate the CLI as the same operating-system user that runs Kandev.
4. Open the seeded default profile and review it before selecting the agent in a workflow step or session. Discovery creates one default profile the first time it provisions an agent. If you deliberately delete every profile, later rescans do not recreate one; create a replacement manually.

The status shown on this page is authoritative for the current host. A CLI that works in your interactive shell can still be absent from Kandev when the service has a different PATH, home directory, or operating-system user.

Update a managed agent runtime

The update icon is available on managed Claude, Codex, OpenCode, Copilot, Gemini, Pi, and Muse agent cards. It updates the runtime on the Kandev host.

Each managed runtime has a reviewed Kandev default. If you have not selected a version, Kandev uses that exact default for probes, sessions, standalone inference, containers, and SSH commands. A successful version update stores your exact selection for this Kandev installation. The selection takes precedence for the current default generation. Use Kandev default clears it, and a later shipped package or reviewed default resets it during startup. Kandev does not store the default as a user selection.

When a Kandev upgrade changes the managed package or its reviewed default, Kandev removes the older selection during startup before the service becomes ready. New probes and launches then use the reviewed default for that release. On the first startup with this generation tracking, Kandev treats an existing selection without a generation marker as legacy and resets it once. When the package and default stay the same, Kandev preserves your selection across restarts and unrelated upgrades. A process that is already running is not replaced, so the new default applies when Kandev starts a future process.

After startup, open the update control to select any validated stable version, including an older version. This lets you roll back the new default when a provider or environment requires it. The selection remains active until you change it or a later Kandev release changes that agent's package or default.

When the cached npm check finds a newer stable release, the update control has a blue dot and its accessible label includes the effective and latest versions. The dot is only a hint. Opening the control performs a fresh, authoritative preview before any update starts. If the check is unavailable, the control has no dot but remains usable.

1. Select the update icon.
2. Review the current version, active version, available stable versions, and command.
3. Keep the latest version selected for a normal update, or select an older stable version to roll back.
4. Select Update runtime, Roll back runtime, or Repair runtime.
5. Wait for the exact version to prepare and pass its ACP capability probe.

Kandev enables the action only after the backend validates the selected version against the trusted package catalogue. It does not accept package names, npm tags, prereleases, registry URLs, or command text. When the active version, observed version, and target version match, the action is disabled as Up to date. A successful activation updates the advertised models, modes, configuration options, commands, and runtime version without a page reload.

• The active exact version survives Kandev and browser restarts.
• Later host-local probes, utility calls, and standalone sessions use the active exact version.
• Active sessions keep running. They are not restarted or hot-swapped.
• Passthrough agents and authentication helpers remain unchanged. The Settings update job prepares the host runtime only; remote executor and new-container commands still use the effective exact version and must resolve that package in their own environment. Running sessions and containers are unchanged.
• If preparation, ACP validation, authentication, or persistence fails, Kandev keeps the previous active version and capability catalogue. Select another stable version or retry the same target.
• Kandev may prepare the exact version again if npm removes its cache entry. Kandev does not own an offline package inventory, and global npm cache cleanup is not required.

Recover a stale npm runtime lookup

Host-local managed runtimes normally start with npm's offline-preferred lookup. If npm has stale package metadata and cannot resolve the selected package@version, the first ACP startup can fail even though the configured registry contains that exact version. Kandev recognizes this specific npm resolution error, removes only the deterministic _npx execution tree for the selected package and version, then retries the same command once with an online-preferred metadata lookup.

Kandev also performs this recovery while it builds the host capability catalogue used by agent profiles. A successful retry publishes the recovered models and keeps the saved model, fallback model, mode, runtime version, and enabled state unchanged. The profile remains selectable and does not show a capability warning. Kandev reports a failed capability status if it cannot prepare the retry or repair the cache, or if the one online retry fails.

The same recovery applies to managed runtime startup on a local PC, in a local Docker executor, or in a remote SSH executor. Kandev sends the repair request to the agentctl process that owns the failed execution. That process resolves npm's cache with the agent environment and removes only the selected execution tree. It does not repair the Kandev host cache, delete sibling execution trees, change the registry, or clear the global npm cache.

The retry keeps the selected package, exact version, command prefix, model, permissions, and session identity. It does not change the npm registry or silently select another version. When the retry succeeds, no recovery card is shown. When it fails again, Kandev and Office show one Retry runtime action with collapsed technical details.

Do not use npm cache clean --force as the normal recovery step. It removes unrelated npm data and does not target the stale execution tree. If the specialized retry cannot resolve the runtime, check that the Kandev service uses the expected npm installation and configured registry. Run npm config get registry as the Kandev service user to inspect the registry used by that process. Then use the runtime update controls to select and prepare another trusted stable version.

Add a custom terminal agent

Add a custom terminal agent

Use Settings > Agents > Add TUI Agent for a CLI that Kandev does not register. Enter a display name, command, and optional model label. {{model}} in the command is replaced by the selected model value, then the entire command is split on whitespace with Go's strings.Fields.

That parser is not a shell and is not quote-aware: quotes and backslashes do not preserve a path or model containing spaces as one argument. Custom TUI agents always use terminal passthrough. They do not gain ACP features such as structured permission prompts, model discovery, modes, or session configuration merely by being added. Test the exact resulting argument split before assigning it to work.

Create and configure a profile

Select an agent, create a profile, then open Settings > Agents > Agent > Profile. The page shows the resolved command preview and only the settings supported by that agent.

Agents can inspect and update declared profile settings through the compact search_settings_kandev, describe_setting_kandev, get_settings_kandev, and update_settings_kandev tools. Use the separate agent_profile_mcp target for the profile MCP document. The settings tools preserve profile validation and save replacement lists atomically. They never return environment values or MCP credentials; use references or the existing interactive credential flow when a secret is required.

Model, mode, command, and configuration choices are probed from the locally installed CLI and cached. The managed Update agent action refreshes them automatically; after other CLI changes, refresh the profile manually. Probe status can report auth required, not installed, not configured, or failed; a saved model name does not prove that the current provider account can use it.

Use an OpenAI-compatible provider

Open the Provider section in a profile that supports this feature. Select OpenAI-compatible provider, enter the absolute router base URL, and select an optional global API-key secret. Enter the model ID that the router accepts. The model field is free text because the router owns the model catalogue.

Kandev sends the provider URL and optional bearer key through the ACP gateway authentication request when a new process starts. A running process keeps its existing provider settings until it restarts. CLI passthrough cannot use this provider because that path does not run the ACP authentication handshake.

Configuration options are resolved for the model selected in the profile. An agent can therefore show a different option set for each model. If a model change makes a saved option value unsupported, Kandev removes that value after a successful resolution; a failed resolution keeps the draft unchanged so you can retry it.

Use a dynamic profile

Choose the Dynamic agent family when you create a profile. Add concrete profiles in the order that Kandev must try them. The logical dynamic profile stays selected in the task and utility binding, while each launch uses one concrete candidate behind the scenes. Candidates must be enabled, launchable profiles. Dynamic profiles and rich Office profiles cannot be candidates.

Use the Dynamic agents card at the top of Settings > Agents to create and list dynamic profiles. The card is hidden, and dynamic profiles cannot be selected for new work, when dynamic routing is disabled. A new profile starts with its name and candidates; enable or disable it later from the profile editor.

Each candidate has a policy for two shared provider-error classes:

• Transient errors include capacity, overload, network, timeout, rate, and provider-availability failures.
• Hard errors include authentication, subscription, quota, credit, model, and provider-configuration failures.

For each class, configure exponential same-candidate retries, the maximum retry count, the initial interval, reset-date waiting with a maximum wait, and the final Skip candidate or Stop for manual recovery outcome. Kandev uses a trusted future reset date at most once for a candidate and class when it fits the configured maximum. It then applies the retry schedule and outcome. Unclassified, task, repository, permission, tool, and ambiguous mid-turn failures stop for manual recovery so Kandev does not repeat work. The error catalogue is versioned and can grow as provider signals become known; an ambiguous new signal fails closed. A future classifier may improve catalogue coverage, but no model is called to classify errors today.

After a provider switch, the failed provider is paused for the route health backoff, or until its trusted reset time when one is available. Kandev runs an exclusive health probe before it becomes eligible again. This shared error classification is used by task/Kanban and Office routing, while the per- candidate policies are configured on dynamic profiles.

When a task launch waits for session capacity, Kandev keeps the selected destination and retries it automatically. Inspecting another session does not resume a parked predecessor. Use an explicit Resume action or send a message for manual recovery. These actions can override the automatic ceiling.

Provider errors that occur before a result can use the configured action, such as retrying the current candidate or trying the next candidate. A started turn with an ambiguous result does not switch providers automatically. If no candidate is eligible, the session waits for a recovery action. After the current turn settles, use Retry current agent or Try next agent in the session recovery surface. These actions use the current route generation, so a stale browser action does not replace a newer route decision.

Host probes and executor model catalogs

The model list shown while editing a profile comes from a host probe. It is an editing hint, not a launch gate. A profile remains selectable when its saved model is missing from that host list. Profile selectors show an amber warning icon for this difference. On a desktop pointer, hover or focus the icon to read its tooltip. On a touch device, select the icon to open its warning drawer. Inspect the model list in profile settings for discovery details. Authentication, installation, and probe-failure indicators remain visible on profile selectors.

At task launch, the selected executor's ACP catalog is authoritative. Kandev sends the requested model only when the executor advertises it. Profiles are compatible by default, so an unavailable saved model can use an advertised explicit fallback, one unique bracketed variation, or the executor's current or default model. Kandev records one warning with the requested and effective models when it continues with a different model. Automatic fallback allows provider-default continuation and ignores the saved explicit fallback.

Enable Require exact model when the profile must keep the saved model. The executor must advertise and accept that model before the first prompt. An empty or unsupported catalog, an unavailable model, or a failed apply stops the session before inference. Kandev never sends an unadvertised model and never rewrites the saved profile model.

The host model list is only an editing hint. A missing host-probe model keeps a profile selectable and shows an advisory warning; the executor catalog decides the launch result. Upgrades and omitted API fields keep existing profiles compatible, with strictness off until a user enables it. Optional portable configuration can copy selected allowlisted files to a remote executor, but it cannot guarantee equal host and executor model catalogs.

Monitor capability and subscription status

Use the profile refresh control after installing, authenticating, or upgrading an agent. A manual refresh updates both the advertised models, modes, and commands and the visible capability status, so an old failure banner does not remain authoritative after the local CLI recovers.

Office agent quota and provider usage

Monitor Office agent quota

When Office mode is enabled, open Office > Agents and select an Office agent to see its Subscription Quota on the overview; the Office dashboard also summarizes the highest utilization across subscription agents. These cards appear only for supported subscription agents with provider credentials.

For account-wide provider usage across supported providers, install the Provider Usage plugin. It adds a provider pill to the session top bar and can add a compact display to the global status surface. That surface is off by default and follows the portable Show status bar preference under Settings > Preferences > Appearance > Status Bar; saving applies without a restart. If it is off, the session top-bar pill remains available. When it is on, the plugin can also appear in the desktop/tablet bottom bar or phone Status drawer. Configure the plugin under Settings > Plugins > Provider Usage. These usage surfaces are operational signals, not a billing ledger or a guarantee that the next request will be accepted; provider availability, account policy, and concurrent usage still apply.

CLI flags and ACP command prefixes

CLI flags

Each flag entry has a raw value, description, enabled state, and an agent-specific default where applicable. Only enabled entries reach the process. Kandev tokenizes each raw value as command arguments: --add-dir /shared becomes two arguments.

The field is not a shell script. Pipes, redirects, variable expansion, and command substitution do not run as shell syntax. Empty or malformed quoting is rejected. Keep separate profiles for materially different permission or workspace flags, and recheck customized flags after upgrading the CLI.

Claude CLI passthrough uses standard output by default. Add an enabled --verbose entry to the profile CLI flags when you need diagnostic output.

Some older profiles contain compatibility fields such as Auggie's allow_indexing; current launch behavior is represented by the active profile settings and flags.

ACP command prefixes

Command prefix is available for ACP launches, not terminal-passthrough launches. Kandev parses the prefix into structured argv rather than running a shell: quote a path containing spaces, for example "/opt/launchers/safe wrapper" --. The resulting argv is prefixed to the agent command, so shell features such as pipes, redirects, variable expansion, and command substitution are not evaluated.

The prefix must contain a nonempty first argv element that is not flag-like. Malformed quotes, a trailing escape, an empty launcher, or a prefix beginning with - is rejected when you save or preview it. If an older persisted profile contains an invalid prefix, Kandev fails the launch rather than silently running the agent without its configured launcher. Check the command preview after changing a prefix.

Environment variables and secrets

Create reusable secrets at Settings > Secrets (/settings/general/secrets), then select a secret reference in a profile environment entry. Secret names are 1–100 characters and values are 1–10,000 characters. Editing a secret with a blank value keeps the saved value.

Kandev has two secret scopes:

• Global secrets are available to the current user across their workspaces. When authentication is disabled, Global is install-global.
• Workspace secrets belong to one workspace and can be selected by that workspace's repositories. They are not available to shared agent or executor profiles.

The General page manages Global secrets. Manage Workspace secrets from Settings > Workspaces > workspace > Secrets. Agent and executor profile selectors intentionally show Global secrets only; a Workspace reference saved through an older or direct API path is rejected when the profile is saved or launched.

Copy or move a secret between scopes from the Copy/Move action on any secret row. The dialog picks Copy or Move, chooses a destination (Global or another workspace), and lets you edit the target name; it is pre-filled as <name> (from Global) or <name> (from <workspace name>) so copied secrets keep their origin visible. Moving removes the original after the copy is safely in place, and the value is transferred server-side between encrypted rows. It is never shown or copied through the browser. A target name that already exists in the destination blocks the action until you rename it.

Kandev encrypts secret values at rest with AES-256-GCM. The encryption key is <KANDEV_HOME_DIR>/data/master.key (by default ~/.kandev/data/master.key) and is created with owner-only file permissions. KANDEV_DATABASE_PATH does not relocate this key. Protect and back it up with the Kandev database; losing it makes stored values unreadable. Anyone with access to the Secrets settings can reveal the plaintext.

Profile environment rules are:

• at most 100 entries;
• key length at most 256 characters and value length at most 8,192 characters;
• keys cannot contain = or a NUL character, and values cannot contain NUL;
• duplicate keys are rejected;
• TASK_DESCRIPTION and every KANDEV_* key are reserved;
• an entry must use either a literal value or a secret reference, never both.

Kandev resolves secret references at process launch and cold resume. A deleted, missing, or unreadable secret blocks launch before the agent starts. The error identifies the environment key and its source.

Secret deletion is blocked while an agent profile, executor profile, or repository environment references the secret. When you select Delete, Kandev checks first. If the secret is in use, a dialog lists the affected resources and does not offer a delete action. Remove or replace those references before deleting the secret.

If a reference is already broken, open the named profile and select the replacement secret for the affected key, save, and retry. For a visible repository reference, open that repository's environment settings and replace the binding. A redacted repository reference means the repository is in a workspace that you cannot access; a workspace user with edit permission must locate and replace the binding in that workspace's repository settings. If no such user exists, ask a workspace owner or administrator to grant access or repair the binding. Creating a secret with the same name does not repair the reference because each secret has a separate ID.

API clients can explicitly force deletion. This leaves broken references and blocks future launches until those references are repaired. See the secret deletion API contract.

Repositories can bind an environment key to a Global secret or to a Workspace secret from the same workspace under Settings > Workspaces > workspace > Repositories. A task inherits bindings from every attached repository. Repository bindings are secret references, never values, and a repository binding to a deleted or unreadable secret blocks that task's launch. If two sources provide the same key, Kandev deduplicates an identical secret reference and rejects every other collision; repository order never chooses a winner.

Literal values remain in profile configuration. A secret reference avoids copying a token there, but the selected agent and its child processes still receive the plaintext at runtime. Use narrowly scoped credentials, and keep read-only review profiles separate from profiles allowed to publish, merge, deploy, or administer external systems.

Permissions and unattended work

In a structured ACP session, the agent can present a permission request and its available responses. With Auto-approve all permissions disabled, a person chooses a response in the session. With it enabled, the runtime selects the first allow-once or allow-always response without waiting. If the agent supplies no allow response, Kandev selects its first response even when that response is not approval; with no responses, it cancels.

Claude ACP also has a narrower built-in rule. When the agent uses the host-injected kandev MCP server, Kandev automatically selects an offered allow-once response, or allow-always when allow-once is not offered, even when Auto-approve all permissions is disabled. This covers every tool on that server, including task creation, task deletion, and plan changes. It is not a saved approval decision and is recreated for each task or Quick Chat session. Kandev still enforces MCP authentication, task and session authorization, user-question barriers, and workflow gates. Shell commands, file operations, third-party tools, and ambiguous requests keep the normal permission flow.

An external MCP client can also list live pending requests for an authorized task and submit one exact option originally offered by the agent. The request-generation ID prevents an old approval from targeting a replacement prompt that reused a provider pending ID. Kandev records who selected which option before delivery and rejects concurrent or replayed answers. It does not expose hidden environment values, headers, raw MCP arguments, or option metadata. See Resolve a live agent permission request.

Auto approval can authorize shell commands, file changes, network calls, or any other capability exposed by that agent. Agent-specific flags that suppress permission prompts can be broader still. Use either only with a constrained executor, repository, environment, and credential set.

Workspace automation selectors do not offer passthrough agent profiles. Local executor profiles are available for the repository-free target; Worktree requires a repository. Hidden automation sessions receive a fixed workspace-scoped coordinator MCP surface. Visible normal-task automations use the ordinary task profile and MCP surface. The trusted automation principal is resolved before hidden-run dispatch, and a hidden automation task and its sessions cannot be used as mutation, messaging, stopping, spawning, or blocker targets. Cross-task spawning uses the target task's normal profile. Native provider continuation and compaction remain authoritative for a healthy reusable session; Kandev's fallback resume prompt uses only the newest 50 non-empty user or assistant messages and excludes tool events. See Automation and MCP.

Structured ACP and terminal passthrough

ACP sessions can expose typed messages, tool updates, permission requests, models, modes, dynamic configuration, todos, usage, and resume metadata. Each capability depends on the agent's actual ACP implementation. ACP-only profile settings, including command prefixes and structured configuration, do not add those capabilities to a terminal-passthrough CLI.

Passthrough preserves the CLI's native PTY interface. It is useful when the native terminal has features that ACP does not expose, but Kandev cannot manufacture structured capabilities that are absent. Custom TUI profiles are locked to passthrough. Profile-specific MCP injection also varies by CLI; verify the command preview and the MCP section before depending on it.

MCP credential exposure: MCP headers and environment values are stored in profile configuration. Codex may place them in process arguments, and Cursor or Pi may leave them in project files after teardown. Use short-lived, narrowly scoped credentials and review persisted files.

Configure external MCP servers

Add external MCP servers to a profile

When an agent advertises MCP support, open its profile's MCP section. The editor accepts either a servers map or an object containing mcpServers.

Supported server types are stdio, http, sse, and streamable_http. If type is absent, a command implies stdio and a url implies http. Connection mode can be:

• auto: per-session for stdio and shared for a network transport;
• per_session: create a connection for each agent session;
• shared: reuse a network connection. Stdio cannot use shared mode.

The built-in task-aware server is injected separately. A profile server named kandev is ignored so it cannot replace the task server.

Executor policy can allow or deny transports or server names, rewrite URLs, and inject environment values. In the current launch wiring, profile MCP resolution starts from the standalone allow-all baseline for every executor and then overlays the selected executor profile's explicit MCP policy. A blank SSH, Sprites, or other remote policy therefore inherits allowed stdio, HTTP, SSE, and streamable HTTP transports; it does not receive the deny-all remote default defined elsewhere in the runtime. Set an explicit restrictive executor MCP policy before relying on remote isolation.

MCP JSON, including headers and server env, is stored as profile configuration. The raw editor has no secret-reference field for those values, so do not paste long-lived credentials into it unless access to the profile store is an acceptable boundary. Prefer a server that can inherit a narrowly scoped profile environment secret.

Passthrough injection adds CLI-specific exposure. Codex encodes MCP environment values and HTTP headers into -c process arguments, which another local user may read through process inspection. Cursor and Pi write project-local .cursor/mcp.json or .pi/mcp.json; when either file already exists, Kandev merges its entries and deliberately does not remove them at teardown because it does not own the user's file. Review and remove persisted entries or credentials yourself.

Kandev does not validate a server-name syntax centrally, so blank or unusual names can fail or be transformed differently by each CLI. A missing command/URL, unsupported or denied transport, or server-name policy denial skips that server with a warning. Configuring shared mode for a stdio server is different: it aborts profile MCP resolution with an error. Review launch/session logs when an expected tool is missing.

Delete profiles and custom agents

Deleting a profile is irreversible. Kandev checks references before deletion:

• active sessions and watcher references are soft conflicts; force bypasses the active-session check and soft-deletes the profile, while disabling affected watchers is best effort rather than guaranteed cleanup;
• enabled automations bound to the profile are disabled before it is deleted, and a failure to disable them aborts the deletion. Unlike watchers, an automation has no preflight that would notice a profile had vanished, so it would otherwise keep firing at a profile that no longer exists;
• feature-flagged Office routing-tier references are hard conflicts and cannot be forced;
• Kandev attempts to clean every ephemeral task with a session using the profile, including matching Quick Chat and Configuration Chat. A cleanup failure is logged and does not prevent profile deletion, so audit leftover resources afterward.

Only custom TUI agents can be deleted from the agent list. Built-in definitions remain registered even when their CLI is not installed.

Troubleshooting

• Agent unavailable after install: confirm the executable as Kandev's service user, select Rescan, and compare the service PATH with your shell.
• Login required: use the agent card's login terminal or sign in under Kandev's operating-system user; signing in as another user does not help the service.
• Model, mode, or command probe fails: authenticate first, refresh discovery, and choose a value advertised by the installed version.
• Launch fails after editing flags: inspect the command preview, remove stale arguments, and correct unmatched quotes or trailing escapes.
• Managed npm runtime cannot resolve its selected version: Kandev checks the configured registry and retries the same version once after refreshing its exact _npx execution tree. If the retry fails, verify the service user's npm configuration and registry, then use Settings > Agents to prepare another trusted stable version. Do not start with npm cache clean --force.
• Environment value is absent: confirm the secret still exists, the key is not reserved, and an executor/runtime variable is not already taking precedence.
• MCP server is absent: confirm agent MCP support, valid JSON, transport mode, executor policy, and the session warning logs.
• MCP tools are missing from one agent session: open MCP servers in that session's chat toolbar. Select kandev, then find the tool in the scrollable list. Select the tool to inspect its description, token estimate, and arguments. Use Back to tools, then Back to servers on touch devices. Connected means the built-in server completed MCP initialize. Active means it served tools/list. A gray row explains an intentional omission. Red identifies an explicit sanitized error. Delivered, connection unverified applies to a profile server that connects directly to the agent. Kandev cannot inspect that server's tools. Inspect the affected session because each report belongs to one session and execution.
• Automation cannot select a profile: passthrough agent profiles and Local executor profiles are intentionally omitted from the automation selectors.

Related: Executors, Automation and MCP, and the contributor guide Adding a new agent CLI.