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 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 and the bare repository
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.
All worktrees share one 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 folder myproject with the bare repository myproject.git and a worktree main inside it. New worktrees go into the same folder.
You already have a clone? SimpleEdit doesn’t convert or move it. Clone the project again with Checkout Repository… into another Destination. SimpleEdit refuses a destination where a folder of that name already exists. Your old clone stays as it is. Push or move any work you still need from it, then delete it when you no longer use 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 you add to the allowlist in Settings → Models show here too, as New session · followed by the model name.
- 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. 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 lists their models, and the local models of Ollama when it runs. Pick the default in Settings → Default Model.