> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LocalDevin

> What every ACP Devin client provides, cloud or local.

```typescript
class LocalDevin extends AcpClient<LocalSession, LocalSessionOptions, LoadSessionOptions> implements DevinClient<LocalSession, LocalSessionOptions, LoadSessionOptions>
```

## Properties

**capabilities** `AgentCapabilitiesMeta` *required*

The agent's `cognition.ai/*` capability flags (`agentCapabilities._meta`).

**connection** `JsonRpcConnection` *required*

**initialize** `InitializeResult` *required*

The agent's `initialize` response (capabilities, auth methods).

**onAgentRequest** `undefined | AgentRequestHandler` *required*

**Type:** `undefined | AgentRequestHandler`

Answer agent → client requests the SDK does not handle itself (anything
but `session/request_permission`). Without a handler — or when the
handler returns `undefined` — built-in defaults apply (diagnostics report
none) and other methods are declined with `method not found`.

**onExtension** `undefined | (notification: CognitionExtensionNotification) =\> void` *required*

**Type:** `undefined | (notification: CognitionExtensionNotification) => void`

Observe connection-scoped `_cognition.ai/*` notifications — those without
a `sessionId` (or one that matches no tracked session), e.g.
`mcp/serversChanged` and `plugins/changed`. Session-scoped notifications
go to the owning session's `onExtension` instead.

**promptCapabilities** `PromptCapabilities` *required*

Which `session/prompt` content blocks the agent accepts, and the cloud size limits.

**protocolVersion** `number` *required*

The ACP protocol version the agent settled on (`1` or `2`).

## Methods

### \[asyncDispose]\()

```typescript
[asyncDispose](): Promise<void>
```

`await using devin = …` closes the client at scope exit, once the connection has shut down.

#### Returns

`Promise<void>`

### assertNotOpen()

```typescript
assertNotOpen(sessionId: string): void
```

Throw unless no session with this id is open on this client.

#### Parameters

**sessionId** `string` *required*

### attach()

```typescript
attach(sessionId: string, options?: LoadSessionOptions): Promise<LocalSession>
```

Resume an existing session and get just the live session, e.g. to observe
it with `session.events()` or continue it with `session.run()`.

```ts
const session = await devin.attach("devin-xxx");
const outcome = await session.run("And now add tests");
```

#### Parameters

**sessionId** `string` *required*

**options** `LoadSessionOptions`

#### Returns

`Promise<LocalSession>`

### close()

```typescript
close(): void
```

Shut down the connection and the CLI process. In-flight prompts reject.

### connect()

```typescript
connect(streams: RpcStreams, options?: LocalDevinOptions, child?: null | ChildProcess, failure?: Promise<never>): Promise<LocalDevin>
```

Attach to an already-running ACP agent over arbitrary streams. Exposed
for tests and custom transports; most callers want `start`.

#### Parameters

**streams** `RpcStreams` *required*

**options** `LocalDevinOptions`

**child** `null | ChildProcess`

**failure** `Promise\<never\>`

#### Returns

`Promise<LocalDevin>`

### createSession()

```typescript
createSession(options?: LocalSessionOptions): Promise<LocalSession>
```

Create a new local session (one agent conversation rooted at `cwd`).

#### Parameters

**options** `LocalSessionOptions`

#### Returns

`Promise<LocalSession>`

### deleteSession()

```typescript
deleteSession(sessionId: string): Promise<void>
```

Delete a persisted session and its history.

#### Parameters

**sessionId** `string` *required*

#### Returns

`Promise<void>`

### extNotify()

```typescript
extNotify(method: M, params: CognitionRequestParams<M>): void
```

Send a connection-scoped `_cognition.ai/*` notification (no response).

#### Parameters

**method** `M` *required*

**params** `CognitionRequestParams\<M\>` *required*

**Type:** `CognitionRequestParams<M>`

```typescript
extNotify(method: string, params?: unknown): void
```

Send a connection-scoped `_cognition.ai/*` notification (no response).

#### Parameters

**method** `string` *required*

**params** `unknown`

### extRequest()

```typescript
extRequest(method: M, params: CognitionRequestParams<M>): Promise<CognitionRequestResult<M>>
```

