Agents & Models

Agentty delegates coding work to external AI agent CLIs running in session worktrees. Install and authenticate at least one backend.

Supported Backends🔗

Agentty supports four agent backends. Each requires its respective CLI to be installed and available on your PATH.

• Codex (codex, recommended; supports subscription usage): install the Codex CLI, then run codex login.
• Claude (claude): install Claude Code, then run claude auth login.
• Antigravity (agy 1.1.18 or newer): install the Antigravity CLI, then run agy and follow its sign-in flow. Agentty excludes older versions from provider selection and reports agy update as the recovery step if a session encounters an outdated executable.
• Gemini (gemini): install the Gemini CLI and authenticate with an API key or Vertex AI.

All CLI backends accept pasted local prompt images from the Agentty composer (Ctrl+V, Ctrl+Shift+V, or Alt+V in prompt mode) and run their turns non-interactively inside the session worktree.

Codex Auto Edit turns run with full command access so browser tests, local services, and other tools that cannot run inside the provider sandbox remain available. This also means Codex commands are not confined to the session worktree; review the session diff and use Read Only for inspection-only work.

Claude turns also allow Claude Code's WebSearch and WebFetch tools, so prompts that need current external information can use the web without an interactive permission grant. Claude Auto Edit retains Claude Code's unsandboxed command fallback for tools that cannot run inside its sandbox.

Treat fetched web content as untrusted context. Claude still has edit-capable tools during the turn, so keep web-backed prompts specific and review the session diff before merging.

Agentty requires at least one supported backend CLI on PATH at startup and fails with an install hint when none is found.

Agentty uses each provider's official non-interactive CLI or app-server surface (claude -p, agy --input-format stream-json, codex app-server, or gemini --acp) after you authenticate with that provider's CLI. It does not implement OAuth flows, read provider OAuth tokens directly, or call private provider APIs. You are responsible for choosing an authentication method permitted for your account, plan, and usage pattern.

Harness Sessions (Preview)🔗

Start Agentty with agentty --experimental-harness to add a Harness session type that runs Agentty's built-in agent loop instead of an external CLI. It talks directly to a model provider using an API key from the environment:

Without the flag the session type is hidden; with the flag but no configured provider it is shown disabled. With a configured provider, Agentty starts even when no backend CLI is installed; the other session types are then disabled and the selector opens on Harness. A Harness session's /model lists only harness models, and other sessions never list them. Choosing a harness model never changes the project's default model.

• Read Only turns can read the worktree. Auto Edit turns can also write files and run unsandboxed bash, which can reach the network and paths outside the worktree, like Codex full access. Provider keys and endpoints are removed from the bash environment.
• Answers arrive in one piece; the activity footer shows tool calls while a turn runs.
• Commit messages and titles use the project's default fast or smart model when one is set and its agent CLI is installed, otherwise the session's harness model. Focused review likewise falls back to the session's harness model when the review model's CLI is not installed.
• History is stored per session under ~/.agentty/harness/ and removed with the session. Image attachments are not supported yet; a prompt with pasted images fails before reaching the model.
• Each completed turn's content-free harness report, with per-request token usage, context fitting, corrections, and tool activity, is kept in the harness_turn_report table of Agentty's database for later analysis, including after the session is deleted.
• Switching away from kimi-k3, kimi-k2.6, or qwen3.8-max is rejected once the session has their reasoning history. Switching to another provider needs only that provider's key.

Subagent Limits🔗

Agentty requests a limit of two concurrent subagents per Codex or Claude session, excluding the parent agent. It applies the limit when starting the provider process, including when resuming a saved session. Restart Agentty after updating to apply the limit to existing sessions.

Codex limits concurrently open child-agent threads. Claude limits ordinary subagent spawning, but provider exceptions such as resumed subagents can exceed the limit. Enforcement depends on the installed CLI supporting its native setting. Gemini and Antigravity have no verified concurrency setting, so Agentty does not cap their internal subagents.

These are per-session provider limits, not host-wide CPU or memory limits. Multiple sessions each have their own allowance, and builds or tests can consume additional resources.

Authentication and Usage🔗

Codex🔗

Codex is the recommended backend when you want subscription-backed usage. The CLI supports signing in with ChatGPT through codex login, and Agentty uses the supported codex app-server integration surface. Usage remains subject to the OpenAI Terms of Use.

Claude🔗

For Agentty usage through claude -p, use API-key authentication through Claude Console or a supported cloud provider instead of a Claude Free, Pro, or Max subscription sign-in. Anthropic's Claude Code legal and compliance documentation describes subscription OAuth as intended for Claude Code and native Anthropic applications, while developer integrations should use API keys or supported cloud providers.

