mirror of
https://github.com/l0ng-ai/openidea.git
synced 2026-11-19 00:10:00 +00:00
The Changes pane beside a task's conversation was fixed at 280 px. Its left edge is now a separator that drags (or moves with ←/→ when focused); the width applies to every task, is remembered across restarts, and always leaves the conversation 240 px (half of a narrower session). In the tool window the Changes view fills the window as before. Co-authored-by: Mr0Bread <55754540+Mr0Bread@users.noreply.github.com>
162 lines
12 KiB
Plaintext
162 lines
12 KiB
Plaintext
---
|
||
title: "Agents"
|
||
description: "Run coding agents such as Claude Code, Codex and Gemini CLI inside the IDE, each task in its own Git worktree or in your checkout."
|
||
---
|
||
|
||
OpenIDEA runs command-line coding agents and gives them a chat interface in the IDE. Each conversation is a **task**. A task can work in a new Git worktree, away from your own changes, or directly in the project. You review what it changed as diffs, answer its permission requests, and keep several tasks running side by side.
|
||
|
||
OpenIDEA does not include a model or an account of its own: it starts the agent you have installed and signed in to, and talks to it over the [Agent Client Protocol](https://agentclientprotocol.com) (ACP).
|
||
|
||
## Supported agents
|
||
|
||
These agents are built in. Install the agent's own CLI and sign in once in a terminal; OpenIDEA finds it on `PATH`.
|
||
|
||
| Agent | Command OpenIDEA starts | Sign in with |
|
||
| -------------- | --------------------------- | --------------------- |
|
||
| Claude Code | `claude` | `claude` |
|
||
| Codex | `codex app-server` | `codex login` |
|
||
| Gemini CLI | `gemini --experimental-acp` | `gemini` |
|
||
| GitHub Copilot | `copilot --acp` | `copilot` |
|
||
| Cursor | `cursor-agent acp` | `cursor-agent login` |
|
||
| OpenCode | `opencode acp` | `opencode auth login` |
|
||
| Qwen Code | `qwen --experimental-acp` | `qwen` |
|
||
| Qoder | `qodercli --acp` | `qodercli login` |
|
||
| Qoder CN | `qoderclicn --acp` | `qoderclicn login` |
|
||
| Kimi CLI | `kimi acp` | `kimi` |
|
||
| Goose | `goose acp` | `goose configure` |
|
||
| Auggie | `auggie --acp` | `auggie login` |
|
||
| Kiro | `kiro-cli acp` | `kiro-cli login` |
|
||
| Mistral Vibe | `vibe-acp` | `vibe` |
|
||
|
||
**Claude Code** and **Codex** are driven through their own protocols (Claude Code's stream-json mode and `codex app-server`). Their ACP adapters (`claude-acp`, `codex-acp`) are no longer listed; tasks that already use them keep working, and an [agent file](#add-a-custom-agent) for either id lists it again. If an agent needs you to sign in, the task tells you which command to run.
|
||
|
||
Agents are unavailable in a project you have not marked as trusted.
|
||
|
||
## Start a task
|
||
|
||
| Action | macOS | Windows / Linux |
|
||
| ------------------ | ----- | ------------------ |
|
||
| **New Agent Task** | `⇧⌘I` | `Ctrl+Alt+Shift+I` |
|
||
|
||
<Steps>
|
||
<Step title="Open the New Agent Task page">
|
||
Press the shortcut, or click **New Agent Task** in the **Agents** tool window (on the right).
|
||
</Step>
|
||
<Step title="Describe the task">
|
||
Type what the agent should do. Type `@` to reference a file, `/` for the agent's slash commands, and paste or attach images (**Attach Image…**) when the agent accepts them.
|
||
</Step>
|
||
<Step title="Choose where it works">
|
||
- **New worktree**: the agent works in a new Git worktree on a branch named `agent/<task>`, created from the base branch you pick. Your checkout is not touched. Worktrees are created next to the project, in a folder named `<project>.worktrees`.
|
||
- **Local checkout**: the agent edits your files directly.
|
||
</Step>
|
||
<Step title="Pick the agent and its settings">
|
||
Choose the agent, and its model, mode and other options when it offers them. Cached models appear immediately; the selected agent's catalog refreshes in the background when it is more than 15 minutes old, without sending a prompt or attaching project MCP servers.
|
||
|
||
After changing the agent CLI or account, open the model picker and choose **Refresh models**. Refreshes share one lookup and have a 30-second cooldown after completion, including failures. Cached choices remain usable while refreshing or after a failure.
|
||
|
||
Available models depend on the installed agent and account. If a selected model is removed, choose another before starting. Refreshing does not change running tasks.
|
||
|
||
</Step>
|
||
<Step title="Send">
|
||
The task opens as an editor tab and starts.
|
||
</Step>
|
||
</Steps>
|
||
|
||
## Work with a task
|
||
|
||
The task tab shows the conversation: your messages, the agent's replies, its reasoning, plans, the tools it runs and the subagents it starts. While the agent works:
|
||
|
||
- Messages you send are queued and delivered when the turn ends (**Queued messages**). **Send now** stops the current turn and sends that message next; queued messages can also be edited or removed.
|
||
- **Stop** ends the current turn.
|
||
- `⌘F` / `Ctrl+F` finds text in the conversation.
|
||
|
||
On your own messages you can **Edit** (the messages after it are replaced; files already changed stay as they are) or **Retract Message**. On replies you can **Copy Markdown**, **Quote Reply**, **Regenerate Response** and **Branch Conversation from Here**, which starts a new task from that point.
|
||
|
||
**Focus Agent Input** defaults to `⌘L` on macOS and `Ctrl+L` on Windows / Linux in every built-in keymap. When focus is inside your writable task conversation, in either an editor tab or the tool window, it returns focus to the message input without changing your draft, caret position or selection—even when pressed repeatedly. It does not send a message or jump through message history.
|
||
|
||
The shortcut does not apply to archived tasks, subagent conversations or the New Task page, and does not take focus from open popups or dialogs. Outside the task conversation, the keys keep their usual editor or terminal behavior. To change or remove the binding, open **Settings › Keymap › Agents › Focus Agent Input**.
|
||
|
||
Right-click a link and choose **Copy Link Address** to copy its URL; **Copy** copies the selected text.
|
||
|
||
### Permissions
|
||
|
||
When an agent wants to run a command or call a tool that needs approval, the task shows the request and is listed as **Needs Input**. Choose one of the options the agent offers, such as **Allow Once**, **Allow for This Session**, **Always Allow**, **Decline**, **Always Decline** or **Decline and Stop**. Many agents also have a mode picker that approves edits or everything automatically; use it with care.
|
||
|
||
Once an agent has run a task, new tasks start in its mode that approves everything (Claude Code's bypass permissions, Codex's Full Access), and command permissions don't apply there. To start them in a mode that asks, set **Settings › Agents › Chat › New tasks start** to **Asking for approval**. Only your own settings choose this, never a project's.
|
||
|
||
### Review the changes
|
||
|
||
Click **Show changes** in the task header to list the files the task changed. Click a file to open a diff between the task's starting point and now. For a worktree task, the changes live on its `agent/…` branch: open a terminal there with **Open in Terminal**, and merge or cherry-pick the branch with the Git tools (see [Version control](/en/guide/vcs)) when you are happy with it.
|
||
|
||
Drag the pane's left edge to resize it. The width applies to every task and is remembered across restarts.
|
||
|
||
### Context from the editor
|
||
|
||
- **Send to Agent** in the editor and Project view context menus adds the selection or the selected files as `@` references to the message you typed last. It has no default shortcut; assign one in **Settings › Keymap**.
|
||
- Referenced files up to 256 KB are embedded in the prompt when the agent accepts embedded files.
|
||
- When the [built-in MCP server](/en/guide/mcp) is on, every task is given OpenIDEA's tools as an MCP server, so the agent can use the IDE's search, symbol lookup, problems, run configurations and more.
|
||
|
||
## The Agents tool window
|
||
|
||
The **Agents** tool window lists the project's tasks by what they need from you: **Needs Input**, **Failed**, usage limit reached, **Running**, **Ready to Review** and **Archived**. Its badge counts tasks that need input or have unread replies.
|
||
|
||
Tasks open in editor tabs by default. **Chat in Tool Window** and **Chat in Editor** switch where conversations open; you can also drag a task into the editor area. A task's context menu has **Open**, **Rename…**, **Open in Terminal**, **Copy to a New Task**, **Pin** / **Unpin**, **Move to Group**, **Archive** / **Unarchive** and **Delete…**. Deleting a worktree task also removes its worktree.
|
||
|
||
Pinned tasks sit above every group. **Move to Group** puts a task in a group of your own, and so does dropping it on a group header; **New Group…** in the tool window's options menu (⋯) creates an empty one, and a group's own menu renames or removes it. Groups and pins are kept per project.
|
||
|
||
Tasks are saved per project and survive restarts. When the agent supports resuming sessions, the conversation continues where it left off on the next message; such an agent is also stopped after five idle minutes and started again when you send the next message.
|
||
|
||
## Manage agents
|
||
|
||
**Settings › Tools › Agents** (also **More Agents…** in the agent picker) has two tabs:
|
||
|
||
- **Built-in**: for each built-in agent, whether its executable was found on `PATH`, a field to point at a **Custom executable**, **Environment variables** for the agent process (written as `NAME=value; OTHER=value`; the values are kept in the OS credential store) and how to sign in. Changes apply to new sessions.
|
||
- **ACP Registry**: agents published in the [ACP Registry](https://agentclientprotocol.com). Search, **Install**, **Update** and **Remove**. Installed agents are kept in OpenIDEA's data directory; downloads are checked against the registry's SHA-256 when it provides one.
|
||
|
||
**Settings › Tools › Agents › Chat** chooses what the task header shows: **Context window usage**, **Time spent on the task**, **Usage limits** (when the agent reports them, such as Claude Code) and **Session cost**.
|
||
|
||
## Add a custom agent
|
||
|
||
Any agent that speaks ACP over stdio can be added with an agent file, `agents/<id>.toml` in OpenIDEA's configuration directory:
|
||
|
||
| OS | Agent files |
|
||
| ------- | -------------------------------------------------------- |
|
||
| macOS | `~/Library/Application Support/ai.l0ng.openidea/agents/` |
|
||
| Windows | `%APPDATA%\ai.l0ng.openidea\agents\` |
|
||
| Linux | `~/.config/ai.l0ng.openidea/agents/` |
|
||
|
||
```toml
|
||
# agents/my-agent.toml
|
||
name = "My Agent"
|
||
command = "/usr/local/bin/my-agent"
|
||
args = ["--acp"]
|
||
|
||
[env]
|
||
MY_AGENT_LOG = "info"
|
||
```
|
||
|
||
<ParamField path="name" type="string">
|
||
Name shown in the agent picker. Defaults to the file name.
|
||
</ParamField>
|
||
<ParamField path="command" type="string" required>
|
||
The executable to start, a path or a name on `PATH`.
|
||
</ParamField>
|
||
<ParamField path="args" type="string[]">
|
||
Arguments that start the agent in ACP mode.
|
||
</ParamField>
|
||
<ParamField path="env" type="table">
|
||
Extra environment variables for the agent process. OpenIDEA moves their values to the OS credential store the next
|
||
time it reads the file, and keeps only the names in it (with empty values). An agent installed from the ACP Registry
|
||
keeps the environment its registry entry sets in the file.
|
||
</ParamField>
|
||
<ParamField path="driver" type="string" default="acp">
|
||
`acp` for an ACP agent. `claude` and `codex` use the Claude Code and Codex protocols instead.
|
||
</ParamField>
|
||
|
||
The file name (without `.toml`) is the agent's id. A file named after a built-in agent (`gemini.toml`, `claude.toml`…) replaces that agent's command; this is what the **Built-in** tab writes when you set a custom executable or environment. Files that fail to parse are skipped and logged.
|
||
|
||
## Limits
|
||
|
||
- Agents run on your machine with your credentials and your subscriptions or API keys; OpenIDEA does not proxy or meter them.
|
||
- A worktree task needs the project to be a Git repository with at least one commit.
|