### Start Development Server

Source: https://github.com/langchain-ai/openwork/blob/main/CONTRIBUTING.md

Launch the development server to start working on the project. This command is used after installing dependencies.

```bash
npm run dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/langchain-ai/openwork/blob/main/CONTRIBUTING.md

Install all project dependencies using npm. Ensure Node.js 20+ and npm 10+ are installed.

```bash
npm install
```

--------------------------------

### Execute Output Examples

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Examples of command output formats including stderr and truncation.

```bash
# Normal command
> echo "hello"
output: "hello\n"
exitCode: 0

# Command with stderr
> ls nonexistent
output: "[stderr] ls: cannot access 'nonexistent': No such file or directory\n"
exitCode: 2

# Truncated output
output: "...lots of output...\n\n... Output truncated at 100000 bytes."
truncated: true
```

--------------------------------

### List Checkpoints Examples

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Examples showing basic iteration and manual pagination logic for retrieving checkpoint lists.

```typescript
const config = { configurable: { thread_id: 'thread-1' } }

for await (const tuple of checkpointer.list(config, { limit: 10 })) {
  console.log('Checkpoint:', tuple.checkpoint.id)
}
```

```typescript
// Get first 50
const checkpoints = []
for await (const cp of checkpointer.list(config, { limit: 50 })) {
  checkpoints.push(cp)
}

// Get next 50 (before oldest from first batch)
const before = checkpoints[checkpoints.length - 1].config
for await (const cp of checkpointer.list(config, { limit: 50, before })) {
  checkpoints.push(cp)
}
```

--------------------------------

### Install and Run Openwork from Source

Source: https://github.com/langchain-ai/openwork/blob/main/README.md

Clone the repository, install dependencies, and run the development server. Requires Node.js 18+.

```bash
git clone https://github.com/langchain-ai/openwork.git
cd openwork
npm install
npm run dev
```

--------------------------------

### Install Openwork via NPM

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/README.md

Use these commands to install the package globally or run it directly via npx.

```bash
npm install -g openwork
# or
npx openwork
```

--------------------------------

### initialize()

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Loads or creates the checkpoint database, performing necessary file size checks and schema setup.

```APIDOC
## initialize()

### Description
Loads or creates the checkpoint database. This method handles loading the sql.js library, verifying database file size (max 100MB), and initializing the schema.

### Example
```typescript
const checkpointer = new SqlJsSaver(dbPath)
await checkpointer.initialize()
// Now ready for checkpoint operations
```
```

--------------------------------

### Instantiate LocalSandbox

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Example of creating a new LocalSandbox instance with custom configuration.

```typescript
const backend = new LocalSandbox({
  rootDir: '/Users/me/myproject',
  virtualMode: false,
  timeout: 120_000,
  maxOutputBytes: 100_000
})
```

--------------------------------

### Execute Error Handling Examples

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Example response structures for timeout and spawn failure scenarios.

```typescript
// Timeout
{
  output: "Error: Command timed out after 120.0 seconds.",
  exitCode: null,
  truncated: false
}

// Spawn failure
{
  output: "Error: Failed to execute command: ENOENT",
  exitCode: 1,
  truncated: false
}
```

--------------------------------

### Example usage of closeCheckpointer

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Demonstrates how to trigger the cleanup process for a checkpointer.

```typescript
await closeCheckpointer('thread-1')
```

--------------------------------

### Install and Run Openwork with npx

Source: https://github.com/langchain-ai/openwork/blob/main/README.md

Use this command to run Openwork directly without global installation. Requires Node.js 18+.

```bash
# Run directly with npx
npx openwork

# Or install globally
npm install -g openwork
openwork
```

--------------------------------

### Database Backup Example

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Visual representation of the automatic backup process when a database exceeds the size threshold.

```text
Old:    ~/.openwork/threads/thread-1.sqlite (105MB)
↓ (backs up on initialize)
New:    ~/.openwork/threads/thread-1.sqlite.bak.1704067200000
Fresh:  ~/.openwork/threads/thread-1.sqlite (empty)
```

--------------------------------

### Initialize and stream from an agent instance

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Example showing how to create an agent runtime and stream messages using the configured thread ID.

```typescript
const agent = await createAgentRuntime({
  threadId: 'abc-123',
  modelId: 'claude-opus-4-5-20251101',
  workspacePath: '/Users/me/myproject'
})

const stream = await agent.stream(
  { messages: [new HumanMessage('Hello')] },
  {
    configurable: { thread_id: 'abc-123' },
    streamMode: ['messages', 'values']
  }
)

for await (const chunk of stream) {
  console.log(chunk)
}
```

--------------------------------

### Save Checkpoint Example

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Example of manually invoking the put method to save a checkpoint.

```typescript
// LangGraph calls this automatically during graph execution
const saved = await checkpointer.put(
  { configurable: { thread_id: 'thread-1' } },
  { id: 'cp-123', ts: new Date().toISOString(), messages: [...] },
  { writes: {...} }
)
```

--------------------------------

### System Prompt Usage

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Example of generating a system prompt for a specific workspace directory.

```typescript
const prompt = getSystemPrompt('/Users/me/project')
// Includes: "The workspace root is: /Users/me/project"
// Includes: file operations with absolute paths
```

--------------------------------

### Setup LocalSandbox Agent

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Initializes a LocalSandbox with specific constraints and integrates it into a deepagent instance.

```typescript
import { LocalSandbox } from './agent/local-sandbox'
import { createDeepAgent } from 'deepagents'

const sandbox = new LocalSandbox({
  rootDir: '/Users/me/myproject',
  virtualMode: false,
  timeout: 120_000,
  maxOutputBytes: 100_000
})