Send a connection-scoped `_cognition.ai/*` request. Typed when the method
is in the generated registry (`CognitionAgentResponseMap`); any other
`_cognition.ai/*` method is accepted untyped. For session-scoped methods
prefer `AcpSession.extRequest`, which fills in the session id.

#### Parameters

**method** `M` *required*

**params** `CognitionRequestParams\<M\>` *required*

**Type:** `CognitionRequestParams<M>`

#### Returns

`Promise<CognitionRequestResult<M>>`

```typescript
extRequest(method: string, params?: unknown): Promise<T>
```

Send a connection-scoped `_cognition.ai/*` request. Typed when the method
is in the generated registry (`CognitionAgentResponseMap`); any other
`_cognition.ai/*` method is accepted untyped. For session-scoped methods
prefer `AcpSession.extRequest`, which fills in the session id.

#### Parameters

**method** `string` *required*

**params** `unknown`

#### Returns

`Promise<T>`

### handshake()

```typescript
handshake(connection: JsonRpcConnection, clientCapabilities?: CognitionClientCapabilities, acpVersion?: AcpProtocolVersion): Promise<InitializeResult>
```

Offer the selected version. V2 offers include v1 initialization fields
so v1-only agents can still negotiate v1.

#### Parameters

**connection** `JsonRpcConnection` *required*

**clientCapabilities** `CognitionClientCapabilities`

**acpVersion** `AcpProtocolVersion`

#### Returns

`Promise<InitializeResult>`

### launchSession()

```typescript
launchSession(input: PromptInput, options: LaunchSessionOptions<LocalSessionOptions, T> & { turn: RunOptions<T> & { output: StandardSchema<T> } }): Promise<LaunchedSession<LocalSession, T>>
```

Create a session and submit its first turn. Resolves on `turn.accepted`,
not the turn's outcome. Cancel explicitly with `session.cancel()`.
Startup errors after creation preserve `sessionId`; never retry blindly.

#### Parameters

**input** `PromptInput` *required*

**options** `LaunchSessionOptions\<LocalSessionOptions, T\> & \{ turn: RunOptions\<T\> & \{ output…` *required*

**Type:** `LaunchSessionOptions<LocalSessionOptions, T> & { turn: RunOptions<T> & { output: StandardSchema<T> } }`

#### Returns

`Promise<LaunchedSession<LocalSession, T>>`

```typescript
launchSession(input: PromptInput, options?: LaunchSessionOptions<LocalSessionOptions, unknown> & { turn: Omit<RunOptions<unknown>, "output"> & { output: undefined } }): Promise<LaunchedSession<LocalSession, undefined>>
```

Create a session and submit its first turn. Resolves on `turn.accepted`,
not the turn's outcome. Cancel explicitly with `session.cancel()`.
Startup errors after creation preserve `sessionId`; never retry blindly.

#### Parameters

**input** `PromptInput` *required*

**options** `LaunchSessionOptions\<LocalSessionOptions, unknown\> & \{ turn: Omit\<RunOptions\<un…`

**Type:** `LaunchSessionOptions<LocalSessionOptions, unknown> & { turn: Omit<RunOptions<unknown>, "output"> & { output: undefined } }`

#### Returns

`Promise<LaunchedSession<LocalSession, undefined>>`

```typescript
launchSession(input: PromptInput, options: LaunchSessionOptions<LocalSessionOptions, T>): Promise<LaunchedSession<LocalSession, undefined | T>>
```

Create a session and submit its first turn. Resolves on `turn.accepted`,
not the turn's outcome. Cancel explicitly with `session.cancel()`.
Startup errors after creation preserve `sessionId`; never retry blindly.

#### Parameters

**input** `PromptInput` *required*

**options** `LaunchSessionOptions\<LocalSessionOptions, T\>` *required*

**Type:** `LaunchSessionOptions<LocalSessionOptions, T>`

#### Returns

`Promise<LaunchedSession<LocalSession, undefined | T>>`

### listSessions()

```typescript
listSessions(options?: ListSessionsOptions): Promise<SessionInfo[]>
```

List persisted sessions, most recently updated first.

#### Parameters

