All guides

Driving SimpleEdit from your agent

Every agent session in SimpleEdit gets SimpleEdit’s tools, whether it runs Claude Code, Codex or OpenCode. Your agent can use the app, not only print into its terminal. Ask in plain words and it picks the right tool. The groups: Show, Ask, Hand off, Coordinate and Review.

Before you start

Install Node.js: the tools run on the Node.js on your PATH. Nothing else is needed. SimpleEdit adds the tools to each session it starts, and only to that session; your own agent settings stay as they are.

Show

AskWhat happens
”Show me what you changed.”The agent asks for a review in the Review Room: your uncommitted changes, one commit, or the whole branch.
”Switch to the worktree for the parser fix.”Your file tree and git log follow the agent to that worktree.
”Summarize the test run.”The agent shows a panel: a summary, a file list or a short code excerpt.
”Let me pick between the two options.”The agent shows a decision card: the question and one button per option. Your pick goes back to the agent.
”Sketch three layouts for the settings page.”The agent opens an HTML sketch in your workspace. Comment on any element of it, or pick an option in the page. See Sketching with your agent.

Threads on lines

You comment on lines and the agent answers in the thread (Getting started). The agent can also start a thread itself, for an assumption or risk you should see while you read that code. Ask: “Flag anything you are unsure about on the lines themselves.”

Ask

Open questions from your agent

An agent that needs a decision registers the question with SimpleEdit instead of writing it into its output. It stays above the session’s terminal until settled. You don’t need to ask for this: SimpleEdit tells its agents to ask this way.

A question is one of two kinds:

To answer, select one of the options, or select Reply… and type your own words. Some questions have more detail under Context.

The session’s row shows a ? chip with the number of open questions; select it to answer without switching sessions. Your answer goes back as a message: an idle agent reads it at once, a busy one when its turn ends. If the session has ended, SimpleEdit keeps the question and asks you to resume first.

A question disappears when you answer it, the agent withdraws it, or you close the session. An assumption also disappears once the agent builds on its default; after that, tell the agent.

Limits:

Settings changes

An agent can read your settings and propose a change. Nothing changes until you approve.

AskWhat happens
”Fold test files in the Review Room by default.”The agent reads your settings and proposes the change. A card shows the proposal above the session’s terminal.
”Which decision model is set up?”The agent reads your settings. It never sees an API key, only whether one is set.

The card, titled Settings change proposed by the session’s name, shows the agent’s summary under The agent’s words, not checked, and the change in SimpleEdit’s own words under What Approve changes. The second part is what you approve.

Select Approve to apply it, or Decline, add a reason if you like, and Send decline. The agent gets the outcome and your reason as a message.

Set up with an agent

Some Settings sections have a Set up with an agent button in their header: Default Model → Model checks, Review queue → Questions and rules, Prompts and Voice (see Talking to your agents). It starts an agent session in your last project window with a prompt for that section; the agent proposes the settings on a card as above. It works only while a project is open.

Hand off

AskWhat happens
”Start a new Codex session to write the migration.”A new session starts with a brief the agent writes. It opens in the background, so your view stays where it is.
”Hand this off to a fresh session.”A new session continues with a short summary instead of the full history.
”Add the docs update to our backlog.”The agent adds an item to the project’s backlog, with a prompt and optionally a provider and model. It keeps working on its own task.

Agents can add, change and reorder backlog items. They cannot start one: you decide when work runs.

Scheduled backlog items

A backlog item can run on a schedule: every 1, 2, 4, 8 or 12 hours, daily or weekly at a time you set, under Schedule in the item’s detail. Each time, SimpleEdit starts a new session with the item’s prompt, and the item stays on the backlog. Run now starts one run right away. The item shows its recent runs.

AskWhat happens
”Add a daily 9:00 item that checks the open Dependabot PRs.”The agent adds the item with that schedule. It stays Paused until you read the prompt and select Unpause.

