Quickstart

import { createAdeChat } from "@ade-dev/sdk";

const ade = await createAdeChat({ home: "./.ade-embed" });
const thread = await ade.threads.open("support", {
  provider: "claude",
  model: "claude-sonnet-4-5",
});
thread.on("event", (envelope) => console.log(envelope.event.type));
await thread.send("Summarise today's incidents");

Reopening "support" after a restart resumes the same conversation. send() resolves when the runtime accepts the turn, not when the reply finishes — watch thread.on("status") / thread.on("event") before treating the thread as idle. Call ade.dispose() when the host shuts down.

Check the machine

const report = await ade.doctor();
if (!report.ok) console.error(report);

const status = await ade.providers.status();

doctor() reports sdkVersion (this package) and the runtime binary version separately — they ship on different cadences. providers.status() returns a map of provider id to { installed, binaryPath, version, authenticated, installCommand, loginCommand, source, … }. Read source first. "probed" means the runtime resolved the binary and read the credential files, so those fields are measurements; "derived" means the runtime is older than the probe RPC and everything comes from the model catalog, so a UI should say “not detected” rather than “not installed”. providers.refresh() bypasses the runtime’s 60-second probe cache — that is the “I just installed it” button. Provider credentials live in the provider’s own config (~/.claude, ~/.codex, ~/.cursor, …), not under home.

Permissions

const thread = await ade.threads.open("ops", {
  provider: "claude",
  model: "claude-sonnet-4-5",
  permissions: "always-allow",
});

"always-allow" maps to each provider’s full-auto create args — bypassPermissions on Claude, danger-full-access on Codex. "default" leaves each provider’s own handling in place, and that is not one behavior: on Claude, ADE installs no gate at all and the Agent SDK decides non-interactively; on Codex, an approval request parks the turn until something answers it. For anything in between, pass a policy instead of a preset:

const thread = await ade.threads.open("ops", {
  provider: "claude",
  model: "claude-sonnet-4-5",
  permissions: {
    allowedTools: ["mcp:catalog:*", "Read"],
    deniedTools: ["Bash"],
    fallback: "deny", // never asks, so a turn can never park
  },
});

On Claude a deny fallback is stronger than “never asks”: every mutating built-in the policy does not name is removed from the model’s catalog, and MCP is scoped to the servers the policy names — including servers you supplied yourself in mcpServers. Name them in the policy to use them. Read Permissions and approvals before shipping a policy or either preset.

React UI

import { AdeChat, createTheme, adaptSdkClient } from "@ade-dev/chat-ui";

<AdeChat
  client={adaptSdkClient(ade)}
  threadKey="support"
  theme={createTheme({ accent: "#7c5cff", background: "#0e0f13" })}
/>;

See Chat UI for labels, theming, and the standalone components.

Inject your tools

const thread = await ade.threads.open("ops", {
  provider: "claude",
  model: "claude-sonnet-4-5",
  mcpServers: {
    docs: { type: "http", url: "https://mcp.example/mcp" },
  },
});

if (!thread.mcpCapability) {
  console.warn("runtime reported no MCP capability; treat the tool-surface guarantee as unverified");
} else if (thread.mcpCapability.strictRequested && thread.mcpCapability.level !== "enforced") {
  console.warn(thread.mcpCapability.residual);
}

Read MCP servers before you tell users that only your tools are loaded. Strict isolation is enforced only on Claude.

Threads

Steer, interrupt, switch models, export.

Runtime

Embedded profile, watchdog, pidfile reclaim.

Start here

Guides

Reference

Quickstart

Check the machine

Permissions

React UI

Inject your tools

Next

Threads

Runtime

​Check the machine

​Permissions

​React UI

​Inject your tools

​Next

Threads

Runtime

Check the machine

Permissions

React UI

Inject your tools

Next