Sessions

A session represents a continuous working context inside a project. It combines conversation history, execution state, file changes, and command output into a single traceable unit.

Sessions are automatically created when you start working on a task or initiate a new chat inside a project.

What a Session Is

A session is an isolated working environment tied to:

• a specific project
• a specific repository clone
• a specific working branch
• its own conversation and execution history

Each session operates independently from other sessions in the same project.

Sessions are not temporary chat windows. They are persistent work environments that retain history and state.

Automatic Session Creation

A session is created automatically when:

• you start a new task
• you begin a new chat inside a project
• you initiate work from a suggested AI-generated task

You can also manually create a new session at any time.

Every session starts from the current project state and derives its own working branch.

What a Session Contains

A session records and preserves:

• user prompts and instructions
• agent responses
• reasoning traces
• file reads and modifications
• diffs and proposed changes
• terminal command execution results
• references to the indexed repository context

All of this remains accessible within that session.

If you return later, the full conversational and execution history is still available.

Sessions and Repository State

Each session operates on its own working branch derived from the project’s main branch.

This enables:

• safe experimentation
• parallel feature development
• isolated debugging
• independent implementation attempts

Changes made in one session do not affect other sessions unless explicitly merged through your repository workflow.

Working Across Multiple Sessions

A single project can contain multiple sessions simultaneously.

Each session:

• maintains its own branch
• maintains its own history
• maintains its own execution logs
• does not overwrite other sessions

You can switch between sessions without merging state.

This allows multiple streams of work to coexist safely.

Common Use Cases

Implementing a New Feature

Start a session to build a new feature.

Inside that session you can:

• discuss design decisions
• modify multiple files
• run build commands
• iterate on implementation
• generate a pull request

All related work remains grouped and traceable.

Debugging an Issue

Use a dedicated session when debugging.

You can:

• run diagnostic commands
• insert temporary logging
• test alternative fixes
• revert changes safely

This keeps debugging isolated from feature work.

Trying Alternative Approaches

If you want to test different implementations:

• create separate sessions
• explore each approach independently
• compare results
• promote the preferred implementation

Each session maintains its own execution trail.

Exploration and Analysis

Sessions are not limited to code changes.

You can use a session to:

• understand architecture
• map dependencies
• analyze performance bottlenecks
• generate documentation
• explain system behavior

Even if no code is changed, the reasoning history remains preserved.

Sessions, Tasks, and Trials

Sessions exist within a broader execution structure.

• A Task defines the objective (for example: “Add E2E tests”).
• A Trial represents a structured attempt to complete that task.
• A Session captures the live interaction and execution inside that trial.

When working under a defined task, sessions are typically created within a trial.

However, sessions can also exist independently for exploratory or ad hoc work.

This separation allows:

• multiple sessions under a single task
• multiple trials for different solution paths
• clear distinction between intent and execution

Persistence and History

Sessions retain:

• full conversation history
• command output logs
• file modification traces
• branch context

They do not automatically reset or discard past information.

Returning to a session restores its working context.

Execution Scope

All execution within a session:

• runs inside the project’s sandboxed workspace
• respects deployment-time configuration
• uses defined environment variables
• follows repository review and merge workflows

Sessions do not automatically merge changes into the main branch.

All updates follow the configured approval process.

When to Start a New Session

Create a new session when:

• the scope of work changes
• you want a clean execution history
• you are testing a different implementation strategy
• you want to isolate experimental work
• you are switching from feature development to debugging

Keeping sessions scoped improves clarity, reviewability, and traceability.