const agent = createDeepAgent({
  model: chatModel,
  checkpointer: checkpointer,
  backend: sandbox,
  systemPrompt: 'You are a helpful assistant.',
  interruptOn: { execute: true }  // Require HITL approval
})

// Stream agent
const stream = await agent.stream(
  { messages: [new HumanMessage('Run the tests')] },
  { configurable: { thread_id: 'thread-1' } }
)

for await (const chunk of stream) {
  console.log(chunk)
}
```

--------------------------------

### LocalSandbox Tool Usage Examples

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Illustrates the types of file and shell operations available to the agent when using LocalSandbox.

```typescript
// Agent can now use:
// - read_file('/Users/me/project/src/index.ts')
// - execute('npm test')
// - grep('TODO', '**/*.ts')
```

--------------------------------

### Execute Command Usage

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Example of invoking the execute method and handling the response.

```typescript
const result = await backend.execute('npm test')
console.log(result.output)
console.log('Exit code:', result.exitCode)
if (result.truncated) {
  console.log('Output truncated at 100KB')
}
```

--------------------------------

### Example usage of file change listener

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Demonstrates how to implement the listener to log the workspace path when changes occur.

```typescript
window.api.workspace.onFilesChanged(({ threadId, workspacePath }) => {
  console.log('Files changed:', workspacePath)
})
```

--------------------------------

### List Directory Contents

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Method signature and usage example for listing files in a directory.

```typescript
async ls(path: string): Promise<FileInfo[]>
```

```typescript
const files = await backend.ls('/Users/me/myproject')
files.forEach(f => {
  console.log(`${f.is_dir ? '[DIR]' : '[FILE]'} ${f.path}`)
})
```

--------------------------------

### Environment Variable Configuration

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

Example format for the .env file used to store API keys for various providers.

```text
ANTHROPIC_API_KEY=sk-ant-v3-abc123...
OPENAI_API_KEY=sk-proj-abc123...
GOOGLE_API_KEY=gsk-abc123...
```

--------------------------------

### Retrieve Checkpoint Example

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Demonstrates how to fetch a checkpoint tuple using a thread ID.

```typescript
const tuple = await checkpointer.getTuple({
  configurable: { thread_id: 'thread-1' }
})

if (tuple) {
  console.log('Last checkpoint:', tuple.checkpoint.id)
  console.log('Can resume from:', tuple.config)
}
```

--------------------------------

### Write File Content

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Method signature and usage example for writing or creating a file.

```typescript
async write_file(path: string, content: string): Promise<void>
```

```typescript
await backend.write_file('/Users/me/myproject/config.json', JSON.stringify({}))
```

--------------------------------

### Model Instance Usage

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Example of initializing a model instance using a specific model ID.

```typescript
const model = getModelInstance('claude-opus-4-5-20251101')
// Returns: ChatAnthropic with anthropicApiKey set
```

--------------------------------

### Handle database size limits

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

The system detects when the database exceeds size limits during initialization, triggers a backup, and starts a fresh database.

```typescript
// Detected on initialize
// Automatic backup + fresh database
console.warn(`Database file too large (${sizeInMB}MB), backing up...`)
```

--------------------------------

### Get Database Instance

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/database.md

Retrieves the initialized SqlJsDatabase instance. Throws an error if the database has not been initialized.

```typescript
function getDb(): SqlJsDatabase
```

```typescript
const db = getDb()
const stmt = db.prepare("SELECT * FROM threads WHERE thread_id = ?")
```

--------------------------------

### workspace:get

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Retrieves the workspace path for a specific thread or globally.

```APIDOC
## IPC Handle: workspace:get

### Description
Retrieves the absolute workspace path for a given thread ID or from global settings if no thread ID is provided.

### Parameters
- **threadId** (string) - Optional - The thread ID to retrieve the workspace path for.
```

--------------------------------

### Read File Contents

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Method signature and usage example for reading file content as text.

```typescript
async read_file(path: string): Promise<string>
```

```typescript
const content = await backend.read_file('/Users/me/myproject/README.md')
console.log(content)
```

--------------------------------

### Example usage of deleteThread

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Demonstrates how to invoke the deleteThread method to remove thread data.

```typescript
// When user deletes thread
await checkpointer.deleteThread('thread-1')
// Checkpoints deleted, database file still exists (can be recreated)
```

--------------------------------

### Find Files with Glob

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Method signature and usage example for finding files matching a glob pattern.

```typescript
async glob(pattern: string): Promise<string[]>
```

```typescript
const tsFiles = await backend.glob('**/*.ts')
console.log(`Found ${tsFiles.length} TypeScript files`)
```

--------------------------------

### Invoke models:list IPC handler

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Example usage of the models:list IPC handler from the renderer process.

```typescript
const models = await window.api.models.list()
const claude = models.find(m => m.id === 'claude-opus-4-5-20251101')
```

--------------------------------

### Search Text with Grep

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Method signature and usage example for searching text within files.

```typescript
async grep(pattern: string, filePath?: string): Promise<GrepMatch[]>
```

```typescript
const matches = await backend.grep('TODO', '**/*.ts')
matches.forEach(m => {
  console.log(`${m.path}:${m.line}: ${m.text}`)
})
```

--------------------------------

### Initialize Application

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/README.md

Perform database and handler registration during the main process startup.

```typescript
// Main process startup (index.ts)
await initializeDatabase()
registerAgentHandlers(ipcMain)
registerThreadHandlers(ipcMain)
registerModelHandlers(ipcMain)
```

--------------------------------

### threads:get

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Get a single thread by ID.

```APIDOC
## threads:get

### Description
Get a single thread by ID.

### Parameters
- **threadId** (string) - Thread ID

