Documentation

Search documentation

IDE integration

Connect a compatible editor to Orek with the Agent Client Protocol (v1 or the v2 draft), then verify prompts, permissions, and session recovery.

Use an editor as the interface to Orek through the Agent Client Protocol (ACP). A compatible editor starts orek acp in the background and talks to it through standard input and output.

This connection is separate from Orek’s terminal interface. Run orek acp only where your editor’s configuration asks for it; do not type it into Orek’s composer. For terminal use, see Using Orek.

Before you begin

  • Install Orek and configure a model provider.
  • Choose an editor that supports ACP version 1 (the stable version most editors ship) or the version 2 draft.
  • Open the project you want Orek to work on.

Starting, resuming, or prompting a session needs an active license; without one, the editor can still connect and list saved sessions. If the editor reports that a license is required, activate Orek in a terminal (orek license login, orek license activate, or orek license import --code-file signed-license.txt), then try again.

Orek does not listen on a network port, and there are no separate marketplace extensions for VS Code, JetBrains, Cursor, or Zed. Use your editor’s own ACP settings.

Editor configuration

Configure the editor to start Orek with these settings:

Setting Value
Executable orek, or its absolute path
Arguments acp
Working directory The project to open
Transport Standard input/output (stdio), using JSON-RPC

When it connects, the editor asks for the newest ACP version it supports. Orek uses that version if it is 1 or 2, and offers version 2 otherwise. The connection keeps that version until it closes. Orek runs commands and edits files itself, so an editor that insists on running them is not compatible.

Verify the connection

Before asking the editor to change a project:

  1. Start a session and send a read-only prompt, such as “Explain the project using its README.”
  2. Confirm that the answer and tool progress appear in the editor.
  3. Try an action that needs approval. Confirm that the editor shows the request and that declining it stops the action.
  4. Check that you can cancel a prompt and resume a saved session.

Select a model and recover from errors

A new session starts on the first model that applies:

Priority Condition Initial model
1 routing.pinned_model is set The pinned model (or routing.pinned_provider’s default model if that provider cannot serve it)
2 routing.pinned_provider is set That provider’s first model in routing.default_preferred_models, or else its first model in Orek’s catalog
3 Neither pin is set The first catalog model whose provider is configured and available

If the pinned provider is unavailable, or no available provider serves the pinned model, starting or resuming the session fails with an explanation.

  • Session options: The editor offers Model, Reasoning Effort, YOLO mode (approve every permitted action without asking; see Permissions and security), and Dynamic Model Routing.
  • Automatic model selection: With no pinned model, Orek chooses a model for each request, as it does in the terminal. To turn this off, add --no-routing to the arguments (orek acp --no-routing) or switch off Dynamic Model Routing in the editor’s session options.
  • Switching models: The editor’s model list shows auto and every model whose provider is available. Choosing a model uses it for this session only, without changing your saved configuration; choosing auto returns to automatic selection when it is on. Let the current prompt finish, or cancel it, before switching.
  • Resuming sessions: A resumed session keeps its model and uses your current provider credentials. If that model or provider is no longer available, resuming fails with an explanation and the saved session is kept, so you can fix your configuration and try again. Credentials are never saved in session files.
  • Provider errors: The editor shows the provider, model, kind of failure, and HTTP status. If a prompt fails before it changes the conversation, you can send it again.

Approve an action in your editor

When an action needs approval, the editor shows its description and the relevant path or command. Each request names the tool (for example bash) along with a readable title.

Subagents ask the same way, and their requests name the subagent (for example, Allow reader (agent-1) to use bash? with title reader (agent-1) · bash: npm test). A workflow step’s gate appears the same way.

When you allow an action once, Orek runs it on your computer under your execution and approval settings and shows the result in the editor.

Plan mode is not available in editors because they have no plan-approval screen. If exec.default_approval_mode = "plan" is set, an editor session starts in the default approval mode instead and tells the editor.

Subagents that finish later

A prompt ends when the main agent answers, even if subagents it started are still working. A subagent result that arrives before then goes back to the main agent within the same prompt. A result that arrives later waits for your next prompt, and the editor shows that the subagent finished. See When a subagent finishes.

Cancel or close a session

