cline/docs/sdk/clinecore.mdx

---
title: "ClineCore"
sidebarTitle: "ClineCore"
description: "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
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
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
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
run() or continue()
  -> model request
  -> tool calls, if any
  -> tool results
  -> repeat until complete
```

```typescript
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
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.