### Returns
- **Promise<Thread | null>** - The requested thread or null if not found
```

--------------------------------

### Build the Project

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/INDEX.md

Executes the build process to generate distribution-ready files in the out/ directory.

```bash
npm run build
```

--------------------------------

### Build Project

Source: https://github.com/langchain-ai/openwork/blob/main/CONTRIBUTING.md

Build the project for all platforms. This command is typically run before deployment or release.

```bash
npm run build
```

--------------------------------

### LocalSandbox Initialization

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Initializes the file system and shell command backend for the agent.

```APIDOC
## LocalSandbox Constructor

### Description
Initializes the sandbox environment for file system operations and shell command execution.

### Parameters
- **rootDir** (string) - Required - The workspace path for file operations.
- **virtualMode** (boolean) - Optional - If false, uses absolute paths.
- **timeout** (number) - Optional - Execution timeout in milliseconds.
- **maxOutputBytes** (number) - Optional - Maximum output size in bytes.

### Example
```typescript
const backend = new LocalSandbox({
  rootDir: workspacePath,
  virtualMode: false,
  timeout: 120_000,
  maxOutputBytes: 100_000
})
```
```

--------------------------------

### threads:history

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Get execution history (checkpoints) for a thread.

```APIDOC
## threads:history

### Description
Get execution history (checkpoints) for a thread.

### Parameters
- **threadId** (string) - Thread ID

### Returns
- **Promise<unknown[]>** - Array of checkpoint tuples
```

--------------------------------

### Initialize LocalSandbox Backend

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Configures the local file system and shell command backend with root directory, timeout, and output limits.

```typescript
const backend = new LocalSandbox({
  rootDir: workspacePath,
  virtualMode: false,           // Use absolute paths
  timeout: 120_000,             // 2 minutes
  maxOutputBytes: 100_000       // ~100KB
})
```

--------------------------------

### constructor(dbPath, serde?)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Initializes a new instance of the SqlJsSaver with a specified database path and optional serializer.

```APIDOC
## constructor(dbPath, serde?)

### Description
Creates a new checkpoint saver instance for the specified database file path.

### Parameters
- **dbPath** (string) - Required - Path to checkpoint database file
- **serde** (SerializerProtocol) - Optional - Serializer (defaults to JSON/pickle)

### Example
```typescript
const checkpointer = new SqlJsSaver('~/.openwork/threads/thread-1.sqlite')
await checkpointer.initialize()
```
```

--------------------------------

### Get default model

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Returns the ID of the currently configured default model.

```typescript
getDefault(): Promise<string>
```

```typescript
const modelId = await window.api.models.getDefault()
console.log(`Using model: ${modelId}`)
```

--------------------------------

### Get thread execution history

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Retrieves the sequence of checkpoints for a specific thread.

```typescript
const history = await window.api.threads.getHistory('thread-id')
console.log(`Thread has ${history.length} checkpoints`)
```

--------------------------------

### Configure API Keys Manually

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

Manual configuration of the .env file using key-value pairs and comments.

```bash
# Set keys
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=gsk-...

# Comments
# This is a comment
```

--------------------------------

### list(config, options?)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Iterates over all checkpoints for a specific thread, supporting pagination via limits and 'before' pointers.

```APIDOC
## list(config, options?)

### Description
Iterate over all checkpoints for a thread, ordered by checkpoint_id in descending order (newest first).

### Parameters
- **config** (RunnableConfig) - Required - Thread configuration containing thread_id.
- **options** (CheckpointListOptions) - Optional - Configuration for pagination including limit and before (a RunnableConfig to start before).
```

--------------------------------

### Define Configuration Directory

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

The base directory for all application data, created automatically on the first run.

```text
~/.openwork/
```

--------------------------------

### Handle missing database file

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

The system automatically initializes a new database if the file is missing during startup.

```typescript
// On initialize if file missing: creates new db
// No error thrown
```

--------------------------------

### getDb()

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/database.md

Retrieves the initialized database instance.

```APIDOC
## getDb()

### Description
Get the initialized database instance.

### Returns
- **SqlJsDatabase** - Global database reference

### Throws
- Error if database not initialized
```

--------------------------------

### Get workspace path

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Retrieves the absolute path for a specific thread or the global workspace setting.

```typescript
get(threadId?: string): Promise<string | null>
```

```typescript
const path = await window.api.workspace.get('thread-id')
if (path) {
  console.log(`Working in: ${path}`)
}
```

--------------------------------

### getSystemPrompt(workspacePath)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Generates a complete system prompt for the agent, incorporating the provided workspace path and standard behavioral guidelines.

```APIDOC
## getSystemPrompt(workspacePath)

### Description
Generates a comprehensive system prompt for the agent, including workspace context and operational guidelines such as file system handling, task management, and tool usage.

### Parameters
- **workspacePath** (string) - Required - The absolute path to the workspace, which is injected into the system prompt context.

### Returns
- **string** - The full system prompt string.
```

--------------------------------

### Define threads:get IPC handler

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Registers the handler to retrieve a single thread by its ID.

```typescript
ipcMain.handle("threads:get", (event, threadId: string) => Promise<Thread | null>)
```

--------------------------------

### createAgentRuntime(options)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Initializes a new agent instance with a specified thread ID, model, and workspace path.

```APIDOC
## createAgentRuntime(options)

### Description
Creates an agent instance configured with a model, checkpointer, and file system backend.

### Signature
`async function createAgentRuntime(options: CreateAgentRuntimeOptions): Promise<AgentRuntime>`

### Parameters
- **threadId** (string) - Required - Unique thread ID for per-thread checkpointing.
- **modelId** (string) - Optional - Model to use (e.g., "claude-opus-4-5-20251101").
- **workspacePath** (string) - Required - Absolute workspace directory for file operations.

