AI assistant¶

An in-editor assistant that drives the AI command-line agent you already have installed — explain, refactor, fix, write tests, summarize, translate, and chat, with every proposed edit shown as a reviewable diff you apply on purpose.

Bring your own agent¶

The assistant does not ask you for an API key and does not sign you into anything. Instead it runs a locally installed AI CLI agent as a helper and streams its output into the editor. Authentication, your subscription, and model choice all belong to that tool.

Today: Claude Code (claude) and Codex CLI (codex). Install one and log in once (so claude or codex works from a terminal); the editor picks it up automatically. Gemini is offered too, but its command-line integration is not yet verified.
Detection is automatic and non-blocking. The editor probes for the agent in the background right after startup — the window never waits for it. While the probe runs, View → AI Chat is briefly disabled with a Detecting AI engine… tooltip; a few seconds later it either enables (agent found) or stays greyed out with a hint telling you what to install.

The agent is a separate program you install

The editor does not bundle or download any AI agent, and it does not send your text anywhere itself — the CLI agent you installed makes the request using its own account and network connection. If the agent isn't installed or logged in, the AI features simply stay disabled and nothing else in the editor is affected.

Requirements¶

The assistant has one hard requirement: a supported AI CLI agent installed and logged in on your system PATH.

Install a supported agent. Today that is Claude Code (claude) or Codex CLI (codex).
Log in once. Run the agent from a terminal and complete its own sign-in, so it works headlessly afterwards. The editor never asks for or stores an API key — your subscription and login live entirely in that tool.
Make sure it's on your PATH. If the editor can't run it, View → AI Chat is greyed out with an explanatory tooltip.

The AI Chat panel¶

There is no top-level AI menu — everything lives in one bottom panel, toggled from View → AI Chat. If the panel was open when you last closed the editor, it reopens on the next start (once the engine is detected).

From top to bottom the panel shows:

an Engine dropdown (your choice is remembered between sessions) and the Allow file edits checkbox (see below);
a status line — the detected engine and version, a probe/progress note, or the "install and log in" hint. After the first answer it also names the model the agent actually used, e.g. Engine: Claude (2.1.200) · claude-sonnet-5 — worth a glance, since the model decides what the run costs you (see Choosing the model);
a thin busy bar with a Stop button while the agent is working;
the console — the whole conversation in one view;
a hint line listing the available commands as clickable links.

The console¶

The conversation works like a terminal: history above, and you type at the end, after the › prompt.

Enter sends; Shift+Enter inserts a line break, so multi-line prompts work.
Clicking or typing anywhere in the history moves the caret back to the prompt — history is selectable and copyable but never editable.
Esc cancels the running request; when nothing is running it clears whatever you typed after ›. Esc works with focus anywhere in the panel.
Ctrl+A selects only the question you are composing, so what you type next replaces it; with nothing typed it selects the whole transcript instead, ready to copy.
Up and Down recall what you asked before, the way a shell does. Up on the first line of what you are typing steps back through your earlier questions; Down walks forward again, and stepping past the newest one hands back the half-typed line you started from. Inside a multi-line prompt they simply move between its lines, and once you edit a recalled question it becomes your new draft. The history is per panel and is not kept between sessions.
While an answer streams in, the view follows along if you are at the bottom; scroll up to read and it stays put. When the answer is complete the view places it deliberately: a short answer scrolls to the bottom so you see it and the prompt below it, while a long one lines its Assistant heading up with the top of the panel so you can read from the start.
Each answer's Markdown is rendered on its own, so numbered lists start at 1 every time instead of continuing the previous answer's numbering.

Commands¶

Type a command at the prompt, or click it in the hint line (commands that take an argument get a trailing space and wait for you to finish the line):

Command	What it does	Result
`.explain`	Explain the selected code	answer in the chat
`.summarize`	Summarize the selected text	answer in the chat
`.refactor <how>`	Refactor as instructed (e.g. `.refactor extract a helper`)	reviewable edit
`.fix`	Fix the selected code	reviewable edit
`.tests`	Write unit tests for the selection	reviewable edit
`.translate <language>`	Translate the selection (e.g. `.translate German`)	reviewable edit
`.model <id>`	Pin the model this editor asks for (see Choosing the model)	answered instantly, no agent run

