Getting started
This guide shows how to open a project, start an agent session and talk to the agent about code.
Before you start
Install and sign in to at least one agent CLI: Claude Code, Codex or OpenCode. SimpleEdit uses your existing login and settings. It does not install an agent for you. See Installing.
1. Open a project
- Start SimpleEdit.
- On the welcome screen, select Open Repository… to open a repository you already have, a plain clone or a bare repository, or Checkout Repository… to clone one.
- When you clone, enter the Repository URL and a Destination, then select Clone. SimpleEdit creates a bare repository and a main worktree.
Worktrees
SimpleEdit works best with one worktree per topic. A worktree is a checkout of the repository on its own branch, in its own folder. Each agent then works on its own branch, and two agents never change each other’s files.
SimpleEdit works with either layout:
- A plain clone, the kind
git clonemakes. The clone is your main checkout. Worktrees that SimpleEdit creates go to~/.simpleedit/worktrees/, outside the repository, so nothing needs gitignoring. Worktrees you or an agent made elsewhere show up too. - A bare repository, the git data without a checkout of its own. When you clone with Checkout Repository…, SimpleEdit sets this up for you. For a repository called
myproject, it creates a foldermyprojectwith the bare repositorymyproject.gitand a worktreemaininside it. New worktrees go into the same folder.
You already have a clone? Open it with Open Repository…. SimpleEdit doesn’t convert or move it.
See Working with worktrees for how to create and switch worktrees.
2. Start a session
A session is one agent (or one terminal) plus its own workspace: editor tabs and git log.
- In the sidebar, select ✦ Agent (or press ⌘T). The default provider starts.
- To pick a provider, right-click ✦ Agent and select the provider’s entry, for example New Codex session · configured default. Models in your quick picker in Settings → Models show here too, in the picker’s order, as New session · followed by the model name. A model you add goes to the top.
- Select + Term for a plain terminal.
The agent runs in its own terminal UI, as it does outside SimpleEdit. Type your prompt there.
The dot next to a session shows its state:
| Dot | Meaning |
|---|---|
| Pulsing grey | The agent is working. |
| Amber | The agent needs you. |
| Grey | The agent is idle. |
| Bright | Something new you have not seen yet. |
| Red | An error. |
3. Comment on code with Threads
A thread is a conversation with the session’s agent, anchored to lines of code.
- Open a file in the session’s editor.
- Select the + next to a line. Or select several lines and press ⌘⇧M.
- Type your comment and press Enter.
SimpleEdit sends the comment when the agent is idle and its prompt is empty. It never types into a running turn. The agent answers in the thread. All threads are in the right column, on the Agent threads tab.
4. Manage sessions
Right-click a session in the sidebar:
- Fork: start a copy of the conversation. The original stays as it is.
- Hand off…: start a fresh session with a short summary of the current one. Use this when the context gets long.
- New group with…: group related sessions.
- Close session: end it.
Sessions survive a restart. After a restart, select Resume to continue a session.
More to know
- Backlog. Park work that would collide with what is running now. Open Backlog in the sidebar, add an item with a prompt, and select Start when you are ready. A scheduled item reads Run now instead. See Driving SimpleEdit from your agent. Agents can add items too (“add this to our backlog”), but only you start them.
- Usage. A pill in the workspace header shows the tokens the session used. For Claude, it also shows an estimated cost (≈ $).
- Providers and models. SimpleEdit runs Claude Code, Codex and OpenCode. Settings → Models puts your quick picker first. Every other available model, including the local models of Ollama when it runs, is under Add models. Pick the default in Settings → Default Model.