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
| Ask | What 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:
- Needs you: the agent stops on that point until you answer. The question shows as an amber card, and the session’s dot turns amber.
- Assuming: the agent goes on with a default it names. The question shows as one muted line: “assuming” and the default. If the default is fine, do nothing. To pick something else, select Change ▾.
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:
- Only a session you work with directly asks you. A workflow worker asks its lead instead.
- Questions show on the desktop only, not on the phone.
- A decision card (see Show) is a one-off panel; an open question stays until settled.
- These are not the questions an agent pins to lines in a review. Those are threads in the Review Room (see Review).
Settings changes
An agent can read your settings and propose a change. Nothing changes until you approve.
| Ask | What 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.
- An agent never sets a key. When a change needs one, such as a decision model’s API key, enter it on the card or select Use key from file….
- Each session has at most one open proposal; a newer one replaces it.
- If the setting changed after the proposal, Approve applies nothing and the agent is told.
- Only a session you work with directly can propose. Workflow workers and the Review Room Companion can’t.
- You approve on the desktop. The phone only shows that a change is waiting for you there.
- Some settings are never open to agents, such as remote access and workflows.
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
| Ask | What 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.
| Ask | What 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
| Ask | What 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.
| Ask | What 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.
| Ask | What 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
| Ask | What 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
| Ask | What 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:
- post, approve or merge anything on GitHub through SimpleEdit
- start a backlog item
- change a SimpleEdit setting without your Approve
- start a workflow, unless you turn on Leads may start workflows in Settings → Workflows
- pass a review gate
- take over your screen: sessions and reviews an agent opens arrive in the background
Tips
- Name the result you want, not the tool: “show me”, “ask the other agent”, “save this for later”.
- Use “add this to our backlog” for work that would collide with what is running now.
- Ask for a review when the agent thinks it is done.