Anything else you type is handled naturally:

Plain text is a free-form question to the agent, sent together with what you have on screen (see below).
A line starting with / is one of the agent's own commands (like Claude's /help) and is forwarded exactly as typed — nothing of the editor's is added to it, and no consent is needed because nothing of yours is sent. This applies to engines whose command set has been verified — today Claude; on the others a / line is treated as an ordinary question.
An unrecognised .word is not an error; it's sent through as a prompt.

Not every CLI command means the same thing here as it does in the agent's own terminal: some need an interactive session the editor's runs don't have, some concern conversations the editor already manages itself, and some — like /model — simply cannot outlive a single request. When you send one of those, the editor forwards it anyway and adds a short note saying why it may not do what you expect. You'll see each note once per session.

The agent's own /model cannot stick — use .model

Every question runs the agent afresh, and a fresh run always starts from the model your CLI is configured to use. /model … answers "Set model to … for this session only", but that session is over the moment the answer is: the next question — even one continuing the same conversation — is back on the configured model. Use .model <id> instead; it is the editor's own command and pins the model for every later question. See Choosing the model.

Matching is case-insensitive, and the hint line narrows as you type (.r → .refactor …).

Selection or whole document¶

Commands work on the current selection. With no selection, they operate on the whole document — and because that sends the entire file to the agent, the editor asks first: Send whole document '…' to Claude? You are asked once per document per editor session; declining aborts the send and keeps what you typed. The question can be switched off in Preferences → AI Assistant, with the option Ask before sending a whole document to the AI engine; with it off, the whole document is sent without asking.

What the assistant knows about your document¶

The agent reads files from disk. Left to itself it would therefore answer questions about a file you have edited but not saved from the old text, and would not see an untitled buffer at all. So a free-form question tells it what you actually have open:

Saved with no unsaved changes — the assistant simply names the file and lets the agent read it. Nothing leaves the editor, so nothing is asked.
Unsaved changes, or a document never saved — the current text is sent along with your question. Small documents travel in the question itself; larger ones are written to a temporary copy the agent is pointed at. The copy is deleted as soon as the exchange ends.
With a folder open — every other open document with unsaved changes is included the same way, so the agent sees the project as you see it rather than as it was last saved.

Because that sends text out, the editor asks first — once per document per editor session, and once for the whole request even when several documents are involved: The current, unsaved content of these documents will be sent to Claude: …. Continue? Declining abandons the request and keeps what you typed.

A selection still takes precedence as the thing you are pointing at: it is sent as Relevant selection alongside the document, not instead of it.

In the default read-only mode the agent is also told it cannot change your document, and that a change should be suggested through the .refactor, .fix, .tests and .translate commands — which do show you a diff.

Reviewing and applying edits¶

Edit commands never rewrite your text silently. When the agent finishes, a review dialog opens with one checkable, colourised change group per modification — removed lines in red, added lines in green:

untick the changes you don't want;
Apply replaces the selection (or the whole document, for the no-selection case) with just the accepted changes;
Discard leaves the buffer exactly as it was.

Applied changes are ordinary edits, so Ctrl+Z undoes them like anything else. Your file's line-ending style (CRLF/LF) is preserved. If the agent declines to make an edit, its explanation appears as a normal chat answer instead of a bogus diff.

If you kept editing while the agent worked, the editor never splices a stale change over your newer text. What it does instead depends on what it can still tell for certain:

your typing moved the target but left it intact → the change is applied where the text is now;
the command covered the whole document and the document has since changed → the proposal is compared against your current text and you review that diff, so the answer isn't wasted;
the original text is gone, or now appears several times over → the editor declines rather than guess, and tells you to run the command again.

The diff colours follow your colour theme: themes may define dedicated Diff added text / Diff removed text colours (editable in Preferences → Syntax Colouring → Themes), and without them the editor picks readable defaults for light and dark interfaces.