### Returns
- **Promise<AgentRuntime>** - Configured deep agent instance.

### Errors
- **Thread ID is required** - Thrown if threadId is not provided.
- **Workspace path is required** - Thrown if workspacePath is not provided.
- **API key not configured** - Thrown if the model provider API key is missing.
```

--------------------------------

### initializeDatabase()

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/database.md

Initializes the SQLite database at ~/.openwork/openwork.sqlite, creating necessary tables and indices if they do not exist.

```APIDOC
## initializeDatabase()

### Description
Initializes and sets up the main metadata database. This function loads or creates the SQLite database file, creates the required schema tables, and sets up performance indices.

### Signature
`async function initializeDatabase(): Promise<SqlJsDatabase>`

### Returns
- **Promise<SqlJsDatabase>** - A promise that resolves to the sql.js database instance.

### Example
```typescript
await initializeDatabase();
```
```

--------------------------------

### Get workspace path via IPC

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Retrieves the workspace path for a specific thread or global settings.

```typescript
ipcMain.handle("workspace:get", (event, threadId?: string) => Promise<string | null>)
```

--------------------------------

### AgentRuntime.batch(inputs, config)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Executes multiple inputs in a batch and returns a Promise.

```APIDOC
## batch(inputs, config)

### Description
Executes multiple inputs in a batch.

### Parameters
- **inputs** (any[]) - An array of inputs for the agent.
- **config** (RunnableConfig) - Configuration object including thread_id, checkpoint_id, signal, streamMode, and recursionLimit.
```

--------------------------------

### Edit File Content

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Method signature and usage example for performing find and replace operations in a file.

```typescript
async edit_file(path: string, oldString: string, newString: string): Promise<void>
```

```typescript
await backend.edit_file(
  '/Users/me/myproject/src/index.ts',
  'export const VERSION = "1.0"',
  'export const VERSION = "1.1"'
)
```

--------------------------------

### Get provider API key

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Retrieves the stored API key for a given provider, returning null if not configured.

```typescript
getApiKey(provider: string): Promise<string | null>
```

```typescript
const key = await window.api.models.getApiKey('openai')
if (key) {
  console.log('OpenAI API key is configured')
}
```

--------------------------------

### Clone and Navigate Repository

Source: https://github.com/langchain-ai/openwork/blob/main/CONTRIBUTING.md

Clone the openwork repository and navigate into the project directory. Replace YOUR_USERNAME with your GitHub username.

```bash
git clone https://github.com/YOUR_USERNAME/openwork.git
cd openwork
```

--------------------------------

### Initialize Database

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/database.md

Initializes the SQLite database at ~/.openwork/openwork.sqlite, creating necessary tables and indices if they do not exist.

```typescript
async function initializeDatabase(): Promise<SqlJsDatabase>
```

```typescript
await initializeDatabase()
// Creates ~/.openwork/openwork.sqlite if not exists
// Sets up schema
```

--------------------------------

### Initialize SqlJsSaver

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Create and initialize a new checkpoint saver instance using a database file path.

```typescript
const checkpointer = new SqlJsSaver('~/.openwork/threads/thread-1.sqlite')
await checkpointer.initialize()
```

```typescript
const checkpointer = new SqlJsSaver(dbPath)
await checkpointer.initialize()
// Now ready for checkpoint operations
```

--------------------------------

### Define settings.json configuration

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

The standard JSON format for defining default models and workspace paths.

```json
{
  "defaultModel": "claude-sonnet-4-5-20250929",
  "workspacePath": "/Users/me/myproject"
}
```

```json
{
  "defaultModel": "gpt-5.2",
  "workspacePath": "/home/user/coding"
}
```

--------------------------------

### workspace:loadFromDisk

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Scans the workspace directory and returns a file tree.

```APIDOC
## IPC Handle: workspace:loadFromDisk

### Description
Recursively scans the workspace directory associated with the thread, returning a list of files while skipping hidden files and node_modules.

### Parameters
- **threadId** (string) - Required - The thread ID to scan.
```

--------------------------------

### window.api.workspace.select

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

Opens a dialog to select a workspace path.

```APIDOC
## window.api.workspace.select(threadId)

### Description
Opens a system dialog to allow the user to select a workspace directory for the given thread.

### Parameters
- **threadId** (string) - Required - The identifier for the thread.
```

--------------------------------

### AgentRuntime.invoke(input, config)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Executes a single turn of the agent and returns a Promise.

```APIDOC
## invoke(input, config)

### Description
Executes a single turn of the agent.

### Parameters
- **input** (any) - The input data for the agent.
- **config** (RunnableConfig) - Configuration object including thread_id, checkpoint_id, signal, streamMode, and recursionLimit.
```

--------------------------------

### Execute Agent File Operations

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Demonstrates common filesystem operations available when using an agent with LocalSandbox.

```typescript
// List workspace root
result = await agent.execute('ls -la')

// Read file via tool
result = await agent.read_file('/Users/me/myproject/src/index.ts')

// Search files
result = await agent.glob('**/*.test.ts')

// Find pattern
result = await agent.grep('export', '**/*.ts')
```

--------------------------------

### Command Execution Configuration

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/README.md

Performance settings for command timeouts, output limits, and working directories.

```typescript
// Timeout: 120 seconds (configurable)
// Output limit: 100KB (configurable)
// Working directory: Set to workspace path for speed
```

--------------------------------

### Set System Environment Variables

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

Configures API keys across different operating system shells.

```bash
# macOS/Linux
export OPENAI_API_KEY="sk-..."

# Windows PowerShell
$env:OPENAI_API_KEY="sk-..."