An item an agent adds or changes always waits like this, so an unattended run only sends a prompt you have seen. Unpause applies to the version you were looking at; if the item changed, SimpleEdit refuses and shows the current one. The phone has Pause, Unpause and Run now too.

Schedules run while SimpleEdit is open and your computer is awake. A run you missed happens once, when it next can. If the previous run is still going, that time is skipped.

Coordinate

Talk to other agents

AskWhat happens
”Ask the session on the API branch which fields it renamed.”The agent finds that session and sends it a message. An idle agent reads it at once; a busy one reads it when its turn ends. The answer comes back to the agent that asked.
”Did the other session reply yet?”The agent checks its inbox.

The other session can run Claude Code, Codex or OpenCode, in any worktree of the project.

Search past sessions

Your agent can search the project’s past Claude Code, Codex and OpenCode sessions and read the messages around a hit.

AskWhat happens
”Search our past sessions for why we dropped the retry queue.”The agent searches every session of the project, in all its worktrees, and reads the conversation around the best hits.
”What did the Codex session say about the migration yesterday?”The agent narrows the search to one provider and a time span.

It is a plain text search, with no model. It covers what you and the agents wrote, not tool output. Secrets such as API keys, tokens and passwords are replaced with [REDACTED] before anything is stored. It stays in this project, and only agents use it: there is no search box in the app.

Consult another model

Your agent can ask another model for a second opinion: a review of its branch, uncommitted changes or a commit, or research on a question. The consulted model reads the code but is told not to change anything. Your agent keeps working; the result arrives as a message.

AskWhat happens
”Consult Codex for a review of this branch before you ask me.”A Codex model reviews the branch. Its findings arrive in your agent’s inbox.
”Have another model research whether this API is deprecated.”The consulted model answers the question, and marks each claim as backed by a primary source, a secondary one, or unverified.

Set the default under Consult model in Settings → Default Model. Without one, ask for a provider by name. A consult doesn’t show in the sidebar. Its token use counts toward your agent’s session and shows in the result. Only a session you work with directly can consult, at most three at a time.

Run a workflow

AskWhat happens
”Turn this plan into a workflow.”The agent becomes the lead and creates a task graph. You read it in the Workflow tab and select Start.
”Make the API task a loop, with Codex as the reviewer.”The task runs as a coder/reviewer loop: a fresh reviewer checks every round until the work is clean or the rounds run out, and then the lead decides.
”Retry the failed task with a clearer brief.” “Add a task for the changelog.”The lead patches the running graph. You see each patch under Show patches (n).

See Running a Workflow.

Review

AskWhat happens
”Ask me to review this PR.” “Ask me to review this branch.”The review opens as a tab in the session’s workspace, and the header shows Review ready. The agent attaches a briefing: what changed, why, the impact, a reading order, its open questions pinned to lines, and the commands it ran as evidence.

Ask the agent a question in a thread and it answers there. When you submit, it reads your verdict and every comment and works on them. It may push back in a thread if it thinks a comment is wrong.

Each thread has a recipient: the Companion (a read-only agent that didn’t write the change; your conversation with it stays private), the Author (the agent that wrote the change, while its session runs; your question reaches it when its current turn ends), or the PR (your comment, sent when you submit). See Reviewing your agent’s work.

What agents cannot do

An agent cannot:

Tips

You:
Add a weekly docs refresh to our backlog, Mondays at 09:00.
Author:
Added. It is paused: you need to read the prompt and unpause it.
Backlog
Added to backlog by “invoicekit”Docs refreshEdit
Docs refreshMon at 09:00 · paused · added by invoicekit
Docs refreshMon at 09:00 · added by invoicekit
UnpausePausedadded by an agent
PauseNext: Mon, 16 Nov, 09:00 · while SimpleEdit is open and the Mac is awake
Backlog promptRefresh the docs for anything that changed in the last week. Open a draft PR with the edits and list what you could not verify.
You read the prompt, then press Unpause.
Unpaused. It runs while SimpleEdit is open.