Conversations¶

Free-form questions form a continuing conversation: the agent remembers your previous questions and answers. There is one conversation per opened folder (or per file, when no folder is open), so unrelated projects don't share context. Edit commands (.refactor, .fix, …) intentionally run one-shot and don't pollute the chat context. Conversations are not persisted — restarting the editor starts fresh ones.

Claude and Codex both continue conversations. Codex names each conversation itself and announces the name when it starts; later questions pick it up from there. If a run of Codex finishes without announcing one, the chat says [conversation could not be continued — the engine announced no session id; the next message starts a new one] — the answer you got stands, but your next question starts a new conversation without the earlier context.

A conversation also survives the things that go wrong. Stopping an answer keeps it, so a question you interrupted can simply be picked up again — ask "carry on with the last task" and the agent still knows what it was doing, even if you stopped it before it said a word. A one-off failure (a rate limit, a dropped connection) doesn't throw the history away either; only a second failure in a row starts a fresh conversation.

Stopping a run¶

While the agent works, a busy bar appears with a Stop button — click it (or press Esc anywhere in the panel) to cancel. Whatever had streamed so far stays in the transcript, the run is marked [Cancelled], and no edit is applied. The conversation is kept, so your next question continues it (see Conversations). Pressing Enter mid-run doesn't queue anything; the status line reminds you the agent is still working.

Letting the agent edit files¶

By default the assistant is read-only: every run launches the agent with its file-editing tools, shell access, and sub-agents disabled, so changes reach you only as reviewable proposals. For engines with verified permission flags this is a hard block enforced by the agent itself, no matter how your CLI is configured:

Claude runs with its file-editing tools, shell access and sub-agents switched off.
Codex runs in its read-only sandbox (-s read-only). The sandbox works differently: it does not switch shell commands off, it confines them — Codex may still run commands to look around, but they cannot write. For now the editor also asks Codex in so many words to stay read-only.

Read-only is not guaranteed for every engine

The hard block relies on the engine's own permission flags. Gemini has no verified flags yet, so the editor can only ask it — as a best-effort instruction — to stay read-only; it cannot force it. Treat read-only as not guaranteed for Gemini: it may still write to disk, and its behaviour is ultimately governed by your CLI's own configuration. Keep such work in a version-controlled folder if that matters to you.

The Allow file edits checkbox (next to the engine dropdown, off by default, remembered between sessions) opts into agent-side editing:

the agent's file edits are auto-accepted and it may modify files in the opened folder during a run;
every write is reported in the conversation as [the agent modified a file: …], and open documents pick the changes up through the editor's normal file watching;
when the run ends, a single summary line lists the full set of touched files with a count, e.g. [modified files (3): …];
Claude's shell access and sub-agents stay blocked even with the option on.

With Codex the option switches its sandbox to -s workspace-write: Codex may then edit files, and run shell commands, within the opened folder and the temporary directory. Codex does not report its edits to the editor, so the chat does not list the files it changed and there is no summary line; open documents still pick the changes up through file watching. The writes themselves are carried out by Codex's own sandbox: if Codex answers that it could not start its command runner, that sandbox is not working on your machine — check its own diagnostics (codex doctor), not the editor.

The same switch is also on Preferences → AI Assistant, as Allow the AI engine to edit files. They are one setting, not two: applying it in Preferences ticks or unticks the panel's checkbox at once, and whatever you set in the panel is what Preferences shows the next time you open it.

Documents with unsaved changes are handled for you. The agent must not edit the file on disk for a document you have changed but not saved — that copy is out of date, and writing to it would leave the file and your editor disagreeing. So the agent is given the temporary copy of your current text to edit instead, and when the run ends the editor brings the result back into your open document as an ordinary, undoable edit. Untitled documents work the same way, even though they have no file at all. If you happened to edit the document yourself while the agent was working, the editor does not overwrite you: it opens the usual review dialog against your current text so you decide change by change. Closing the document during the run simply discards the agent's work, with a note in the conversation.

Allow file edits can overwrite or delete your work

