First launch
Before you have a project, Arakun checks the machine for agents and GitHub. Then it walks you through four short steps, next to a small preview of the window that changes as you pick:- The agent new sessions start with.
- Your first project.
- The color scheme and the sidebar layout.
- GitHub, the phone remote and crash reports.
Your first session
1
Add a project
In the project’s folder, run:This adds the project, or switches to it. It starts Arakun if it is not running.Or press Ctrl+O. It searches the git repositories in your home folder. Paste a clone URL or type a GitHub
owner/repo to clone it and add it in one step.2
Start a new session
Press Ctrl+T, or click New session at the top of the sidebar. A composer opens at once.
3
Pick the agent and the model
The menu next to the composer lists the models of the agent in use, its reasoning levels and, where the agent has one, a fast mode switch. The strip of agent icons at the bottom shows the models of another agent; picking one of them switches agent. The chip beside it sets the agent’s mode, such as Plan mode.
4
Write the task
- Enter sends. Shift+Enter adds a line.
- Up on an empty composer recalls earlier prompts.
- Paste or drop images to attach them.
Each session gets its own worktree
When you send the first prompt, Arakun gives the session its own git worktree on a new branch, so agents don’t step on each other. A prompt written in the main checkout, such as on a project’s start screen, starts in a new worktree too.- The new branch starts from origin’s default branch (usually
main), fetched first. Set another Base branch in Settings › Project. - Alt+click on New session asks for the branch first.
- Ctrl+Shift+N makes a new worktree at once. Ctrl+Alt+N asks for the branch and where to start from.
- Before a repository’s first commit there is nothing to branch from, so sessions start in the main checkout.
Find your sessions
On a new install, the sidebar lists every session of every project, under its project. Each row has a mark for its state: a ring while it works,! when it needs you, a cross when it failed, a check when its checks passed and a faint dot when idle.
The title bar holds the sessions you pin to it. Drag a row up to the bar, or press Alt+P with the pointer on the row. Settings › Appearance › Tabs and sessions has three presets: Focused (this layout), Classic (every open tab in one row, projects and worktrees in the sidebar) and Everything.
While the agent works
- Enter queues your next message. Ctrl+Enter stops the turn and sends it now.
- Esc stops the turn.
- A running command shows its time so far, and a subagent how long it has run.
Branch names from the task
A new worktree starts on a random branch name, such asenv/brave-otter. After the first prompt, a small model names the branch after the task, such as fix/terminal-tab-name, and Arakun renames it. The folder keeps its name.
By default the agent you sent the prompt to names it, when that agent is Claude Code (with haiku) or Droid. Other agents leave the name alone. Settings › Branches can pick Claude Code or Droid for every environment, or turn naming off.
To rename the branch yourself before it is pushed, run arakun rename <branch> in the environment.