Client

createClient(opts)

Creates the root client. All SDK operations start here.

import { createClient } from "swarmlord";

const client = createClient({
    apiKey: process.env.SWARMLORD_API_KEY!,
});

Parameters

• apiKey string optional — Your swarmlord API key. Get one at swarmlord.ai. If omitted, it will read process.env.SWARMLORD_API_KEY.
• baseUrl string optional — API base URL. Override for self-hosted or development. Defaults to process.env.SWARMLORD_URL or "https://api.swarmlord.ai".

---

Methods

client.agent(nameOrConfig)

Create an agent handle. Everything flows from agents — sessions, tasks, and schedules.

// Built-in agent with all tools enabled
const build = client.agent("build");

// Custom configuration with specific tools
const reviewer = client.agent({
    model: "anthropic/claude-sonnet-4-20250514",
    instructions: ["Focus on security and correctness"],
    tools: {
        bash: true,
        read: true,
        grep: true,
        glob: true,
        edit: false,
        write: false,
    },
});

• nameOrConfig string | AgentConfig required — Agent name ("build", "plan", "explore", "general") or a full configuration object.

AgentConfig

• name string — Base agent type. Defaults to "build".
• model string — Model ID in provider/model format (e.g. anthropic/claude-sonnet-4-20250514).
• instructions string[] — Additional instructions appended to the agent's system prompt.
• temperature number — Sampling temperature.
• tools Record<string, boolean> — Enable or disable specific tools. Keys are tool names, values are true (enabled) or false (disabled). Unmentioned tools keep their default state.
• permission PermissionConfig — Low-level permission rules. Prefer tools for tool-level control.
• config Config — Advanced configuration including compaction settings and command templates.

Returns: AgentHandle

---

client.session(id)

Resume an existing session by ID. Use this when you saved a session ID and want to continue the conversation from another process.

const session = client.session("session-id");
await session.send("Pick up where we left off");

• id string required — Session ID to resume.

Returns: SessionHandle

---

client.task(sessionId)

Resume a task handle by its session ID. Use this to check on a task from another process.

const task = client.task("task-session-id");
const result = await task.result();

• sessionId string required — The session ID of the task.

Returns: TaskHandle

---

client.schedule(id)

Resume a schedule handle by ID.

const schedule = client.schedule("schedule-id");
await schedule.pause();

• id string required — Schedule ID.

Returns: ScheduleHandle

---

client.listSessions(opts?)

List all sessions for the authenticated user.

const sessions = await client.listSessions({ limit: 20, archived: false });

• limit number — Maximum number of sessions to return.
• archived boolean — Whether to include archived sessions.

Returns: Promise<SessionInfo[]>

---

client.listSchedules()

List all schedules for the authenticated user.

const schedules = await client.listSchedules();

Returns: Promise<ScheduleInfo[]>

---

client.getConfig()

Get the user-level configuration.

const config = await client.getConfig();

Returns: Promise<Config>

---

client.updateConfig(config)

Merge-update the user-level configuration.

await client.updateConfig({
    model: "anthropic/claude-sonnet-4-20250514",
    instructions: ["Always write tests"],
});

• config Partial<Config> required — Configuration fields to merge.

Returns: Promise<void>

---

client.listModels()

List available models (proxied from the provider).

const { data: models } = await client.listModels();
for (const m of models) {
    console.log(`${m.id} — ${m.name}`);
}

Returns: Promise<{ data: ProviderModel[] }>