Cancelling a prompt stops it and every subagent the session started. A running saved workflow pauses rather than being cancelled.

Closing the session, or closing the editor, does the same and also stops the session’s background jobs and deletes their logs. A paused workflow stays saved with the session and can be resumed when you reopen it. Stopping work does not undo changes already made to your project.

Cancelling or closing withdraws every pending approval request in that session, including those from subagents and workflow gates. Orek ignores any later reply from the editor.

Use MCP servers from your editor

An editor can pass its own Model Context Protocol (MCP) servers to Orek when it starts or resumes a session:

  • Stdio servers: programs that run on your computer.
  • Streamable HTTP servers: addresses starting with http:// or https://. Local and private-network hosts are allowed.

If the editor passes a server with the same name as one in your Orek configuration, the session uses the editor’s connection but keeps your configured enabled, allowed_tools, timeouts, and permission rules. Arguments, environment, headers, and OAuth credentials are never shared between the two. The editor cannot pass two servers with the same name.

Error messages for failed, timed-out, or disabled servers never show URLs, headers, environment variables, or credentials. Servers from the editor are trusted for that session and never start OAuth sign-in; see MCP servers.

Additional directories

An editor can also give a session extra folders to work in, as absolute paths to existing folders. Orek uses the list the editor sends when it starts or resumes a session; resuming without a list leaves the session with none. To change the folders of an open session, close it and resume it with the new list. Orek reports each saved session’s folders to the editor.

Editor MCP servers when resuming

While Orek keeps running, resuming a session without a server list keeps the servers it had, and a new list replaces them (an empty list removes them). Servers from the editor are never saved to disk, so after Orek restarts the editor must pass them again.

Protocol versions

Orek behaves the same with version 1 and the version 2 draft; only the messages differ. Differences you may notice:

  • To show a saved session’s history again, a version 1 editor loads the session; a version 2 editor does so when it resumes.
  • Version 1 editors that cannot show an on/off switch show Orek’s YOLO mode and Dynamic Model Routing options as an On/Off choice.

Sessions work across versions: a session started from a version 1 editor can be listed, resumed, and deleted from a version 2 editor, and the reverse.

Testing and debugging

Problem What to check
The connection fails at startup Check that the editor supports ACP version 1 or 2. An editor that asks for another version is offered version 2 and may disconnect.
The editor cannot start Orek Check the executable path, arguments, working directory, and provider configuration.
The editor reports unreadable messages If you start Orek through a wrapper script, make sure the script prints nothing else to standard output. Look for errors in standard error or Orek’s log.
A permission prompt never appears Check that the editor supports ACP permission requests.
The editor reports an unknown method The editor used a feature from the other protocol version, such as loading a session on version 2. Update the editor or choose the matching version.
An MCP server from the editor is rejected Check its name, transport, and URL host, and that the editor does not pass two servers with the same name.
An OAuth MCP server cannot connect Add it to your Orek configuration and run orek mcp auth <name> before connecting.
Starting a session or sending a prompt reports that a license is required In a separate terminal, run orek license status, then activate or import your license and try again. You cannot sign in from the editor.

Starting the ACP server

To check that Orek starts, run this in a terminal:

In your shell

orek acp

The process waits silently for messages from an editor; it is not a chat prompt. To try the connection without an editor, use the orek acp-client commands in the CLI reference.

Transport and saved sessions

Orek writes only protocol messages to standard output. Diagnostics go to standard error or the project’s log files.

Editor sessions are saved with your other Orek conversations for the project, so you can list, resume, fork, or export them from the terminal too.

Tool categories

Orek labels each tool with an ACP category so the editor can show what it does:

Category Purpose Example tools
read Read files and workspace information read_file, list_directory, git_inspect, read_mcp_resource
edit Change files write_file, apply_patch, search_replace
delete Delete files delete_file
search Search content grep_files, search_files, code_graph_query, search_project, provider web search
execute Run or stop commands shell, kill_background_process
fetch Fetch external information webfetch, provider page retrieval
think Record plans, task checklists, or memory updates update_plan, write_tasks, memory
other Everything else, including MCP tools and subagent, workflow, and question tools spawn_agent, run_workflow, ask_user_question, mcp__<server>__<tool>

Next steps