Type to search the docs and updates.

Browse documentation

Agent reference

Per-tool behavior for the fields on the agents page. Where a tool cannot honor a field, sync prints a note.

effort values by target

Without effort, the agent uses the session's level.

TargetValuesOutput
Claude Codelow, medium, high, xhigh, max, model dependenteffort, not checked
QoderSame five names, or a positive integereffort
JunieAlias of reasoningLeveleffort
Factorylow, medium, highreasoningEffort; other values raise a sync note
CodexAny stringmodel_reasoning_effort; an integer raises a note
CursornoneSync note. Put it in the model id, as above
CopilotnoneSync note. x-copilot.effort still passes through
Augmentoff, minimal, low, medium, high, xhighthinking (Auggie 1.x); other values raise a sync note, and x-augment.thinking wins
Every other targetnoneSync note

Claude model names on other targets

A shared model (a single value or default) set to a Claude model name is left out, with a sync note, on a tool that cannot load it. That tool uses its own default.

  • The note suggests model: {claude: <name>}, or names the tier to fix when the name sits in a tier's default.
  • on-unsupported: error fails the sync instead.
  • A value under model.<target> or x-<target>.model is written as given.
  • import claude writes these names as model: {claude: <name>}. import codex adds a Codex agent model as model.codex.
TargetClaude names that raise the note
Codex, Gemini, OpenCode, Kilo CodeThe aliases, inherit, and claude-* ids
Cursor, Factory, KiroThe aliases

Claude Code's aliases are sonnet, opus, haiku, fable, best, opusplan, sonnet[1m], and opus[1m]. The value default resets Claude's model instead of naming one, so it raises no note.

can and tools support by target

A tool that cannot enforce the list prints a sync note. Check these notes before relying on can: [read] to restrict an agent.

TargetBehavior
Claude Code, Copilot, JunieWritten as a YAML list
Qoder, TraeWritten as a comma-separated string (tools: Read, Bash)
Windsurf, Kiro, Factory, Gemini, Kilo Code, OpenCodeChanged to the tool's own names or a permission map
Antigravity, OpenHands, Goose, Codex, Cursor, AugmentDropped with a note

On Trae, an explicitly empty list disables all tools, and an unset field loads every tool. Use x-trae: {tools: ""} to restrict only Trae.

Translation can grant extra access: on Kiro, edit also allows delete_file. Sync prints a note naming the extra access, and on-unsupported: error fails. explain agents/<name>.md lists each tool's names and any widening. Most tools accept their own names through x-<target>.tools, which skips the change.

mcpServers support by target

mcpServers names the servers, usually from mcps/, that one agent may reach. Without it, the agent gets the session's full set. An agent-only server reaches only the agents that name it.

TargetBehavior
Claude Code, QoderServer names in the agent file. An agent-only server is written in full instead
KiroEvery named server written in full, under mcpServers
OpenHandsEvery named server written in full, under mcp_servers. Not when Goose shares .agents/agents/: set outputs.openhands.agents-dir
Junie, FactoryServer names in the agent file. An agent-only server's name is left out, except on Junie when it is the only name
AntigravityDropped; its docs give no shape for an inline server. Set x-antigravity.mcpServers
Gemini, CopilotDropped. Set x-gemini.mcp_servers or x-copilot.mcp-servers
Every other targetDropped, and agent-only servers left out, with a sync note

An x-<target> key for the list, such as x-kiro.mcpServers, replaces what sync would write. On Kiro and OpenHands, a name with no MCP spec is dropped with a note.

An empty list keeps every server on Junie and excludes every server on Factory, so list the servers you want.

maxTurns and background by target

A native key under x-<target>, such as x-gemini.max_turns, x-kilo.steps, or x-cursor.is_background, wins. An x-<target> override with the wrong type raises a sync note, and the shared value is used. validate, lint (LINT050), and sync stop on a maxTurns that is not a whole number of 1 or more, or a background that is not true or false.

TargetmaxTurnsbackground
Claude CodemaxTurnsbackground
QodermaxTurnsbackground, when background subagent sessions are on
Qwen CodemaxTurnsbackground
JuniemaxTurnsSync note
Gemini CLImax_turnsSync note
Kilo Code, OpenCodestepsSync note
CursorSync noteis_background
Every other targetSync noteSync note

import reads each native key back into maxTurns or background. When the spec already sets the value under x-<target>, import writes it back there and keeps the shared value.

permissionMode and agent hooks support by target

Without either field, the agent uses the session's setting. On Claude Code, a session in bypassPermissions, acceptEdits, or auto mode runs the agent in that mode and ignores its value, and an agent's own bypassPermissions never applies.

TargetpermissionModeAgent hooks
Claude CodeSeven values; manual is an alias of defaultWritten to the agent file
QoderSix values. Any other value is reportedSeven events. A wider setting is reported
OpenHandsDifferent names (always_confirm, never_confirm, confirm_risky). Set x-openhandsSix snake_case events, command handlers only. Set x-openhands
Qwen CodeNot written, with a note: Qwen maps Claude's names to its own approval modes with different strictness. Set x-qwen.approvalModeWritten to the agent file; Stop becomes SubagentStop. Project agent hooks need a trusted folder
CodeBuddyFive values; any other value stops syncWritten to the agent file. Running them needs the user's allowUntrustedFrontmatterHooks choice
Grok BuildWritten to the agent fileWritten to the agent file
JunieWritten to the agent fileCopied with the frontmatter, with a note: Junie documents no agent hook field
Every other targetSync noteSync note

On Qoder, bypassPermissions becomes acceptEdits when security policy disables it, and an agent runs fewer hook events than the project does.

color support by target

color is written as given and not checked. An unrecognized value affects only the badge.

TargetValues
AugmentFree text, an ANSI color name
Kilo CodeHex or a theme token, so color: blue may not show as expected
Claude Code, QoderOne of eight names: red, blue, green, yellow, purple, orange, pink, cyan
OpenHandsDropped with a note, since it shares .agents/agents/ with Goose, which has no color. Set x-openhands.color to a Rich color name

readonly by target

TargetEffect
CursorRestricted
Claude CodedisallowedTools: Write, Edit, NotebookEdit (Bash stays allowed)
Codexsandbox_mode = "read-only", which current Codex ignores (the agent keeps the session sandbox), and a sync note
Qwen CodedisallowedTools: [write_file, edit, notebook_edit] (shell stays allowed)
Factorytools: read-only with mcpServers: [] unless servers are listed. Wins over a portable tools list
Other targetsSync note

An explicit x-claude.disallowedTools, x-qwen.disallowedTools, x-codex.sandbox_mode, or x-factory.tools wins.