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

# ClineCore

> The full Cline harness: built-in tools, sessions, approvals, scheduling, and hub support.

`ClineCore` is the full Cline harness as a programmable runtime. It gives you everything Cline ships out of the box: built-in tools for files, shell, search, and web; session persistence and message history; tool approval callbacks; local, hub, and remote backends; scheduling and automation APIs; and plugin support.

Under the hood, `ClineCore` uses the `Agent` class from `@cline/agents`. You can use `Agent` directly if you want to skip the harness and wire everything yourself: your own tools, your own persistence, your own lifecycle.

## When to use which

| Need                                               | Use         |
| -------------------------------------------------- | ----------- |
| Sessions, persistence, message history             | `ClineCore` |
| Built-in tools for files, shell, search, web fetch | `ClineCore` |
| Hub/remote runtime                                 | `ClineCore` |
| Scheduling or event automation                     | `ClineCore` |
| Multi-agent teams                                  | `ClineCore` |
| Browser-compatible or lightweight in-process agent | `Agent`     |
| Custom tools only, no built-ins                    | `Agent`     |
| Full control over persistence and lifecycle        | `Agent`     |

## ClineCore

`ClineCore` wraps runtime execution with application features:

* session manifests and message artifacts
* built-in tools
* tool approval callbacks
* local, hub, and remote backends
* automation/scheduling APIs
* optional plugin paths and extensions

```typescript theme={"system"}
import { ClineCore } from "@cline/sdk"

const cline = await ClineCore.create({
  clientName: "my-app",
  backendMode: "auto",
})

const session = await cline.start({
  prompt: "Set up GitHub Actions for this repo",
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
    systemPrompt: "You are a helpful coding assistant.",
    cwd: "/path/to/project",
    workspaceRoot: "/path/to/project",
    enableTools: true,
    enableSpawnAgent: false,
    enableAgentTeams: false,
  },
})

console.log(session.sessionId)
console.log(session.result?.finishReason)
```

### Methods

| Method                           | Purpose                             |
| -------------------------------- | ----------------------------------- |
| `ClineCore.create(options)`      | Create the runtime                  |
| `start(input)`                   | Start a session                     |
| `send({ sessionId, prompt })`    | Send a follow-up message            |
| `subscribe(listener, options?)`  | Listen to session events            |
| `list(limit?, options?)`         | List sessions with history metadata |
| `get(sessionId)`                 | Read session metadata               |
| `readMessages(sessionId)`        | Read session messages               |
| `getAccumulatedUsage(sessionId)` | Read session token/cost totals      |
| `abort(sessionId, reason?)`      | Abort current work                  |
| `stop(sessionId)`                | Stop a session                      |
| `delete(sessionId)`              | Delete a session                    |
| `dispose(reason?)`               | Clean up runtime resources          |

See [ClineCore reference](/sdk/reference/cline-core) for exact signatures.

## Backend Modes

| Mode     | Behavior                                                     |
| -------- | ------------------------------------------------------------ |
| `auto`   | Prefer a compatible local hub, otherwise use local execution |
| `hub`    | Require a compatible WebSocket hub                           |
| `remote` | Connect to a configured remote hub                           |
| `local`  | Always use local in-process execution and local storage      |

For process topology, see [Hub & Spoke](/sdk/architecture/hub-spoke).

## Session Artifacts

`ClineCore` stores session manifests and messages as files. A session result includes:

| Field          | Meaning                             |
| -------------- | ----------------------------------- |
| `sessionId`    | Session identifier                  |
| `manifest`     | Parsed session manifest             |
| `manifestPath` | Path to the session manifest JSON   |
| `messagesPath` | Path to persisted message JSON      |
| `result`       | Final `AgentResult`, when available |

## Tool Approval

Use tool policies for simple cases:

```typescript theme={"system"}
await cline.start({
  prompt: "Audit this repo",
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
    systemPrompt: "You are a helpful coding assistant.",
    cwd: process.cwd(),
    workspaceRoot: process.cwd(),
    enableTools: true,
    enableSpawnAgent: false,
    enableAgentTeams: false,
  },
  toolPolicies: {
    read_files: { autoApprove: true },
    search_codebase: { autoApprove: true },
    run_commands: { autoApprove: false },
    editor: { autoApprove: false },
  },
})
```

Use `requestToolApproval` when your application needs to decide dynamically:

```typescript theme={"system"}
const cline = await ClineCore.create({
  clientName: "my-app",
  capabilities: {
    requestToolApproval: async (request) => {
      return { approved: request.toolName !== "run_commands" }
    },
  },
})
```

For tool behavior and policies, see [Tools](/sdk/tools).

## Using Agent directly

`Agent` (also exported as `AgentRuntime`) is the stateless primitive that `ClineCore` builds on. Use it directly when you want full control or don't need the harness.

`Agent` is an alias for `AgentRuntime`. Use `Agent` when constructing from provider/model IDs. Use `AgentRuntime` when supplying a pre-built `AgentModel`.

`Agent` runs the core loop:

```txt theme={"system"}
run() or continue()
  -> model request
  -> tool calls, if any
  -> tool results
  -> repeat until complete
```

```typescript theme={"system"}
import { Agent } from "@cline/sdk"

const agent = new Agent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
  systemPrompt: "You are a helpful coding assistant.",
  tools: [myTool],
})

agent.subscribe((event) => {
  if (event.type === "assistant-text-delta") {
    process.stdout.write(event.text ?? "")
  }
})

const result = await agent.run("Review this diff")
console.log(result.outputText)
```

### Agent Methods

| Method                | Purpose                              |
| --------------------- | ------------------------------------ |
| `run(input)`          | Start a run with user input          |
| `continue(input?)`    | Continue with optional new input     |
| `abort(reason?)`      | Abort the active run                 |
| `subscribe(listener)` | Listen to `AgentRuntimeEvent` events |
| `restore(messages)`   | Replace conversation history         |
| `snapshot()`          | Read runtime state                   |

See [Agent reference](/sdk/reference/agent) for exact signatures.

### Multi-Turn Conversations

`AgentRuntime` keeps message state internally. Use `continue()` after the first run:

```typescript theme={"system"}
await agent.run("What does this project do?")
await agent.continue("Now identify risky files")
```

If you persist messages externally, restore them with `restore(messages)` before continuing.