# Native agent profiles

Intelligent Terminal discovers supported native agent CLIs installed on the
Windows host and exposes them as individual entries in the new-tab dropdown,
alongside shell profiles, with each provider's own icon. No agent folder is
created. These profiles can be edited, copied, hidden, launched in tabs
or panes, and selected with `wt -p`, just like a shell profile.

The supported providers are GitHub Copilot, Claude, Codex, Gemini, OpenCode,
and Google Antigravity.
WSL installations and arbitrary custom agents are not automatically generated.
Native profile discovery uses this dedicated provider list, not the broader
ACP or delegation provider registry.
Discovery does not install software, sign in, or start an ACP server. Native CLI
availability is independent of the adapters needed by the built-in agent pane.

Antigravity profiles discover the interactive `agy.exe` installed by the
[official CLI installer](https://antigravity.google/docs/cli/install), not an
`antigravity.exe` or the separate `agy_acp_server.exe`. The profile's stable
provider ID is `antigravity`. An ACP-only installation does not generate a
native profile; an `agy` installation does not need the ACP server to do so.

The generated profile icons use transparent SVG artwork. Copilot, Claude,
Codex, OpenCode, and Antigravity use dark artwork on light surfaces and their original
artwork on dark surfaces. Menus render the artwork without foreground tinting,
including hover and pressed states. Gemini and custom SVG icons retain their
original colors.

## Launch and configuration

A managed profile starts the native interactive CLI directly in a normal
ConPTY. Native executables are launched by Terminal; npm `.cmd` shims use the
Windows system `cmd.exe` with AutoRun and delayed expansion disabled. Neither
discovery nor profile launch runs WTA. Input, output, environment, working
directory, and process lifetime follow the ordinary Terminal connection path.
This does not draw a chat interface or connect the CLI through the ACP master.

Edit the profile in Settings. Existing starting-directory, environment,
appearance, elevation, and close-on-exit settings still apply. Fonts are
rendered by Terminal; an agent's explicit terminal colors may override colors
from the Terminal palette. Agent themes are not automatically synchronized.

The profile uses these additional, flat JSON properties:

```jsonc
{
    "name": "Claude - Project",
    "agentProfile.id": "claude",
    "agentProfile.model": "",
    "agentProfile.permissionMode": "",
    "agentProfile.arguments": "",
    "startingDirectory": "C:\\source\\project",
    "defaultSplitProfile": "default"
}
```

For generated profiles, keep their generated `guid` and `source` properties.
Agent identity does not depend on the profile's display name. User overrides
are layered on the generated settings and are retained if a CLI disappears.
Copy a profile to create multiple project configurations for the same agent.

An empty model or permission mode adds no corresponding managed option. The CLI
keeps its configured default unless an explicitly provided additional argument
changes it. Permission choices use provider-specific native modes.
The native CLI validates its option values and combinations.

The profile editor exposes model and additional startup arguments, but does not
include a permission-mode selector. Configure approvals through the CLI or set
`agentProfile.permissionMode` in JSON.
For Antigravity, `accept-edits` and `plan` map to `agy --mode`; an empty value
preserves the CLI's configured default.
The agent profile's Advanced page exposes only close-on-exit behavior and
environment-variable refresh. It omits the separate ACP agent-pane and
command-palette delegation selectors and the other terminal fine-tuning
controls; those settings remain available through JSON. Ordinary shell pages
retain their existing controls and selectors.
The Run as administrator control is also omitted from agent profile pages.
Shell prompt marks, automatic prompt marking, shell cursor repositioning, and
rainbow input suggestions are omitted from agent profile pages, including
copies and profiles with an edited command line. Ordinary shell profile pages
and existing JSON settings are unchanged.

Additional arguments use Windows command-line quoting, for example an argument
containing a space must be quoted. They are arguments, not PowerShell or command
prompt script text. Terminal passes them to the selected native CLI.
Consult the CLI's help for supported options. Structured model and permission-mode
options precede additional arguments; the CLI decides whether duplicate options
override earlier values or report an error.

Terminal applies its usual `%NAME%` environment expansion to the assembled
command line. The command preview displays the unexpanded command.
Embedded NUL characters cannot
be transported by Windows process command lines.
Batch shims reject `%`, `!`,
`^`, embedded quotes, and line breaks because they pass through `cmd.exe`.
Do not put credentials in command-line arguments.

`AllowedAgents` controls which native profiles are generated and offered.
The native CLI validates configured options and manages its approval settings.

The command-line field is directly editable, just like a shell profile. Saving
an explicit `commandline` runs that command unchanged by the agent command
builder; structured model, permission, and additional-argument settings no
longer apply and are hidden in Settings. Reset the command-line setting to
restore generated native commands and the structured controls. Simply opening
Settings or leaving the displayed command unchanged does not create an override.
Copying a generated profile retains its structured settings; copying an edited
profile retains its explicit command. Both copies retain their agent identity,
including settings inherited from the generated parent. Editing the command
does not turn the profile into a shell profile or remove its native provider
metadata. An explicit command supplied in a new-tab
action also overrides the managed launch, following ordinary Terminal action
precedence. An edited command is not a managed launcher or an operating-system
security boundary.

## Splitting panes

The Command Palette offers separate split choices:

- The original directional commands (for example, `Split pane, split: left`)
  use the global default profile.
- `Split pane (current profile), split: up/down/left/right` always starts another instance of
  the focused pane's profile, ignoring `defaultSplitProfile`. These reuse
  Duplicate pane actions, not Duplicate tab; no existing terminal contents or
  agent session is copied.
- `Split pane...` lets you explicitly choose a target profile.

The default split shortcuts and tab split action still use `splitMode: "profile"`.
Their built-in policy actions remain available to shortcuts and Settings without
adding another group of Command Palette choices. User-defined profile-mode
actions remain available in the palette.
Configure the source profile's `defaultSplitProfile` in `settings.json`; there
is no default split target control in the profile editor. For profile-mode
actions, it determines the target:

| Value | Result |
| --- | --- |
| Empty or omitted | Another instance of the current profile |
| `"default"` | The global default profile |
| A profile GUID, including braces | That profile |

An explicit `splitMode: "duplicate"` always starts another instance of the
current profile. An action specifying a profile, profile index, command, or
another content type keeps its explicit target. Existing user-defined actions
are not rewritten. A user-defined action with an omitted `splitMode` still uses
`manual` (the specified or global default profile), as does `wt split-pane`
unless `--duplicate` is supplied. Saved layouts retain their recorded profiles.

All new-terminal splits, including Alt-click profile selections and protocol
splits, inherit the source pane's working directory unless the operation supplies
an explicit directory. A compatible source directory takes precedence over the
target profile's configured starting directory. Ordinary new tabs continue to
use their configured starting directory. Shell-to-shell, shell-to-agent, agent-to-shell and
agent-to-agent splits follow the same rule. Native agents use their current
pane-bound session directory when available; otherwise their resolved launch
directory (including relative `-d` arguments), not subsequently edited settings.
Splitting while the built-in assistant is focused splits its source terminal,
leaving the assistant panel and conversation intact.
Unavailable or invalid directories fall back to the target profile's starting
directory. POSIX directories are inherited only between matching WSL launch
namespaces; no Windows/WSL or cross-distro path conversion is guessed.
Source identity comes from the running connection, not reloaded profile settings.
Commands are expanded before WSL validation; unknown source identities do not
inherit POSIX paths. WSL launches without an explicit distribution selector use
the target's normal startup directory instead, because the default distribution
may have changed since the source started.
Saved-layout, existing-content and session-resume arguments remain unchanged.
New-tab startup behavior is unchanged. A hidden,
missing, or invalid split target produces a warning and falls back to the global
default profile. The target is resolved once, not recursively through another
profile's split preference.

Splitting an agent profile starts a new CLI instance. It does not clone chat
history or automatically resume the source session. Moving a pane keeps its
running process. Managed layout restoration resolves the launcher again instead
of persisting a package-version-specific executable path. If the CLI has been
removed and the profile is orphaned, restoration recovers its native provider
identity and reports the unavailable CLI instead of opening a default shell.
Invalid or mismatched saved provider identities fail explicitly. Explicit
command-line overrides retain ordinary Terminal launch precedence.

## Discovery and lifetime

Discovery checks native CLI files directly during settings loading and Settings
Extensions enumeration, not each time the new-tab menu opens. It reads the fresh
Windows environment PATH and retains process-only PATH entries, preferring
`.exe` over `.cmd` across directories. It does not depend on `wta.exe`.
Windows app execution aliases, such as those registered in `WindowsApps`, are
recognized as launchable entries even when ordinary file-status queries cannot
follow them. The alias path is preserved so Windows can resolve the registered
application when launching the profile.
Successful results are cached for 30 seconds. After installing or removing a
CLI, reload settings after that interval or restart Terminal. There is no
30-second polling timer. A failed filesystem probe is
logged and retains the last successful in-process snapshot rather than treating
the failure as an uninstall. A failed refresh does not renew the cache TTL, so
the next discovery request retries. With no successful snapshot, the first
probe failure propagates to the settings loader.

Removing a CLI stops generation after the next successful uncached discovery.
Its saved profile becomes orphaned and leaves the active profile list, while
retaining user overrides. Reinstalling restores the same generated GUID and
settings. Deleting a generated profile and saving settings suppresses it through
Terminal's generated-profile state; rediscovery does not make it visible again.
Managed launches resolve the executable again at connection creation, so a stale
menu entry cannot run an unavailable CLI.

The default new-tab menu lists ordinary profiles first and automatically generated
agent profiles second, with a separator only when both groups have visible,
available profiles. Each group preserves the existing profile order and shortcuts.
The default layout means an omitted `newTabMenu` or exactly one
`{ "type": "remainingProfiles" }` entry. Grouping affects only the displayed menu
and does not rewrite `settings.json`. User-created copies without the generated
agent source stay in the ordinary group.

Agent profiles can be reordered through the new-tab menu settings or hidden
individually. Any other `newTabMenu` layout, including an empty list, folders,
explicit profiles, or separators, is rendered as configured without automatic
grouping or separators. Profiles also respect disabled profile sources and the
agent allowlist.

There is no WTA or hidden PowerShell process beneath a managed agent. The native CLI
decides what Ctrl+C means during interaction. When it exits, Terminal observes its
exit status and the pane follows `closeOnExit`; startup failures are not converted
into successful exits.

Existing per-tab agent-pane prewarming and AI-assistant toggling remain
independent of these native CLI profiles. Existing hook-based native-session
tracking is reused where supported; the launcher does not create a second ACP
session for the same CLI.