Start a session
A session is one conversation with one agent about one project. This guide creates a session from nothing.
1. Create the session
- Select New session in the sidebar.
- Pick the project folder. This folder is the project: the agent works inside it, and your machine runs the agent.
- Name the session, or let Admiral name it.
The session belongs to that project and to that device. See Projects and sessions.
2. Choose the repository and branch
The composer pickers set where the work happens:
- Repository. Pick a local folder, clone a repository, or create a new one.
- Branch. Pick the branch the agent works on.
- Worktree toggle. Turn it on to put the agent's work in a separate copy of the repository. Your own working files stay untouched. Use a worktree when you want to keep working while the agent works.
3. Choose the agent and model
The agent picker lists the agents enabled on this machine. OpenCode is the default. Claude Code and Gemini are native options. See Agents and models for how they differ.
4. Send the task
Write the task like you would write it for a new team member:
- State the goal, not just the step.
- Point at the files or behavior involved.
- Say what done looks like.
Example:
Add rate limiting to the login endpoint. Keep it under 5 requests per minute per IP. Return a 429 with a JSON body. Add a test.
Select Send. The transcript starts filling, and the session status turns blue while the agent runs.
5. Follow up
The agent works until it finishes or it needs you. When it needs you, the status turns amber. Answer in the composer; your message joins the same session.
Next steps
- Steer and queue: what Send, Queue, and Stop each do.
- Review changes: check the work when the status turns green.