# Windows CMD
set OPENAI_API_KEY=sk-...
```

--------------------------------

### Set API Keys via CLI

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

Configures API keys using environment variables or by writing to the local .env file.

```bash
# Set API key before running
ANTHROPIC_API_KEY=sk-ant-... npm run dev

# Or via .env file
echo "ANTHROPIC_API_KEY=sk-ant-..." > ~/.openwork/.env
```

--------------------------------

### workspace.loadFromDisk(threadId)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Scans the workspace directory and returns the file tree structure.

```APIDOC
## workspace.loadFromDisk(threadId)

### Description
Scan workspace directory and return file tree.

### Parameters
#### Path Parameters
- **threadId** (string) - Required - Thread ID

### Response
- **Returns** (Promise<{ success, files, workspacePath?, error? }>) - File listing or error
```

--------------------------------

### flush()

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/database.md

Forces an immediate save of the database to disk.

```APIDOC
## flush()

### Description
Force immediate save to disk (bypasses debounce).

### Returns
- **Promise<void>**
```

--------------------------------

### LocalSandbox Constructor

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

The LocalSandbox constructor allows for the configuration of the execution environment, including resource limits and directory settings.

```APIDOC
## LocalSandbox(options)

### Description
Initializes a new LocalSandbox instance with custom configuration settings for process execution.

### Parameters
- **timeout** (number) - Optional - Execution timeout in milliseconds (default: 120,000).
- **maxOutputBytes** (number) - Optional - Maximum combined stdout and stderr size in bytes (default: 100,000).
- **rootDir** (string) - Optional - The working directory for spawned commands.
- **virtualMode** (boolean) - Optional - Whether to use virtual paths (default: false).
- **env** (Record<string, string>) - Optional - Environment variables to pass to the process.
- **maxFileSizeMb** (number) - Optional - Maximum file size limit for reads in MB (default: 10).

### Example
```typescript
const backend = new LocalSandbox({
  timeout: 30000,
  maxOutputBytes: 50000,
  rootDir: '/path/to/project',
  virtualMode: false,
  env: { NODE_ENV: 'production' },
  maxFileSizeMb: 50
});
```
```

--------------------------------

### Load workspace from disk

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Scans the workspace directory and returns a file tree structure.

```typescript
loadFromDisk(threadId: string): Promise<{
  success: boolean
  files: FileInfo[]
  workspacePath?: string
  error?: string
}>
```

```typescript
interface FileInfo {
  path: string           // Virtual path (starts with /)
  is_dir: boolean
  size?: number
  modified_at?: string   // ISO timestamp
}
```

```typescript
const result = await window.api.workspace.loadFromDisk('thread-id')
if (result.success) {
  result.files.forEach(f => {
    console.log(`${f.is_dir ? '[DIR]' : '[FILE]'} ${f.path}`)
  })
}
```

--------------------------------

### Initialize LocalSandbox Constructor

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Constructor signature for initializing the LocalSandbox instance.

```typescript
constructor(options: LocalSandboxOptions = {})
```

--------------------------------

### Configure Working Directory

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Defines the root directory for spawned processes and toggles between absolute and virtual path modes.

```typescript
rootDir: '/Users/me/myproject'
virtualMode: false  // Use absolute paths
```

```typescript
const backend = new LocalSandbox({
  rootDir: workspacePath,
  virtualMode: false
})
```

--------------------------------

### app:version

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Retrieves the current application version synchronously.

```APIDOC
## app:version

### Description
Get application version synchronously.

### Method
IPC Sync
```

--------------------------------

### List available models

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Retrieves an array of all available model configurations.

```typescript
list(): Promise<ModelConfig[]>
```

```typescript
const models = await window.api.models.list()
const available = models.filter(m => m.available)
console.log(`${available.length} models available`)
```

--------------------------------

### Storage Directory Structure

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/INDEX.md

Layout of the ~/.openwork/ directory containing metadata, configuration, and thread checkpoints.

```text
~/.openwork/
├── openwork.sqlite          # Thread metadata
├── .env                     # API keys
├── settings.json            # App config
└── threads/{threadId}.sqlite  # Checkpoints
```

--------------------------------

### threads:create

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Create a new thread.

```APIDOC
## threads:create

### Description
Create a new thread with optional metadata.

### Parameters
- **metadata** (Record<string, unknown>) - Optional - Initial metadata

### Returns
- **Promise<Thread>** - New thread with auto-generated ID
```

--------------------------------

### put(config, checkpoint, metadata)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

Saves a checkpoint state and metadata to the storage system.

```APIDOC
## put(config, checkpoint, metadata)

### Description
Save a checkpoint. This method is typically called automatically by LangGraph during graph execution to persist state.

### Parameters
- **config** (RunnableConfig) - Required - Thread configuration.
- **checkpoint** (Checkpoint) - Required - The state snapshot to save.
- **metadata** (CheckpointMetadata) - Required - Metadata associated with the checkpoint.

### Returns
- **Promise<RunnableConfig>** - The configuration object updated with the saved checkpoint_id.
```

--------------------------------

### Run Project Checks

Source: https://github.com/langchain-ai/openwork/blob/main/CONTRIBUTING.md

Execute linting and type checking to ensure code quality and correctness before building or submitting changes. These commands should pass before creating a pull request.

```bash
npm run lint
```

```bash
npm run typecheck
```

--------------------------------

### Format API Key Environment Variables

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

The required format for storing API keys in the .env file.

```text
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=gsk-...
```

--------------------------------

### Select workspace via IPC

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Opens a directory selection dialog and updates the workspace path.

```typescript
ipcMain.handle("workspace:select", (event, threadId?: string) => Promise<string | null>)
```

--------------------------------

### models:listProviders

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Lists all supported AI providers and their current API key configuration status.

```APIDOC
## models:listProviders

