Agentty ADE

Agentty is an ADE (Agentic Development Environment) for structured, controllable AI-assisted software development. Built with Rust and Ratatui, and refined through its own day-to-day use, it brings agents, review, and iteration into one focused terminal workflow.

Installation · Supported CLI Agents · Usage · Documentation · Contributing · License

Codex, Claude, Gemini, and Antigravity sessions show compact tool status and command previews, with output previews for failed calls. Explicit Claude skill invocations appear alongside them, and answers retain saved usage counts.

Press w in session view to inspect saved execution graphs, accept exact outputs, answer node questions, retry work, resume dispatch, or cancel a graph.

The /plan workflow uses bundled Markdown agent definitions. Repository overrides live in .agents/agents/<id>/agent.md; see the workflow guide for the supported format.

Installation

npm (recommended)

The npm, Bun, and pnpm packages require Node.js on your PATH. Global installs support automatic updates through the original package manager when Agentty can identify it.

npm install -g agentty

Other methods

bun add --global agentty

pnpm add --global agentty

npx agentty

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/agentty-xyz/agentty/releases/latest/download/agentty-installer.sh | sh

cargo install agentty

Supported CLI Agents

Agentty currently supports Codex, Claude, Antigravity, and Gemini. Install and authenticate at least one provider CLI before starting a session:

• Codex (codex, recommended; supports subscription usage): install the Codex CLI and run codex login.

[!NOTE]

Codex is the recommended CLI agent for Agentty when you want subscription-backed usage. Codex supports signing in with ChatGPT for subscription access, including in the CLI, and Agentty uses the Codex app-server integration surface. Usage remains subject to the OpenAI Terms of Use. OpenClaw documents ChatGPT/Codex subscription sign-in as the normal Codex harness path, and opencode recommends ChatGPT Plus or Pro authentication for its OpenAI provider.

• Claude (claude): install Claude Code and run claude auth login.

[!WARNING]

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 docs describe subscription OAuth as intended for ordinary use of Claude Code and native Anthropic applications, while developer integrations should use API keys or supported cloud providers. Theo's explanation video discusses the same uncertainty, but commentary does not guarantee that subscription-backed usage is safe for third-party tool invocation.

• Antigravity (agy): install version 1.1.18 or newer of the Antigravity CLI and run agy to sign in when prompted.

[!WARNING]

For Agentty usage through agy headless mode, use authentication backed by a Google Cloud project or an API key when available for your Antigravity setup, rather than a Google Account subscription sign-in. The Antigravity terms do not yet clearly describe how subscription access applies when agy headless mode is invoked by third-party tools.

• Gemini (gemini): install the Gemini CLI and authenticate with an API key or Vertex AI.

[!WARNING]

"Sign in with Google" (Google Account OAuth) no longer works for the Gemini CLI after Google's transition of the Gemini CLI to the Antigravity CLI. API key (GEMINI_API_KEY) and Vertex AI authentication still work, so use one of those for the Gemini backend, or use the Antigravity (agy) backend instead.

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 that is permitted for your account, plan, and usage pattern.

Usage

Launch Agentty from the repository you want to work in. Project discovery is opt-in: the startup suggestion defaults to Skip, and the Projects tab supports adding a repository by path (a) or scanning a chosen folder (d).

agentty              # Launch with auto-update enabled (default)
agentty --no-update  # Launch without automatic updates
agentty --otlp-endpoint http://localhost:4318/v1/traces  # Export session traces
agentty --experimental-harness  # Offer preview Harness sessions
agentty --experimental-multi-agent  # Enable the /plan orchestrated chat
agentty --help       # Show supported command-line options
agentty --version    # Show the installed Agentty version

Start with agentty --experimental-multi-agent to enable /plan. Use it in a session with a prepared worktree, including a new Regular session, to turn the chat into a Plan then implement conversation. Answer or revise the read-only Planner proposal in the composer, then approve it in your own words to run the Implementer; follow-ups go to the Implementer.

--experimental-harness adds a preview Harness session type that runs Agentty's built-in agent loop against a free local model, such as one a running Ollama serves, or against paid Muse, Kimi, or Qwen using MODEL_API_KEY, KIMI_API_KEY with KIMI_BASE_URL, or DASHSCOPE_API_KEY with DASHSCOPE_BASE_URL, or OpenAI's GPT models with a paid OPENAI_API_KEY or on your ChatGPT Plus or Pro plan after ag-harness login chatgpt. Its /model picker lists local models first, marks each model free, plan, or paid with a cheap, standard, or premium price class, and remembers your choice for new Harness sessions. A project's Default Fast Model can be a cheap harness model, such as qwen3.8-flash, for commit messages and titles. Its edit mode runs unsandboxed shell commands. See Harness sessions.

Session tracing is disabled unless --otlp-endpoint supplies a complete OTLP HTTP/protobuf traces URL. Authentication headers can come from OTEL_EXPORTER_OTLP_TRACES_HEADERS or OTEL_EXPORTER_OTLP_HEADERS. Traces contain step timings, tool identities, available executable names, exit codes, and output sizes. Add --otlp-capture-content to include tool commands, arguments, and results as previews of at most 4 KiB each. Common credential markers suppress the entire affected preview; arbitrary secrets may still appear. Prompts and reasoning are excluded. See the session tracing documentation for provider limitations. A traces URL ending in /v1/traces also sends the usage events below as OTLP log records to the sibling /v1/logs URL, even when PostHog telemetry is disabled.

Only one Agentty instance can use a given Agentty root at a time. Close the running instance before launching another. Separate AGENTTY_ROOT directories can run independently.

Telemetry is enabled by default: release builds send events to the Agentty PostHog project. Set AGENTTY_TELEMETRY_ENABLED=0 to disable it. See the telemetry details for the exact events and fields.

Documentation

The programmatic session API supports creating and listing tasks before execution, submitting attempts, and explicitly accepting outcomes. See the task contract for session ownership, concurrency, and current limits.

It also supports explicit static execution graphs with isolated task conversations, exact output acceptance, and shared execution limits. See execution graphs for supported profiles and lifecycle limits.

Documentation for installation and workflows is available at agentty.xyz/docs.

[!WARNING]

Agentty is in active development. While releases follow Semantic Versioning, the current 0.y.z series may still introduce breaking changes between releases as workflows, integrations, and safeguards evolve. Always review and verify the changes Agentty proposes or applies in your repositories before you rely on them.

Contributing

See CONTRIBUTING.md for contribution guidance.

License

Apache-2.0