Public beta. APIs may change before general availability.

For the full reference, see the root README. The exported TypeScript types are the canonical contract.

Capability map

New here? The exported TypeScript types are the discovery front-door and the canonical contract — every harness primitive with its import path, signature and JSDoc example (compactTranscript, buildRepoMap, isTransientError, @theokit/sdk/persistence, ...), surfaced by your editor.

Two references ship inside the package — no network, pinned to the version you installed, and both GENERATED from the built declarations so they cannot drift from what you actually got:

node_modules/@theokit/sdk/docs/harness-capability-map.md   # every public symbol + its exact import specifier
node_modules/@theokit/sdk/docs/error-codes.md              # every `code` an error can carry, and where it is raised

If you are an agent: read the capability map before writing an import. Several symbols are reachable from more than one specifier, and a class emitted into a subpath entry is a DISTINCT nominal type from the one in the root bundle — import a symbol and everything you pass it to from the same specifier, or the call fails on a private field.

Agents that consume documentation should prefer the machine-readable corpora on the docs site (llmstxt.org convention): llms.txt (curated index) and llms-full.txt (every page inlined).

Install

npm install @theokit/sdk

Quick start

import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey: process.env.THEOKIT_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});

const run = await agent.send("Summarize what this repository does");

for await (const event of run.stream()) {
  console.log(event);
}

Native Claude Code sessions

A local agent's conversation is a native Claude Code .jsonl transcript on disk — there is no proprietary session store. Point baseDir at ~/.claude and the Claude Code CLI can --continue a session your agent wrote:

const agent = await Agent.create({
  apiKey: process.env.THEOKIT_API_KEY!,
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: process.cwd(), baseDir: "~/.claude" },
});
// After runs finish, `claude --continue` picks up the same session on disk.

Extended-thinking --continue is out of scope for now (thinking signatures are written but dropped on read — issue #122). See the exported session-persistence types for the full contract.

Memory

Durable facts live under <cwd>/.theokit/memory/. To keep several users of one agent app apart, give each agent a userId; each user then gets their own partition (.theokit/memory/users/<userId>/) for facts, index and session summaries:

const alice = await Agent.create({ memory: { enabled: true, userId: "alice" } });
const bob = await Agent.create({ memory: { enabled: true, userId: "bob" } });
// Facts recorded by alice are never recalled or returned by memory_search for bob.

userId must match [a-z0-9][a-z0-9-_]*; other values (such as ../x) are rejected.

Plugins

listWorkspacePlugins(cwd, { compatSources }) lists the plugins an agent opened on cwd would load (name, folder, manifest path and format), using the same discovery and manifest code as the runtime and without running plugin code. It reads the project's .theokit/plugins plus the plugin roots of the declared compatSources, never ~/.theokit/plugins.

import { listWorkspacePlugins } from "@theokit/sdk";

const plugins = await listWorkspacePlugins(process.cwd(), { compatSources: ["claude-code"] });

Schedule with cron

import { Cron } from "@theokit/sdk";

await Cron.create({
  cron: "0 9 * * *",
  timezone: "America/Sao_Paulo",
  message: "Summarize yesterday's commits",
  agent: {
    apiKey: process.env.THEOKIT_API_KEY!,
    model: { id: "composer-2" },
    local: { cwd: process.cwd() },
  },
});

await Cron.start();   // required for local jobs to fire

Two runtimes: local (in-process scheduler — fires while the host process is alive) and cloud (Theo PaaS schedules server-side). See the exported Cron types for the full contract.

Status

The full contract is defined by the exported TypeScript types; see CHANGELOG.md for the release history.

License

MIT — see LICENSE.