**options** `ListSessionsOptions`

#### Returns

`Promise<SessionInfo[]>`

### listSubagents()

```typescript
listSubagents(cwd?: string): Promise<SubagentsListResponse>
```

List the subagents running for sessions rooted at `cwd` (defaults to the client-level `cwd`).

#### Parameters

**cwd** `string`

#### Returns

`Promise<SubagentsListResponse>`

### loadSession()

```typescript
loadSession(sessionId: string, options?: LoadSessionOptions): Promise<LoadedLocalSession>
```

Resume a persisted session (sessions survive CLI restarts). The session
keeps its persisted model — the client-level `model` default applies only
to `createSession`; use `session.setModel` to switch.

#### Parameters

**sessionId** `string` *required*

**options** `LoadSessionOptions`

#### Returns

`Promise<LoadedLocalSession>`

### mcpServers()

```typescript
mcpServers(options: SessionOptions): McpServer[]
```

#### Parameters

**options** `SessionOptions` *required*

#### Returns

`McpServer[]`

### openSession()

```typescript
openSession(session: LocalSession, options: SessionOptions, establish?: () => Promise<unknown>): Promise<LocalSession>
```

Bring a freshly constructed session live: wire its permission handler,
route notifications to it, and run the agent request that establishes it
(`session/new` follow-ups such as choosing the model or organization). A
failing request releases the session and surfaces as a
[SessionStartupError](https://docs.devin.ai/sdk/reference/classes/SessionStartupError.md) carrying the allocated id.

#### Parameters

**session** `LocalSession` *required*

**options** `SessionOptions` *required*

**establish** `() =\> Promise\<unknown\>`

#### Returns

`Promise<LocalSession>`

### releaseSession()

```typescript
releaseSession(sessionId: string): void
```

Detach a session: active turns reject, observers end, and the handle cannot send requests.

#### Parameters

**sessionId** `string` *required*

### resumeSession()

```typescript
resumeSession(session: LocalSession, options: SessionOptions, load: () => Promise<unknown>): Promise<LoadedSession<LocalSession>>
```

Resume an existing session: like `openSession`, but the agent
replays history as `session/update` notifications before `load` settles;
those are captured and returned instead of being delivered live. Refuses
a session that is already open on this client, since loading it again
would steal its notification routing.

#### Parameters

**session** `LocalSession` *required*

**options** `SessionOptions` *required*

**load** `() =\> Promise\<unknown\>` *required*

#### Returns

`Promise<LoadedSession<LocalSession>>`

### spawn()

```typescript
spawn(cliPath: string, options?: Omit<LocalDevinOptions, "apiKey" | "stateDir">, env?: ProcessEnv): Promise<LocalDevin>
```

Spawn the CLI at `cliPath` as `devin acp` with exactly `env`, and perform
the ACP `initialize` handshake. Unlike `start` this neither requires
an API key nor redirects the CLI's state directories, for hosts whose CLI
is already authenticated (e.g. a sandbox).

#### Parameters

**cliPath** `string` *required*

**options** `Omit\<LocalDevinOptions, "apiKey" | "stateDir"\>`

**Type:** `Omit<LocalDevinOptions, "apiKey" | "stateDir">`

**env** `ProcessEnv`

#### Returns

`Promise<LocalDevin>`

### start()

```typescript
start(options?: LocalDevinOptions): Promise<LocalDevin>
```

Spawn `devin acp` and perform the ACP `initialize` handshake.

#### Parameters

**options** `LocalDevinOptions`

#### Returns

`Promise<LocalDevin>`

### supports()

```typescript
supports(capability: string): boolean
```

Whether the agent advertised a `cognition.ai/*` capability, e.g.
`devin.supports("cognition.ai/sessionRename")` before calling
`session.rename()`.

#### Parameters

**capability** `string` *required*

#### Returns

`boolean`

### track()

```typescript
track(session: AcpSession): void
```

Register a session so its notifications are routed to it.

#### Parameters

**session** `AcpSession` *required*

### untrack()

```typescript
untrack(sessionId: string): void
```

Stop routing notifications to a session (e.g. after deleting it).

#### Parameters

**sessionId** `string` *required*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.