Session

A Session manages a conversation with an AI model about a code repository.

Sessions provide:

Multi-turn conversations with message history
Tool execution (file reading, code search, etc.)
Progress callbacks for streaming UI updates
Automatic cleanup of git worktrees on close

Example

const session = await connect(repoUrl);
const result = await session.ask("What does this repo do?");
console.log(result.response);
session.close();

Properties

id

readonly id: string

Defined in: src/session.ts:243

Unique identifier for this session

repo

readonly repo: Repo

Defined in: src/session.ts:245

The repository this session is connected to

Methods

ask()

ask(question, options?): Promise<AskResult>

Defined in: src/session.ts:306

Ask a question about the repository.

The model will use available tools to explore the codebase and formulate an answer. Concurrent calls are serialized (queued) to maintain conversation coherence.

Parameters

question

string

The question to ask

options?

AskOptions

Optional settings including progress callback

Returns

Promise<AskResult>

Result containing the response, tool calls made, and usage statistics

Throws

Error if the session has been closed

close()

close(): Promise<void>

Defined in: src/session.ts:347

Close the session and clean up resources.

This removes the git worktree associated with the session. The session cannot be used after closing. Safe to call multiple times.

Returns

Promise<void>

getMessages()

getMessages(): Message[]

Defined in: src/session.ts:326

Get all messages in the conversation history. Includes user messages, assistant responses, and tool results.

Returns

Message[]

replaceMessages()

replaceMessages(messages): void

Defined in: src/session.ts:336

Replace the entire conversation history. Useful for restoring a previous session state.

Parameters

messages

Message[]

The new message history

Returns

void