### Description
List supported providers with API key status.

### Method
IPC Handle

### Returns
- **Promise<Provider[]>** - List of providers including id, name, and hasApiKey status.
```

--------------------------------

### Database Optimization Configuration

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/README.md

Settings for auto-save debouncing and checkpoint size limits.

```typescript
// Auto-save debounce: 100ms
// Batches multiple writes into single disk operation

// Checkpoint size
// - Typical: 1-10MB for 50-100 checkpoints
// - Max: 100MB before auto-recovery kicks in
```

--------------------------------

### execute(command)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Executes a shell command in the workspace directory and returns the command output, exit code, and truncation status.

```APIDOC
## execute(command)

### Description
Executes a shell command in the workspace directory. The method spawns a shell process, enforces a timeout, and returns the combined stdout and stderr output.

### Signature
`async execute(command: string): Promise<ExecuteResponse>`

### Parameters
- **command** (string) - Required - The shell command to execute.

### Returns
- **ExecuteResponse** (object)
  - **output** (string) - The combined stdout and stderr output (stderr lines are prefixed with [stderr]).
  - **exitCode** (number | null) - The process exit code.
  - **truncated** (boolean) - Indicates if the output exceeded the maximum allowed size.

### Example
```typescript
const result = await backend.execute('npm test');
console.log(result.output);
console.log('Exit code:', result.exitCode);
```
```

--------------------------------

### Access Storage Paths

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/database.md

Utility functions for resolving paths to the main database, configuration files, and thread-specific checkpoints.

```typescript
getOpenworkDir(): string
// ~/.openwork

getDbPath(): string
// ~/.openwork/openwork.sqlite

getCheckpointDbPath(): string
// ~/.openwork/langgraph.sqlite

getThreadCheckpointDir(): string
// ~/.openwork/threads

getThreadCheckpointPath(threadId): string
// ~/.openwork/threads/{threadId}.sqlite

getEnvFilePath(): string
// ~/.openwork/.env
```

--------------------------------

### workspace.select(threadId?)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Opens a folder selection dialog and sets the workspace path for the specified thread.

```APIDOC
## workspace.select(threadId?)

### Description
Open a folder selection dialog and set workspace path.

### Parameters
#### Path Parameters
- **threadId** (string) - Optional - Thread ID to bind workspace to

### Response
- **Returns** (Promise<string | null>) - Selected path or null if cancelled
```

--------------------------------

### Workspace API

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/INDEX.md

Methods for file system and workspace management.

```APIDOC
## window.api.workspace

### Methods
- **get(threadId?)**: Gets workspace info.
- **set(threadId?, path)**: Sets workspace path.
- **select(threadId?)**: Selects a workspace.
- **loadFromDisk(threadId)**: Loads workspace from disk.
- **readFile(threadId, path)**: Reads a text file.
- **readBinaryFile(threadId, path)**: Reads a binary file.
- **onFilesChanged(callback)**: Registers a file change listener.
```

--------------------------------

### Configure Deep Agent

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Initializes the Deep Agent with model, checkpointer, backend, and interrupt settings for shell command approval.

```typescript
const agent = createDeepAgent({
  model,                         // Chat model instance
  checkpointer,                  // SqlJsSaver for thread
  backend,                       // LocalSandbox for files/shell
  systemPrompt,                  // Full system prompt with workspace
  filesystemSystemPrompt,        // Custom filesystem prompt with paths
  interruptOn: { execute: true } // Require approval for shell commands
})
```

--------------------------------

### Configure Model

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/README.md

Set provider API keys and define the default model for the application.

```typescript
// Renderer - Set API key
await window.api.models.setApiKey('anthropic', 'sk-ant-...')

// Set as default
await window.api.models.setDefault('claude-opus-4-5-20251101')
```

--------------------------------

### Retrieve Database Paths

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

Functions to resolve paths for the main database, thread checkpoints, and legacy storage.

```typescript
getDbPath(): string  // ~/.openwork/openwork.sqlite
```

```typescript
getThreadCheckpointPath(threadId: string)  // ~/.openwork/threads/{threadId}.sqlite
```

```typescript
getCheckpointDbPath(): string  // ~/.openwork/langgraph.sqlite (unused)
```

--------------------------------

### List supported providers

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Retrieves all supported providers along with their current API key configuration status.

```typescript
listProviders(): Promise<Provider[]>
```

```typescript
const providers = await window.api.models.listProviders()
providers.forEach(p => {
  console.log(`${p.name}: ${p.hasApiKey ? 'configured' : 'not configured'}`)
})
```

--------------------------------

### agent:resume

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Resume agent execution from a checkpoint with an approval decision.

```APIDOC
## IPC Event: agent:resume

### Description
Resume agent execution from checkpoint with approval decision.

### Parameters
- **threadId** (string) - Required - Thread ID
- **command** (object) - Required - Resume command with decision
- **command.resume** (object) - Required - Resume configuration
- **command.resume.decision** (string) - Optional - Decision type (approve/reject/edit)
- **modelId** (string) - Optional - Model override

