> ## Documentation Index
> Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Ten lines to an ADE chat sidecar: createAdeChat, open a durable thread, send, listen, dispose.

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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:

```ts theme={null}
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](https://ade-app.dev/docs/sdk/permissions.md) before shipping a policy or either preset.

## React UI

```tsx theme={null}
import { AdeChat, createTheme, adaptSdkClient } from "@ade-dev/chat-ui";

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

See [Chat UI](https://ade-app.dev/docs/sdk/chat-ui.md) for labels, theming, and the standalone components.

## Inject your tools

```ts theme={null}
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](https://ade-app.dev/docs/sdk/mcp.md) before you tell users that only your tools are loaded.** Strict isolation is enforced only on Claude.

## Next

> [card] [Threads](https://ade-app.dev/docs/sdk/threads.md)
>
> Steer, interrupt, switch models, export.

> [card] [Runtime](https://ade-app.dev/docs/sdk/runtime.md)
>
> Embedded profile, watchdog, pidfile reclaim.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.