Skip to content
Newquantumcoderxyz v2 is now available

SDK

Type-safe JS client for quantumcoderxyz server.

The quantumcoderxyz JS/TS SDK provides a type-safe client for interacting with the server. Use it to build integrations and control quantumcoderxyz programmatically.

Learn more about how the server works. For examples, check out the projects built by the community.


Install

Install the SDK from npm:

Terminal window
npm install @quantumcoderxyz-ai/sdk

Create client

Create an instance of quantumcoderxyz:

import { createquantumcoderxyz } from "@quantumcoderxyz-ai/sdk"
const { client } = await createquantumcoderxyz()

This starts both a server and a client

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
config Config Configuration object {}

Config

You can pass a configuration object to customize behavior. The instance still picks up your quantumcoderxyz.json, but you can override or add configuration inline:

import { createquantumcoderxyz } from "@quantumcoderxyz-ai/sdk"
const quantumcoderxyz = await createquantumcoderxyz({
hostname: "127.0.0.1",
port: 4096,
config: {
model: "anthropic/claude-sonnet-5-5",
},
})
console.log(`Server running at ${quantumcoderxyz.server.url}`)
quantumcoderxyz.server.close()

Client only

If you already have a running instance of quantumcoderxyz, you can create a client instance to connect to it:

import { createquantumcoderxyzClient } from "@quantumcoderxyz-ai/sdk"
const client = createquantumcoderxyzClient({
baseUrl: "http://localhost:4096",
})

Options

Option Type Description Default
baseUrl string URL of the server None; set explicitly
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 return false

Types

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

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

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


Errors

By default, HTTP errors are returned in result.error. Set throwOnError: true to throw them instead. Network errors can still throw regardless of this option.

try {
await client.session.get({ path: { id: "invalid-id" }, throwOnError: true })
} catch (error) {
console.error("Failed to get session:", error)
}

Structured Output

You can request structured JSON output from the model by specifying a format with a JSON schema. The model will use a StructuredOutput tool to return validated JSON matching your schema.

Structured output is only available on the client exported from @quantumcoderxyz-ai/sdk/v2. This client takes flat parameters instead of path and body objects.

Basic Usage

import { createquantumcoderxyzClient } from "@quantumcoderxyz-ai/sdk/v2"
const client = createquantumcoderxyzClient({ baseUrl: "http://localhost:4096" })
const result = await client.session.prompt(
{
sessionID: sessionId,
parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
format: {
type: "json_schema",
schema: {
type: "object",
properties: {
company: { type: "string", description: "Company name" },
founded: { type: "number", description: "Year founded" },
products: {
type: "array",
items: { type: "string" },
description: "Main products",
},
},
required: ["company", "founded"],
},
},
},
{ throwOnError: true },
)
// Access the structured output
console.log(result.data.info.structured)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

Output Format Types

Type Description
text Default. Standard text response (no structured output)
json_schema Returns validated JSON matching the provided schema

JSON Schema Format

When using type: 'json_schema', provide:

Field Type Description
type 'json_schema' Required. Specifies JSON schema mode
schema object Required. JSON Schema object defining the output structure
retryCount number Optional. Number of validation retries (default: 2)

Error Handling

If the model fails to produce valid structured output after all retries, the response will include a StructuredOutputError:

if (result.data.info.error?.name === "StructuredOutputError") {
console.error("Failed to produce structured output:", result.data.info.error.data.message)
console.error("Attempts:", result.data.info.error.data.retries)
}

Best Practices

  1. Provide clear descriptions in your schema properties to help the model understand what data to extract
  2. Use required to specify which fields must be present
  3. Keep schemas focused - complex nested schemas may be harder for the model to fill correctly
  4. Set appropriate retryCount - increase for complex schemas, decrease for simple ones

APIs

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


Global

global.health() is only available on the @quantumcoderxyz-ai/sdk/v2 client.

Method Description Response
global.health() Check server health and version { healthy: true, version: string }

Examples