If Claude session turns or utility prompts fail with authentication_error, Failed to authenticate, or OAuth token has expired, refresh the CLI session and retry:

claude auth login
claude auth status

Antigravity🔗

For Agentty usage through agy headless mode, prefer authentication backed by a Google Cloud project or API key rather than Google Account subscription sign-in. The Antigravity terms do not currently explain how subscription access applies when third-party tools invoke headless sessions.

Antigravity retains conversation context between turns and resumes it after a restart.

Gemini🔗

Google Account OAuth no longer works for Gemini CLI after Google's transition from Gemini CLI to Antigravity CLI. Use GEMINI_API_KEY or Vertex AI authentication, or choose the Antigravity backend instead.

Project Instruction Files🔗

Agentty relies on each backend's native project-instruction discovery instead of inlining repository guidance into prompts.

• Codex loads AGENTS.md.
• Claude Code loads CLAUDE.md.
• Gemini CLI loads GEMINI.md.
• Antigravity CLI loads AGENTS.md and GEMINI.md from the active workspace.

Keeping CLAUDE.md and GEMINI.md as symlinks to a canonical AGENTS.md gives all backends the same repository guidance.

Selecting a Backend🔗

Use /model to choose a locally available backend, then one of its models.

The Projects tab shows installed CLI versions and updating... during startup refresh. Antigravity, Claude, and Codex use their native updaters; Gemini updates only when Agentty recognizes an npm-global installation. If an Antigravity executable changes while Agentty is running, wait for discovery or restart before retrying a turn.

In Settings, choose a model and reasoning level for each project role. Claude and Codex also offer Normal or Fast response speed. Unavailable backend defaults fall back to an installed backend.

Session overrides take precedence. Changing defaults does not alter existing sessions. Default Response Style initializes new sessions as Concise, Balanced, or Detailed.

Antigravity maps xhigh and max reasoning to high. Claude maps both to max, which is supported by claude-opus-5-5. Codex supports a distinct max effort.

Available Models🔗

Each backend exposes one or more selectable model entries with different trade-offs between speed, quality, and cost.

Antigravity and Gemini Models🔗

Both providers share the same Gemini model ids:

• gemini-4-argon: Gemini 4 Argon model.
• gemini-3.1-pro-preview (default): Higher-quality Gemini model for deeper reasoning.
• gemini-3.8-flash: Fast Gemini model for agentic and multimodal tasks.
• gemini-3.5-flash-lite: Lightweight Gemini model for fast, cost-conscious workloads.

Claude Models🔗

• claude-fable-5-1 (default): Claude Fable model for creative, narrative-heavy tasks.
• claude-opus-5-5: Latest Claude Opus model for complex agentic tasks.
• claude-sonnet-5-5: Balanced Claude model for quality and latency.
• claude-haiku-4-5-20251001: Fast Claude model for lighter tasks.

Codex Models🔗

• gpt-6-astra: Most capable Codex model for the hardest end-to-end work.
• gpt-6.1-sol (default): Near-Astra Codex model for complex work at a lower cost.
• gpt-6-luna: Efficient Codex model for focused, high-volume tasks.
• gpt-5.6-terra: Current Codex model for balanced coding performance.
• gpt-5.3-codex-spark: Codex spark model for quick coding iterations.

Harness Models🔗

Available only in Harness sessions. New Harness sessions start on the first listed model whose provider is configured:

• muse-spark-1.3: Muse Spark model.
• kimi-k3: Latest Kimi model.
• kimi-k2.6: Previous Kimi model.
• qwen3.8-max: Most capable Qwen model.
• qwen-plus: Balanced Qwen model.

Each request stays within an input budget below the model's context window. Because Agentty estimates tokens from text size, it holds back the model's output reserve plus a quarter of the window. Older turns that no longer fit are left out; after switching to a model with a smaller window, the next turn fits history to that model's budget.

Stored Model Upgrades🔗

Model pickers show only the current models listed above. When a stored project default or active session references a superseded model, Agentty upgrades and persists its replacement automatically. Finished sessions preserve their historical model data.

Switching Models🔗

Use /model to change the current session's backend and model, /reasoning to change reasoning effort, and /style to choose answer length. See Slash Commands for response styles and permission modes.

Claude and Codex also support /speed. Fast reduces latency at higher provider cost and may switch to a compatible model:

Returning to Normal keeps the resulting model. Choosing an incompatible model resets speed to Normal. These changes do not alter project defaults. Gemini and Antigravity have no speed control. See the provider guides for Codex fast mode and Claude Code fast mode.

To change defaults for future sessions, use Settings. See Settings Scope.