SDK

JS SDK for the codeflow server.

The codeflow JS/TS SDK provides a type-safe client for interacting with the codeflow server. You can use it to build custom integrations and control codeflow programmatically.

Learn more about how the codeflow server works.

Note: Many API endpoints now require a directory query parameter to specify the working directory context.

Install

Install the SDK from npm:

npm install @codeflow-ai/sdk

Create client

Create a client instance to connect to your codeflow server:

import { createcodeflowClient } from "@codeflow-ai/sdk"

const client = createcodeflowClient({
  baseUrl: "http://localhost:4096",
})

Options

Option	Type	Description	Default
`baseUrl`	`string`	URL of the codeflow server	`http://localhost:4096`
`fetch`	`function`	Custom fetch implementation	`globalThis.fetch`
`parseAs`	`string`	Response parsing method	`auto`
`responseStyle`	`string`	Return style: `data` or `fields`	`fields`
`throwOnError`	`boolean`	Throw errors instead of returning	`false`

Start server

You can also programmatically start an codeflow server:

import { createcodeflowServer } from "@codeflow-ai/sdk"

const server = await createcodeflowServer({
  hostname: "127.0.0.1",
  port: 4096,
})

console.log(`Server running at ${server.url}`)

server.close()

Options

Option	Type	Description	Default
`hostname`	`string`	Server hostname	`127.0.0.1`
`port`	`number`	Server port	`4096`
`signal`	`AbortSignal`	Abort signal for cancellation	`undefined`
`timeout`	`number`	Timeout in ms for server start	`5000`

Types

The SDK includes TypeScript definitions for all API types. Import them directly:

import type { Session, Message, Part } from "@codeflow-ai/sdk"

All types are generated from the server’s OpenAPI specification and available in the types file.

Errors

The SDK throws typed errors that you can catch and handle:

try {
  const session = await client.session.get({ id: "invalid-id" })
} catch (error) {
  console.error("Failed to get session:", error.message)
}

APIs

The SDK exposes all server APIs through a type-safe client interface.

App

Method	Description	Response
`app.log()`	Write a log entry	`boolean`
`app.agents()`	List all available agents	`Agent[]`

Examples

// Log an entry
await client.app.log({
  service: "my-app",
  level: "info",
  message: "Operation completed",
})

// List available agents
const agents = await client.app.agents()

Project

Method	Description	Response
`project.list()`	List all projects	`Project[]`
`project.current()`	Get current project	`Project`

Examples

// List all projects
const projects = await client.project.list()

// Get current project
const currentProject = await client.project.current()

Path

Method	Description	Response
`path.get()`	Get current path	`Path`

Examples

// Get current path information
const pathInfo = await client.path.get()

Config

Method	Description	Response
`config.get()`	Get config info	`Config`
`config.providers()`	List providers and default models	`{ providers:` `Provider[], default: { [key: string]: string } }`

Examples

const config = await client.config.get()
const { providers, default: defaults } = await client.config.providers()

Sessions

Method	Description	Notes
`session.list()`	List sessions	Returns `Session[]`
`session.get({ id })`	Get session	Returns `Session`
`session.children({ id })`	List child sessions	Returns `Session[]`
`session.create({ parentID?, title? })`	Create session	Returns `Session`
`session.delete({ id })`	Delete session	Returns `boolean`
`session.update({ id, title? })`	Update session properties	Returns `Session`
`session.init({ id, messageID, providerID, modelID })`	Analyze app and create `AGENTS.md`	Returns `boolean`
`session.abort({ id })`	Abort a running session	Returns `boolean`
`session.share({ id })`	Share session	Returns `Session`
`session.unshare({ id })`	Unshare session	Returns `Session`
`session.summarize({ id, providerID, modelID })`	Summarize session	Returns `boolean`
`session.messages({ id })`	List messages in a session	Returns `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ id, messageID })`	Get message details	Returns `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ id, ...promptInput })`	Send prompt message	Returns `Message`
`session.shell({ id, agent, command })`	Run a shell command	Returns `Message`
`session.revert({ id, messageID, partID? })`	Revert a message	Returns `Session`
`session.unrevert({ id })`	Restore reverted messages	Returns `Session`
`session.permissions.respond({ id, permissionID, response })`	Respond to a permission request	Returns `boolean`

Examples

// Create and manage sessions
const session = await client.session.create({ title: "My session" })
const sessions = await client.session.list()

// Send messages
const message = await client.session.prompt({
  id: session.id,
  model: {
    providerID: "anthropic",
    modelID: "claude-3-5-sonnet-20241022",
  },
  parts: [{ type: "text", text: "Hello!" }],
})

Files

Method	Description	Response
`find.text({ pattern })`	Search for text in files	Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Find files by name	`string[]` (file paths)
`find.symbols({ query })`	Find workspace symbols	`Symbol[]`
`file.read({ path })`	Read a file	`{ type: "raw" \| "patch", content: string }`
`file.status()`	Get status for tracked files	`File[]`

Examples

// Search and read files
const textResults = await client.find.text({ pattern: "function.*codeflow" })
const files = await client.find.files({ query: "*.ts" })
const content = await client.file.read({ path: "src/index.ts" })

Logging

Method	Description	Response
`log.write({ service, level, message, extra? })`	Write log entry	`boolean`

Examples

await client.log.write({
  service: "my-app",
  level: "info",
  message: "Operation completed",
})

Agents

Method	Description	Response
`agent.list()`	List all available agents	`Agent[]`

Examples

const agents = await client.agent.list()

TUI

Method	Description	Response
`tui.appendPrompt({ text })`	Append text to the prompt	`boolean`
`tui.openHelp()`	Open the help dialog	`boolean`
`tui.openSessions()`	Open the session selector	`boolean`
`tui.openThemes()`	Open the theme selector	`boolean`
`tui.openModels()`	Open the model selector	`boolean`
`tui.submitPrompt()`	Submit the current prompt	`boolean`
`tui.clearPrompt()`	Clear the prompt	`boolean`
`tui.executeCommand({ command })`	Execute a command	`boolean`
`tui.showToast({ title?, message, variant })`	Show toast notification	`boolean`
`tui.control.next()`	Wait for the next control request	Control request object
`tui.control.response({ body })`	Respond to a control request	`boolean`

Examples

// Control TUI interface
await client.tui.appendPrompt({ text: "Add this to prompt" })
await client.tui.showToast({
  message: "Task completed",
  variant: "success",
})

Auth

Method	Description	Response
`auth.set({ id, ...authData })`	Set authentication credentials	`boolean`

Examples

await client.auth.set({
  id: "anthropic",
  type: "api",
  key: "your-api-key",
})

Events

Method	Description	Response
`event.subscribe()`	Server-sent events stream	Server-sent events stream

Examples

// Listen to real-time events
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Event:", event.type, event.properties)
}