import { createquantumcoderxyzClient } from "@quantumcoderxyz-ai/sdk/v2"
const client = createquantumcoderxyzClient({ baseUrl: "http://localhost:4096" })
const health = await client.global.health({ throwOnError: true })
console.log(health.data.version)

App

MethodDescriptionResponse
app.log()Write a log entryboolean
app.agents()List all available agentsAgent[]

Examples

// Write a log entry
await client.app.log({
body: {
service: "my-app",
level: "info",
message: "Operation completed",
},
})
// List available agents
const agents = await client.app.agents()

Project

MethodDescriptionResponse
project.list()List all projectsProject[]

Examples

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

Path

MethodDescriptionResponse
path.get()Get current pathPath

Examples

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

Config

MethodDescriptionResponse
config.get()Get config infoConfig
config.providers()List providers and default models{ providers: Provider[], default: { [key: string]: string } }

Examples

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

Sessions

MethodDescriptionNotes
session.list()List sessionsReturns Session[]
session.get({ path })Get sessionReturns Session
session.children({ path })List child sessionsReturns Session[]
session.create({ body })Create sessionReturns Session
session.delete({ path }) Delete session Returns boolean
session.update({ path, body })Update session propertiesReturns Session
session.init({ path, body }) Analyze app and create AGENTS.md Returns boolean
session.abort({ path }) Abort a running session Returns boolean
session.share({ path }) Share session Sharing has been discontinued; this endpoint returns an error
session.unshare({ path })Clear a stored share linkReturns Session
session.summarize({ path, body }) Summarize session Returns boolean
session.messages({ path })List messages in a sessionReturns { info: Message, parts: Part[]}[]
session.message({ path })Get message detailsReturns { info: Message, parts: Part[]}
session.prompt({ path, body }) Send prompt message Returns { info, parts }. body.noReply: true adds context without an AI response. For structured output, use the /v2 client
session.command({ path, body })Send command to sessionReturns { info: AssistantMessage, parts: Part[]}
session.shell({ path, body })Run a shell commandReturns AssistantMessage
session.revert({ path, body })Revert a messageReturns Session
session.unrevert({ path })Restore reverted messagesReturns Session
postSessionByIdPermissionsByPermissionId({ path, body }) Respond to a permission request Returns boolean

Examples

// Create and manage sessions
const session = await client.session.create({
body: { title: "My session" },
throwOnError: true,
})
const sessions = await client.session.list()
// Send a prompt message
const result = await client.session.prompt({
path: { id: session.data.id },
body: {
model: { providerID: "anthropic", modelID: "claude-sonnet-5-5" },
parts: [{ type: "text", text: "Hello!" }],
},
})
// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
path: { id: session.data.id },
body: {
noReply: true,
parts: [{ type: "text", text: "You are a helpful assistant." }],
},
})

Files

MethodDescriptionResponse
find.text({ query })Search for text in filesArray of match objects with path, lines, line_number, absolute_offset, submatches
find.files({ query })Find files and directories by namestring[] (paths)
find.symbols({ query })Find workspace symbolsSymbol[]
file.read({ query })Read a fileFileContent
file.status({ query? })Get status for tracked filesFile[]

The root client’s find.files supports these optional query fields:

  • dirs: "false" to search files only; otherwise directories are included
  • directory: override the project root for the search

The /v2 client additionally supports type ("file" or "directory") and limit (1–200), using flat parameters.


Examples

// Search and read files
const textResults = await client.find.text({
query: { pattern: "function.*quantumcoderxyz" },
})
const files = await client.find.files({
query: { query: ".ts", dirs: "false" },
})
const paths = await client.find.files({
query: { query: "packages", dirs: "true" },
})
const content = await client.file.read({
query: { path: "src/index.ts" },
})

TUI

Method Description Response
tui.appendPrompt({ body }) 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({ body }) Execute a command boolean
tui.showToast({ body }) Show toast notification boolean

Examples

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

Auth

Method Description Response
auth.set({ ... }) Set authentication credentials boolean

Examples

await client.auth.set({
path: { id: "anthropic" },
body: { 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)
}