### Example
```typescript
window.api.agent.streamAgent('thread-id', '', 
  { resume: { decision: 'approve' } },
  (event) => { /* handle */ }
)
```
```

--------------------------------

### Configure LocalSandbox Options

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Interface defining configuration options for the LocalSandbox instance.

```typescript
interface LocalSandboxOptions {
  rootDir?: string              // Workspace root (default: process.cwd())
  virtualMode?: boolean         // Virtual paths (default: false)
  maxFileSizeMb?: number        // File size limit (default: 10)
  timeout?: number              // Command timeout ms (default: 120000)
  maxOutputBytes?: number       // Output limit (default: 100000)
  env?: Record<string, string>  // Environment variables
}
```

--------------------------------

### Database File Path Pattern

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

The standard file system path for thread-specific SQLite databases.

```text
~/.openwork/threads/{threadId}.sqlite
```

--------------------------------

### workspace:readBinaryFile

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Reads a binary file from the workspace as base64.

```APIDOC
## IPC Handle: workspace:readBinaryFile

### Description
Reads a binary file (e.g., images, PDFs) from the workspace and returns it as a base64 encoded string.

### Parameters
- **threadId** (string) - Required - The thread ID.
- **filePath** (string) - Required - The virtual path of the file to read.
```

--------------------------------

### write_file(path, content)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Writes or creates a file with the provided content.

```APIDOC
## write_file(path, content)

### Description
Write or create a file. Creates parent directories if needed and overwrites existing files.

### Parameters
- **path** (string) - Required - File path
- **content** (string) - Required - File contents

### Returns
- **Promise<void>**
```

--------------------------------

### Restrict API Key File Permissions

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/README.md

Set file permissions to read/write only for the owner to secure the environment configuration file.

```bash
chmod 600 ~/.openwork/.env
```

--------------------------------

### Retrieve or Initialize a Thread Checkpointer

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Use this to obtain a SqlJsSaver instance for a specific thread. It automatically handles database initialization and caching.

```typescript
async function getCheckpointer(threadId: string): Promise<SqlJsSaver>
```

```typescript
const checkpointer = await getCheckpointer('thread-id')
const config = { configurable: { thread_id: 'thread-id' } }
const checkpoint = await checkpointer.getTuple(config)
```

--------------------------------

### createDeepAgent

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Configures and creates a new Deep Agent instance.

```APIDOC
## createDeepAgent

### Description
Creates a new agent instance with specified model, checkpointer, backend, and system prompts.

### Parameters
- **model** (object) - Required - Chat model instance.
- **checkpointer** (object) - Required - SqlJsSaver for thread state.
- **backend** (object) - Required - LocalSandbox instance.
- **systemPrompt** (string) - Required - Full system prompt.
- **filesystemSystemPrompt** (string) - Required - Custom filesystem prompt.
- **interruptOn** (object) - Optional - Configuration for human-in-the-loop interruptions (e.g., { execute: true }).
```

--------------------------------

### Runtime Functions

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/INDEX.md

Functions for managing agent lifecycles and interacting with the local sandbox environment.

```typescript
createAgentRuntime(options)         // Create agent instance
getCheckpointer(threadId)           // Get/create checkpointer
closeCheckpointer(threadId)         // Close checkpoint database
getSystemPrompt(workspacePath)      // Generate system prompt
LocalSandbox                        // File/shell backend
  .execute(command)
  .read_file(path)
  .write_file(path, content)
  .edit_file(path, oldStr, newStr)
  .ls(path)
  .glob(pattern)
  .grep(pattern, files?)
```

--------------------------------

### ls(path)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Lists the contents of a specified directory.

```APIDOC
## ls(path)

### Description
List directory contents.

### Parameters
- **path** (string) - Required - Directory path (absolute or virtual)

### Returns
- **Promise<FileInfo[]>** - Array of entries with type and size
```

--------------------------------

### workspace:set

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/types.md

Parameters for the workspace:set IPC call.

```APIDOC
## workspace:set

### Description
Sets the workspace path.

### Parameters
- **threadId** (string) - Optional - The ID of the thread.
- **path** (string | null) - Required - The path to set for the workspace.
```

--------------------------------

### Access configuration via IPC

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

Methods for interacting with settings through the window.api interface.

```typescript
// Get default model
const modelId = await window.api.models.getDefault()

// Set default model
await window.api.models.setDefault('claude-opus-4-5-20251101')

// Get workspace (deprecated - use thread metadata instead)
const path = await window.api.workspace.get()

// Set workspace (deprecated - use thread metadata instead)
await window.api.workspace.set(undefined, '/path/to/project')
```

--------------------------------

### Select workspace folder

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Opens a native folder selection dialog to set the workspace path for a thread.

```typescript
select(threadId?: string): Promise<string | null>
```

```typescript
const path = await window.api.workspace.select('thread-id')
if (path) {
  console.log(`Workspace set to: ${path}`)
}
```

--------------------------------

### Agent Runtime Directory Structure

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

The directory structure for the Openwork agent runtime, including storage for metadata, checkpoints, and configuration.

```text
~/.openwork/
├── openwork.sqlite          # Thread metadata
├── langgraph.sqlite         # Checkpoints (legacy)
├── .env                     # API keys
├── settings.json            # Settings (default model, etc.)
└── threads/
    └── {threadId}.sqlite    # Per-thread checkpoint database
```

--------------------------------

### Client API Methods

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/INDEX.md

Access these methods via window.api in the renderer process to manage threads, agents, models, and workspace files.

```typescript
// Threads
window.api.threads.list()
window.api.threads.get(id)
window.api.threads.create()
window.api.threads.update(id, updates)
window.api.threads.delete(id)
window.api.threads.getHistory(id)
window.api.threads.generateTitle(message)

// Agent
window.api.agent.invoke(threadId, message, callback, modelId?)
window.api.agent.streamAgent(threadId, message, command, callback, modelId?)
window.api.agent.interrupt(threadId, decision, callback?)
window.api.agent.cancel(threadId)

// Models
window.api.models.list()
window.api.models.listProviders()
window.api.models.getDefault()
window.api.models.setDefault(modelId)
window.api.models.setApiKey(provider, key)
window.api.models.getApiKey(provider)
window.api.models.deleteApiKey(provider)

