Sessions
A session is one coding agent working in a project's folder. The agent is Claude Code, Codex, Antigravity or OpenCode, running in a terminal inside Clauge. You can run any number of sessions at the same time, and each one has a purpose, its own branch and, if you want, a ticket.
Before you start
- Install the agent. Clauge runs the agent's own command-line tool, and you sign in to it with your own account. If an agent shows Not installed in the New session dialog, select it, run one of the install commands shown, then select Re-check. See Quick Start.
- Link a folder. A session needs a folder on your computer. On a project with no folder, the New menu shows Link folder… in place of New session. See Projects.
Start a session
- Open a project and choose New session. The button is on the project overview page, in the New menu and in the project's right-click menu.
- If the dialog was not opened from a project, pick the project in the list on the left.
- Under Agent, pick the agent. Agents your organization's policy does not allow are disabled.
- Enter a Session Title.
- Optional: under Ticket, search by key or title and pick the ticket this session is for. If the title is empty, it is filled from the ticket.
- Pick a Purpose.
- If you picked Custom, write the System Prompt (optional).
- Optional: if Resume Existing Session appears, pick an earlier conversation for this folder, or leave it on Start fresh.
- Select Create session.
The session opens in a tab in Workspace and appears under the project in the tree.
Branches
The Folder field in the dialog shows the project's linked folder and what the session will do with it:
- Git repository: the session works on its own branch, isolated from your files. Two sessions on the same project do not share a branch.
- Not a git repository: the agent edits the folder directly, with no separate branch. If another session already works in that folder, the dialog warns that the two can overwrite each other's changes.
Purposes
The purpose sets the instructions the agent starts with.
| Purpose | Instructions given to the agent |
|---|---|
| Brainstorming | Ask questions, compare two or three approaches with trade-offs, and write no implementation code unless you ask |
| Development | Read the existing code first, make small focused changes, and verify each one |
| Code Review | Read all recent changes, check for bugs, security, performance and edge cases, and cite files and lines |
| PR Review | Ask for the branch and base branch, review only the diff between them, and give a verdict |
| Debugging | Reproduce, find the root cause before proposing a fix, then make the minimal change |
| Custom | Your own system prompt |
Advanced options
The Advanced tab of the dialog has four switches, all off by default.
| Option | What it does |
|---|---|
| Skip permissions | Auto-approves all tool calls without confirmation |
| Git identity | Overrides the git author Name and Email for this session |
| Custom binary path | Uses a specific agent binary for this session instead of the one on $PATH |
| Attach contexts | Adds saved context snippets to the agent's instructions each time it starts. See Contexts & plugins |
Work in a session
The session tab is the agent's terminal. Type to the agent as you would in your own terminal. You can drop a file on the terminal to insert its path into the prompt.
The side panel has three tabs:
| Tab | Use |
|---|---|
| Files | Browse and open files in the session's folder |
| Git | See changes, stage them, Commit, push, sync and Create PR |
| Shell | A plain shell in the session's folder |
Each session shows its state in the tree and on the overview pages:
| State | Meaning |
|---|---|
| working | The agent is running |
| Needs your input | The agent is waiting for an answer from you |
| idle | Nothing is running |
Edit, reset or delete a session
Right-click a session in the tree:
| Item | What it does |
|---|---|
| Open | Opens the session tab |
| Edit | Changes the title, purpose, system prompt and advanced options |
| Reset session | Clears the agent's conversation and starts fresh in the same session |
| Copy branch | Copies the session's branch name |
| Delete session | Deletes the session after you confirm |
Group sessions
A group session works across all the projects of a group instead of one. Each repository the agent needs is copied into the session on its own branch, isolated from your files.
To start one, open the group's overview page and choose New session in the Sessions section. This is available only if your organization's policy allows group sessions.
Related pages
- Board: the tickets a session can be attached to
- Coworkers: named agent profiles for tickets, reviews and automations
- Development standards: the AI-DLC rules that apply in organization groups