Your first session

A session is one working run of an AI coding tool inside a project — from the moment you launch it to the moment you end it. Starting a session is how you tell Operon to begin watching your AI agent. This page walks through the New Session dialog step by step and explains what happens once your session is live.

Start a new session

Open the New Session dialog to configure a run. The left side holds the core inputs — project, directory, tool, and goal — and the right side shows intelligence panels that appear as you fill things in.

1. 1

   Open New Session

   Click New Session from the sidebar or press Cmd+N (Ctrl+N on Windows and Linux). The dialog opens with an empty form.

2. 2

   Pick a project directory

   Choose an existing project or create a new one, then set the local directory for it using the Browse button. This is the folder your AI tool will run inside — typically the root of your git repository. If Operon detects prior sessions for that path, a "Prior context" panel appears so you can carry forward files and unfinished tasks.

3. 3

   Let Operon detect your tool

   Operon scans your machine for installed AI coding tools — Claude Code, Codex, Cursor, Gemini CLI, Copilot, and Aider — and marks which are found. It preselects the first available one. Tools that are not installed are shown but disabled, and there is always a plain Shell option. You can also reveal experimental agents that run inside a shell.

4. 4

   Write a goal

   Describe what you want to accomplish, for example "Refactor the auth module to use JWT." The goal is optional, but writing one helps a lot. As you type, the Prompt Copilot scores your goal from 0 to 100 for quality and, when it can, suggests concrete improvements — like naming the files involved, adding an action verb, or clarifying the expected outcome. A Pre-flight panel also estimates complexity and risk.

5. 5

   Adjust advanced settings (optional)

   Expand the panels on the right to isolate the run in a git worktree, draw a file scope boundary so the agent can only touch certain paths, or link an issue from Linear, GitHub, GitLab, or Jira. These are all optional — skip them for a straightforward run and add them when you want more control.

6. 6

   Launch the session

   Click Launch Session. Operon starts your chosen tool in the selected directory, opens the terminal, and switches you into the new session.

What happens next

Once you launch, the terminal opens with your AI tool already running in your project directory. You interact with the agent exactly as you normally would in a terminal — Operon does not get in the way. What changes is that everything is now being recorded.

• Every prompt you send and every response the agent gives is captured into a trace — a group of activity spanning one prompt to the AI’s final answer.
• Tool calls, file edits, shell commands, sub-agents, and errors are stitched into that trace and into a searchable timeline.
• Tasks the agent works on are extracted into a kanban board so you can see progress at a glance.
• Token usage and cost are tracked per session in real time.

You can switch between the Terminal, Activity, Timeline, Tasks, and other views at any time without interrupting the agent — the terminal stays live in the background. When you are done, ending the session is non-destructive: it stops recording but never deletes your work, and if you used a worktree with uncommitted changes, Operon preserves it.

Where to go from here