// Workspace
window.api.workspace.get(threadId?)
window.api.workspace.set(threadId?, path)
window.api.workspace.select(threadId?)
window.api.workspace.loadFromDisk(threadId)
window.api.workspace.readFile(threadId, path)
window.api.workspace.readBinaryFile(threadId, path)
window.api.workspace.onFilesChanged(callback)
```

--------------------------------

### Define LocalSandbox Class

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Class definition for LocalSandbox extending FilesystemBackend.

```typescript
class LocalSandbox extends FilesystemBackend implements SandboxBackendProtocol
```

--------------------------------

### Configure HITL Approval

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/file-system-backend.md

Enables Human-in-the-Loop (HITL) approval for command execution within the deepagents configuration.

```typescript
createDeepAgent({
  // ...
  interruptOn: { execute: true }  // Require approval for all execute() calls
})
```

--------------------------------

### workspace.readBinaryFile(threadId, filePath)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Reads a binary file from the workspace and returns it as a base64 encoded string.

```APIDOC
## workspace.readBinaryFile(threadId, filePath)

### Description
Read binary file as base64 (images, PDFs, etc.).

### Parameters
#### Path Parameters
- **threadId** (string) - Required - Thread ID
- **filePath** (string) - Required - Virtual path

### Response
- **Returns** (Promise<{ success, content?, size?, modified_at?, error? }>) - base64 content or error
```

--------------------------------

### Configure Command Execution Approval

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/configuration.md

Enables human-in-the-loop approval for shell command execution.

```typescript
createDeepAgent({
  interruptOn: { execute: true }  // All commands need approval
})
```

--------------------------------

### SQL Query for Listing Checkpoints

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/checkpoint-system.md

SQL statement to retrieve a paginated list of checkpoints for a specific thread.

```sql
SELECT * FROM checkpoints
WHERE thread_id = ? AND checkpoint_ns = ?
ORDER BY checkpoint_id DESC
LIMIT ?
```

--------------------------------

### AgentRuntime.stream(input, config)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Streams the agent's response as an AsyncIterable.

```APIDOC
## stream(input, config)

### Description
Streams the agent response as an AsyncIterable.

### Parameters
- **input** (any) - The input data for the agent.
- **config** (RunnableConfig) - Configuration object including thread_id, checkpoint_id, signal, streamMode, and recursionLimit.
```

--------------------------------

### threads.create(metadata?)

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Create a new conversation thread.

```APIDOC
## threads.create(metadata?)

### Description
Create a new conversation thread.

### Parameters
- **metadata** (Record<string, unknown>) - Optional - Custom metadata attached to thread (e.g., workspacePath)

### Returns
- **Promise<Thread>** - The newly created thread with auto-generated ID

### Example
```typescript
const thread = await window.api.threads.create({
  title: 'My Project',
  workspacePath: '/path/to/project'
})
console.log(`Created thread: ${thread.thread_id}`)
```
```

--------------------------------

### Define CreateAgentRuntimeOptions interface

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/types.md

Configuration parameters required for initializing an agent runtime instance.

```typescript
interface CreateAgentRuntimeOptions {
  threadId: string
  modelId?: string
  workspacePath: string
}
```

--------------------------------

### Create Assistants Table

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/database.md

Defines the schema for the assistants table, intended for future assistant template management.

```sql
CREATE TABLE IF NOT EXISTS assistants (
  assistant_id TEXT PRIMARY KEY,
  graph_id TEXT NOT NULL,
  name TEXT,
  model TEXT DEFAULT 'claude-sonnet-4-5-20250929',
  config TEXT,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL
)
```

--------------------------------

### models.list()

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Retrieves a list of all available models along with their availability status.

```APIDOC
## models.list()

### Description
List all available models with their availability status.

### Returns
- **Promise<ModelConfig[]>** - Array of model configurations

### Example
```typescript
const models = await window.api.models.list()
const available = models.filter(m => m.available)
console.log(`${available.length} models available`)
```
```

--------------------------------

### Create a new thread

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/api-reference.md

Initializes a new conversation thread with optional custom metadata.

```typescript
const thread = await window.api.threads.create({
  title: 'My Project',
  workspacePath: '/path/to/project'
})
console.log(`Created thread: ${thread.thread_id}`)
```

--------------------------------

### workspace:set

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/ipc-handlers.md

Sets the workspace path for a thread or globally and manages the file watcher.

```APIDOC
## IPC Handle: workspace:set

### Description
Sets the workspace path for a specific thread or globally. This action also triggers the file watcher if a path is set or stops it if the path is cleared.

### Parameters
- **threadId** (string) - Optional - The thread ID to bind the workspace to.
- **path** (string) - Required - The absolute path to set, or null to clear.
```

--------------------------------

### Workspace Path Error Handling

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/agent-runtime.md

Exception thrown when a workspace folder has not been selected.

```typescript
throw new Error("Workspace path is required. Please select a workspace folder before running the agent.")
```

--------------------------------

### Project Directory Structure

Source: https://github.com/langchain-ai/openwork/blob/main/_autodocs/README.md

Visual representation of the project's source code organization.

```text
openwork/
├── src/
│   ├── main/               # Electron main process
│   │   ├── agent/          # Runtime & sandbox
│   │   ├── ipc/            # IPC handlers
│   │   ├── db/             # Database
│   │   ├── checkpointer/   # State persistence
│   │   └── services/       # Utilities
│   ├── preload/            # IPC bridge
│   ├── renderer/           # React UI
│   └── config/             # Build config
├── resources/              # App icons/assets
├── package.json
└── README.md
```