With the option enabled the agent writes to disk directly and those writes are auto-accepted — there is no per-change review dialog. The agent can overwrite, delete, or corrupt files in the opened folder, and edits to files you don't have open aren't shown to you as diffs. Only enable this for a folder under version control (Git, SVN, …): commit or stash your work first, then use the VCS diff to inspect every change and revert anything unwanted — treat version control as your undo for agent edits. Gemini, whose permission flags are not yet verified, ignores this option entirely, so its edits are governed solely by your CLI's own configuration.

Switching engines¶

At start-up the editor looks for every engine it knows, and the Engine dropdown lists only the ones installed on this machine. If the engine you chose last time is no longer there, the first installed one takes its place automatically. An engine you install while the editor is running appears after a restart. With no engine installed at all the dropdown lists every engine the editor knows, and the panel stays greyed out with the install-and-log-in hint.

Pick a different agent from the Engine dropdown at any time (it's disabled while a run is active). Switching cancels detection of the previous engine, probes the new one in the background, and starts fresh conversations — a chat begun with one engine can't be continued by another. It also clears the transcript, since that conversation belonged to the other engine; whatever you had typed at the prompt is kept.

Choosing the model¶

By default the editor doesn't ask for a model, so each run uses whatever your CLI agent is configured to use — for Claude Code that is the model in your personal ~/.claude/settings.json. That is often not what you want for the editor: it is a global preference, it can change without you noticing, and the model decides what each request costs.

The status line tells you what was actually used, so you can always check. To pin a model for the editor itself, type it in the chat:

You type	What happens
`.model claude-sonnet-5`	every later question asks for that model
`.model`	reports the pinned model and the model last actually used
`.model default`	drops the pin; the agent's own default applies again

.model is handled by the editor — it never launches the agent, so it answers instantly and costs nothing. A pin takes effect from your next question, and the status line confirms it once the answer arrives.

The same thing can be set by hand, per engine, in OctoEdit's settings file:

Key	Value	Effect
`ai/model/<engine>`	a model id, e.g. `claude-sonnet-5`	every run uses that model
`ai/model/<engine>`	empty / absent (default)	the CLI agent's own default

<engine> is the engine's id as shown in the dropdown, lower-cased — e.g. ai/model/claude or ai/model/codex. Restart the panel's next request for it to take effect, then confirm it in the status line. Gemini, whose model flag is not yet verified, ignores the setting.

Related advanced setting

ai/programPath/<engine> does the same job for the binary: set it to an absolute path when the agent is installed somewhere the editor's PATH search can't see it. Both keys are deliberately file-only escape hatches — a wrong value fails loudly rather than being silently ignored.

When a run fails¶

If the agent exits with an error, the chat shows [agent exited with code N followed by the agent's own error lines and a closing ] — for Codex, its start-up banner and its ERROR: … lines, such as the 401 Unauthorized you get when you are not logged in. That is usually enough to tell what went wrong; running the agent once from a terminal tells you the rest.

The editor's log (mte.log, see Logging & diagnostics) records each run in lines starting with AI: — which engines were found, the program and arguments of every run, its exit code, and the agent's last error lines when a run fails; starting the editor with --log=debug adds the rest of the agent's diagnostic output. Your question and the answer are never shown in the error message and never written to the log: the log gives only the question's size in bytes.

Privacy and cost¶

Requests are sent by the CLI agent you chose, using its own account and network connection — the editor adds no separate telemetry or endpoints. (Codex repeats the whole exchange in its diagnostic output; the editor drops that copy and never writes it to its log.) What is sent (your instruction, your selection or document, and the unsaved text of open documents when a question needs it) and what it costs are governed by that agent's subscription or plan. Nothing leaves the editor without the consent prompt described above, and the status line names the model each request actually used.

What ships today

Commands work on the current selection (or whole document, with consent) and, when accepted, replace it. There are two authority levels: the read-only propose-only flow above, or the explicit Allow file edits opt-in. There is no separate in-editor review of the agent's own on-disk edits — with Allow file edits on, rely on your version control instead; the one exception is a document open with unsaved changes, whose edits come back through the editor.