Plugin code never runs on a host's main thread. The in_process execution
mode is removed along with the fallback to it when a host shipped no
worker bootstrap: that fallback turned a loud "plugins do not load" into
a silent "plugins run inside the hub", which is the failure class behind
CLINE_PLUGIN_MODE is now `worker` (default) or `sandbox`; `in_process` is
no longer honoured.
A host that ships no bootstrap for the requested mode fails every plugin
load with PluginBootstrapMissingError, which names
CLINE_PLUGIN_BOOTSTRAP_PATH, so the cause shows in `cline config tools`,
`cline hub plugins`, and session-start warnings instead of plugins
silently dropping. The SSH remote helper is such a host today: it is
uploaded as a single file with no bootstrap beside it, so plugin tools
are reported missing there instead of running inside the remote hub.
With no plugin code in the host, the registry loses the jiti import
path, per-session module copies, AsyncLocalStorage call scoping, the
__clinePluginHost shim, and stack attribution of uncaught errors. The
daemon's uncaughtException / unhandledRejection handlers are fatal
again. The in-process registry tests that cover retained behaviour
(hook timeouts and error modes, multi-session notices, capability
checks, discovery and settings issues, command/rule/builder timeouts,
host-rejected registrations, timeout overrides, reload) move to the
worker suite.
How each host obtains the bootstrap and the SDK packages plugins
import, and embedding them in compiled binaries, is left to follow-ups.
* feat(core): load plugins in the hub process and surface plugin errors
Plugins now load in-process through one registry per process instead of a
node/bun subprocess. The compiled CLI and the hub it starts no longer need a
runtime on PATH, and plugins can use the Bun global under the Bun-built hub.
The subprocess sandbox stays available with CLINE_PLUGIN_MODE=sandbox.
The registry wraps import, setup, every hook, tool, and command call with
timeouts and error capture, and tracks loading/ready/degraded/failed/disabled
per plugin with the last error's phase, message, stack, and counts. A failing
plugin no longer silently drops its tools:
- session.create takes a `plugins` policy shaped like toolPolicies, and its
reply and session.created event carry `pluginIssues`
- failures after start (setup and hooks run on the first turn) reach each
affected session as a status notice
- the hub answers plugins.list/status/reload and broadcasts
plugin.status_changed; `cline hub plugins [--reload]` wraps them
- the daemon marks a plugin failed instead of shutting down when an uncaught
error's stack points into it
- the CLI prints a warning naming the plugin and error, and
`cline config tools --json` lists failed plugins as plugin_failure entries
Setup and tool contexts gain cwd and emitEvent; __clinePluginHost keeps
working as a shim. Compiled binaries fall back to jiti/static when babel is
not on disk next to them.
* fix(core): give each session its own copy of every plugin module
Plugins written for the per-session sandbox keep state at module level. The
cline-monitor plugin, for example, builds one plugin object per import and
throws "Create a separate monitor plugin handle for each session" on a second
setup(). Sharing one imported copy across hub sessions broke it on the
second session.
The registry now hands each session its own copy: the first session claims
the copy imported at startup, and later ones re-evaluate the module while
reusing jiti's transform cache (about 180ms for cline-monitor instead of
2.8s with no cache).
A setup() failure now costs only the session it happened in: other sessions
keep their copies, the next session tries again, and a successful setup
returns the status to ready. Import failures, attributed uncaught errors, and
repeated hook/tool failures still turn the plugin off for every session.
* docs(sdk): document the plugin hooks that exist and how hook failures behave
The Hook Stages list (snake_case stages such as tool_call_before) and the
Hook Policies table (mode, retries, queueLimit, maxConcurrency) described no
code: plugin hooks are the seven runtime hooks, and there is no per-hook
policy object. Replace both with the real hooks, what each can return, and
how hookErrorMode and the 3-second hook timeout apply.
* fix(core): report failed plugins as failed in settings
Settings marked a plugin "failed" only when the plugin tool report had no
entry for it. The report now lists failed plugins with their state, so they
showed as "available" (desktop Extensions page and other core settings
hosts). Use the reported state, and fill loadError with the failing phase
and message so the reason is visible.
Also tell only the calling session about a per-session setup failure;
other sessions' copies still work. Keep the hub log line's own message
instead of letting the plugin error text overwrite it.
* fix(core): address plugin registry review findings
Reload and generations: each session copy records the generation (import)
it came from. A reload starts a new generation without invalidating older
copies, so running sessions keep working. Failures and blocking are counted
per generation, so a broken reload cannot turn off copies that still work,
and an old copy's failures cannot change the current status. A stray error
attributed by stack turns off every live generation, since a stack cannot
tell copies of one file apart.
Sandbox mode: the hub daemon no longer preloads plugins in sandbox mode,
and tool listing and MCP settings sync inspect plugins through the sandbox.
The session plugin policy now applies in sandbox mode: paths whose file
name the policy turns off never reach the sandbox, and plugins matched only
by their exported name are dropped after import.
Calls: commands, rule content, and message builders go through the same
guarded path as hooks and tools (timeout, error capture, failure count), and
calls into a copy that is turned off, failed setup, or whose session ended
are refused. A failing rule contributes no text and a failing message
builder leaves messages unchanged.
Cleanup: ctx.onDispose registers per-session cleanup. Timers a copy creates
while its own code runs, including at import, are tracked and cleared when
the session releases the copy; host callbacks given to plugins run outside
that scope so host timers are never cleared with them. Release runs on
session stop and dispose, and now also when building the session runtime
fails. The automation-events example uses ctx.onDispose.
Registrations: automation event types are validated while setup runs. If
the host still rejects a registration on commit, the copy's setup is
recorded as failed and the error is rethrown so the partial registrations
are discarded.
Also: forward importTimeoutMs, hookTimeoutMs, and contributionTimeoutMs to
the in-process registry per session; key the plugin tool inspection cache on
registry status; keep the module copy imported by preload for the first
session; report settings-disabled plugins a session would use as issues
with reason "settings".
* fix(core): keep this bindings and route import-time plugin events
- Timer tracking forwards the runtime's this (the timer handle in Node and
Bun) to plugin callbacks.
- Plugin methods keep their receiver: rule content, message builders,
command handlers, and setup() are called on their own objects, including
setup() in the existing in-process loader.
- Each plugin copy owns one async scope from import onward. Claiming the
copy for a session fills in that scope's session id and event callback,
so events emitted by work the module started at import reach the session.
- Each generation tracks its own health, so an older copy's first failure
after a reload is reported to its sessions even though the status shows
the reloaded generation.
* fix(core): bind plugin changes to sessions started afterwards
Plugins are bound to a session when it starts; added, edited, or reloaded
plugins reach only sessions started afterwards. Change detection used the
entry file's mtime and size, which missed edits to files the entry imports
(common for package plugins) and same-size edits within one clock tick, so
the next new session could claim a stale preloaded copy.
Detect changes with a content fingerprint of the entry file and every file
it reaches through relative static imports, for the registry, the plugin
tool inspection cache, and the plugin command service. Add a bootstrap test
that a session started before a plugin is added or changed keeps its
original tools even when its setup runs afterwards, and a registry test for
a change outside the entry file.
* fix(core): include side-effect imports in plugin change fingerprints
The fingerprint only followed `from`, `import()`, and `require()`
specifiers, so a fix to a file the entry imports only for side effects
(`import "./setup.js"`) left the fingerprint unchanged and new sessions kept
getting the failed entry.
Scan statement-level side-effect imports for the fingerprint only. They are
kept out of the dependency preflight, where a loose match on text inside a
string (`'run import "x" first'`) would reject a valid plugin.
* fix(core): retry failed plugin imports on a backoff
Change detection follows static and side-effect relative imports, but a
broken import can also be fixed where no fingerprint sees it: a dynamically
imported file, a file behind a block comment, or a dependency installed in
node_modules. Such plugins stayed failed until an explicit reload.
Retry a plugin whose import failed when a session starts, at most every 30
seconds, even if no change was detected. A broken plugin costs at most one
extra import attempt per 30 seconds, bounded by the import timeout.
Replace the SHA-1 fingerprint with a non-cryptographic checksum; it only has
to notice edits to plugin source.
* feat(desktop): show plugin failures in the chat
Plugin failures reached the desktop webview only as core logs written to the
devtools console. Show them as status lines in the chat:
- session start returns `pluginWarnings` for plugins the session asked for
but could not load, and the webview adds one status line per warning
- plugin notices that arrive later on the session stream (setup and hooks
run on the first turn) carry `metadata.pluginIssue`; the webview adds
those as status lines too, while other core logs stay out of the
transcript
* fix(desktop): keep plugin warnings when saved history reloads
Finishing a turn replaces the live transcript with saved history, which
never contains plugin warnings (they come from the start reply and stream
notices), so the explanation of a missing plugin disappeared after the first
turn. Carry the session's live plugin-warning lines into canonical history
at their original position by time.
* refactor(core): simplify the in-process plugin registry (#14999)
* refactor(core): simplify the plugin registry
Drop the pieces added in review rounds that cost more than they buy:
- Global timer tracking. It monkeypatched setTimeout/setInterval/
setImmediate and their clear* counterparts on globalThis for the whole
host process (the hub, the CLI, and the shared VS Code extension host),
and attributed timers by async scope, so a host callback invoked from
inside a plugin call had its timers cancelled when the session released
its plugin copy. Plugins stop what they start in ctx.onDispose, which
stays.
- Plugin generations and per-generation health. Blocking and consecutive
failures are counted per plugin again; a re-import (reload or source
change) resets them. Running sessions keep their copies callable unless
the plugin is turned off, so a broken reload fails closed for them.
- Automatic retry of failed imports on a 30 s backoff, and the side-effect
import scan in the change fingerprint. plugins.reload covers changes the
fingerprint cannot see.
- The duplicated registerAutomationEventType validation; the commit
try/catch already records a host-rejected registration as a setup
failure.
* refactor(core): do not apply the session plugin policy in sandbox mode
The sandbox is an opt-in escape hatch and the per-session policy is new;
filtering sandbox results by file-derived and exported names added two
passes nobody needs yet. The policy is documented as in-process only.
* revert(desktop): drop the live plugin-warning merge into saved history
Reverts 90df99574. The merge re-inserted unpersisted warning lines by
timestamp after every history reload and still lost them on reopen.
* fix(core): keep plugin status consistent across a reload and a late block
- A re-import now resets `blocked` and the failure count only after it
succeeds, so calls that hit the failure threshold while the import was in
flight cannot leave the plugin blocked under a `ready` status.
- Sessions are notified when a plugin is turned off even if its status
already read `failed` from another session's setup failure.
- Docs: say which relative imports the change fingerprint follows, that a
failed reload turns the plugin off for running sessions too, and that the
sandbox ignores the session plugin policy.
* fix(core): attribute stray plugin errors by the plugin's real path too
Module resolution follows symlinks and, on Windows, expands 8.3 short names
(the GitHub runner's temp dir is C:\Users\RUNNER~1\...), so a stack frame can
spell the plugin path differently from the configured one and the uncaught
error was never attributed. Match the realpath as well, and compare with
normalized separators and case on win32. Fixes the Windows-only failure of
"attributes a stray error to the plugin whose file is in its stack", which
also fails on the base branch.
* fix(core): match both realpath spellings when attributing plugin errors
On Windows fs.realpathSync keeps 8.3 short names while realpathSync.native
expands them, and module resolvers differ in which they use. Accept either
so the stack frame matches regardless.
* fix(core): do not count a stale plugin copy's failures against the reloaded module
Each copy is stamped with the entry's import counter. After a reload (or a
source change), failures from copies of the previous import are reported to
their own session but no longer bump the error counts, block the plugin, or
change its status, so a session still running a broken copy cannot turn off
the fixed plugin for everyone else. The pre-review registry had this guard
via its generation number; the simplification dropped it.
* fix(core): don't let a stale session import turn off a reloaded plugin
A session's copy import that failed after plugins.reload (or a source change)
had already re-imported the plugin was recorded against the current module:
the catch around claimInstance had no import identity, so recordFailure
blocked the plugin and dropped the freshly loaded copy for every session.
Capture the entry's importId before claiming. If it changed by the time the
import fails, report the failure to that session only and leave the current
module's status alone, matching how stale copies' call failures are handled.
* fix(desktop): don't duplicate a queued prompt behind a plugin start warning
Session start appends plugin warnings after the optimistic user bubble. The
chat_queued_prompt_start handler searched backward for that bubble and
stopped at the first non-user row, so it hit the warning, missed the bubble,
and appended the prompt a second time until saved history replaced it.
Skip plugin warning rows in that search.
* feat(core): default a worker-thread transport for isolated plugins (#15034)
* feat(core): add a worker-thread transport for isolated plugins
CLINE_PLUGIN_MODE=worker runs each session's plugins in a worker thread
inside the host runtime. It reuses the subprocess sandbox protocol and
bootstrap, so it needs no node/bun executable on PATH and works from the
compiled CLI and hub. terminate() stops a plugin stuck in a synchronous
loop, and an uncaught error or process.exit() ends only that worker.
- WorkerSandbox mirrors SubprocessSandbox (timeouts, idle reclaim,
per-worker pending calls) over the worker message port.
- The bootstrap talks to parentPort in a worker and posts ready once it
listens; the host holds calls until then because Bun drops earlier
messages.
- Workers override process.cwd() instead of chdir, which Bun would apply
to the whole host process.
- Uncloneable values fall back to JSON, matching the subprocess IPC.
- The sandbox test suite runs against both transports, plus worker-only
tests for loops, stray throws, process.exit, cwd, and no runtime.
* fix(core): ship a self-contained plugin bootstrap and snapshot queued worker calls
The CLI copies plugin-sandbox-bootstrap.js beside the compiled binary,
where nothing can resolve @cline/shared or jiti, so a worker (or
subprocess) exited before initializing any plugin. Bundle every package
into the bootstrap and fail the core build if it imports anything but
Node builtins.
Calls made before a worker reports ready kept the caller's args object,
so later changes leaked into the call and an uncloneable value added in
that window threw from the message listener. Queue a structured clone
instead, skip calls that already timed out, and reject a call whose
flush fails.
* test(core): give the worker loop-recovery test room for a cold worker on CI
The recovery call boots a fresh worker and re-imports the plugin within
the same tool timeout, which 200ms did not cover on CI runners.
* fix(core): keep worker plugin stdout off the host's stdout under Bun
Bun workers write console.log and process.stdout straight to the host's
stdout (Bun ignores the Worker stdout option), so a plugin's logging
corrupted --json output and JSON-RPC streams. Discard stdout-bound output
inside the worker, matching the subprocess sandbox's stdio "ignore".
* fix(core): complete discarded stdout write callbacks in plugin workers
The worker's process.stdout.write replacement dropped the completion
callback, so a plugin awaiting a write hung until the call timed out.
Call it on the next tick for both write(chunk, cb) and
write(chunk, encoding, cb).
* feat(core): run plugins in workers by default, through the plugin registry
Worker mode now goes through PluginRegistry instead of around it, so it
keeps everything in-process mode has: plugin status and plugins.list/
status/reload, plugin.status_changed, degraded/failed tracking with the
failure threshold, session notices, the per-session plugins policy,
stale-copy protection, and per-session timeouts. Only where a copy runs
changes: each plugin gets its own worker per session, and the copy the
registry wraps is a proxy to it.
One worker per plugin means a worker that dies on its own (uncaught
error, unhandled rejection, process.exit) is that plugin's failure with
no stack attribution: the plugin is turned off and the host and other
plugins keep running. The hub preloads status in throwaway workers.
- CLINE_PLUGIN_MODE defaults to worker; in_process and sandbox are
opt-ins. Hosts that ship no bootstrap fall back to in_process.
- WorkerSandbox reports unexpected exits; sandbox tool proxies honor a
tool's own timeoutMs.
- The bootstrap is resolved lazily and can be set with
CLINE_PLUGIN_BOOTSTRAP_PATH. The desktop app ships it as a Tauri
resource and points the sidecar at it; the VS Code build copies it
next to the bundle as .mjs.
* fix(core): carry setup context, tool context, and tool definitions into plugin workers
Worker plugins lost what in-process plugins get, now that workers are the
default:
- Setup context: ctx.cwd, ctx.emitEvent, and ctx.onDispose. Cleanup runs
in the worker before it stops (session release, shutdown, idle
reclaim); calls arriving during an idle stop wait for a fresh worker.
- Tool context: the abort signal (the host forwards aborts by call id),
emitUpdate (routed back to the calling tool), and emitEvent.
- Tool definitions: lifecycle, executionMode, resultPolicy, maxRetries,
and any other plain field now reach the runtime.
- Setup gets its own timeout inside the worker. A setup that throws,
times out, or takes the worker down fails only that session's copy,
instead of being reported as an import failure that turns the plugin
off for every session.
* fix(core): don't treat an exit during plugin cleanup as a crash
stopGracefully() ran the dispose method before marking the worker as
stopping, so a disposer that called process.exit() or threw from a timer
looked like an unexpected exit and turned the plugin off for every
session. Mark the worker as stopping before cleanup starts.
* fix(core): apply the session plugin policy by a worker plugin's own name
The host checked the policy against the file-derived name before the
worker had imported the plugin, so a policy keyed by the plugin's
exported name misfired: "*" off plus the plugin turned on by name
skipped it for good, and turning it off by name still ran its setup().
The worker now applies the policy after import, against both names, and
before setup. The host skips the worker up front only once it has seen
the plugin's own name for its current code.
* fix(core): keep setup prompts and cleanup for worker plugins
Worker plugins run setup() while the session bootstraps, before it is
registered, unlike in-process plugins whose setup runs on the first turn.
- Prompts a plugin sends to its session during setup (steer_message,
queue_message, pending_prompt) found no session and were dropped. The
host now holds them until the session is registered, then delivers them.
- A setup that registered ctx.onDispose and then threw or timed out lost
its cleanup, since only plugins that loaded are disposed later. The
worker now runs that cleanup right away, so a child process started
before the failure does not outlive it.
---------
Co-authored-by: Saoud Rizwan <7799382+saoudrizwan@users.noreply.github.com>
* docs: match the CLI automation pages to the CLI
The scheduling, teams, subagents, connector and sample pages told
readers to run commands and flags the CLI doesn't have, and the
samples downloaded files that are gone.
- Scheduling: `executions` is `history`; `--workspace` is required;
provider and model are separate flags; the other create options,
subcommands and cron names are listed. Routing results now names the
chat with `--delivery-thread` or `/schedule create` in the chat. A
schedule with only `--delivery-bot` never posts anything.
- Teams: start with `/team` and resume with `cline --id`, not the
hidden `--team-name`; there is no `--no-teams`; state is in
teams.db. The SDK teams guide gets the same CLI fix.
- Subagents: the page described the old read-only research tool.
`spawn_agent` subagents can edit files and run commands without
further approval, run in the CLI and Desktop only, and are turned
off with the `spawn_agent` tool.
- Connectors: gchat, WhatsApp and Linear flag names; Discord tools
are on by default.
- Samples: inline the scripts whose download links 404; filter
`run_result` for the final answer; `cline auth` needs `--modelid`;
current model ids and prices; the issue responder runs Cline with a
read-only token and posts from a second job, like the PR reviewer.
Part of #14853.
Co-authored-by: Harshil Mistry <125483347+harshil-mistry@users.noreply.github.com>
* docs: check commenter permission, fail scripts on failed runs
The @cline issue responder admitted any OWNER, MEMBER or COLLABORATOR,
and organization members or collaborators with read access pass that
check. A secret-free authorize job now looks up the comment author's
repository permission and lets the analyze job run only for write or
admin. It checks the comment's author rather than the actor, so editing
someone else's comment doesn't start Cline on their text. The analyze
job also stops setting CLINE_DIR from runner.temp, which isn't
available at job level.
Plan mode removes the editing tools and refuses common file-changing
commands, but python -c and node -e still write files. The scheduling
and subagent pages now say so instead of promising that Plan runs
can't edit files.
When a run fails, the CLI exits 1 but run_result still carries the
error text, so jq prints it and the pipeline succeeds. The orchestration
scripts now use set -euo pipefail, wait on each background review by
PID, remove output files from earlier runs and name their inputs
instead of globbing. analyze-issue.sh sets pipefail. The PR review
pattern names the pull requests the sample skips.
* docs: wait on saved review PIDs, list the current team tools
The parallel review samples waited on $(jobs -p). Bash 3.2, the macOS
/bin/bash, leaves finished jobs out of that list, so a review that failed
fast was never waited on and the next model read an empty review. Save
$! after each background pipeline and wait on those PIDs.
The SDK teams guide listed team_delegate_task, team_check_status and
team_get_result, which no longer exist, and a JSON layout under
~/.cline/data/teams/. List the tools in TEAM_TOOL_NAMES and say that team
state is in ~/.cline/data/db/teams.db, keyed by session and restored
when the session resumes.
---------
Co-authored-by: Dominic Cooney <55120+dominiccooney@users.noreply.github.com>
Co-authored-by: Harshil Mistry <125483347+harshil-mistry@users.noreply.github.com>
* docs: match the CLI reference to CLI 3.0.68
The CLI reference and the pages that repeat it had drifted from the CLI.
They named a `dev` command that no longer exists, swapped the --config
and --data-dir defaults, described `connect` as an IDE adapter, said
--thinking defaults to medium, and showed a JSON output shape (say/ask
messages) that the CLI never prints. The documented `jq -r .text`
example prints only nulls.
Replace the pasted help with the 3.0.68 output and document what it
lists: --compaction, --worktree, --update, --kanban, `skill`,
`dashboard`, the `auth` options, `config <target>`, `connect --stop`
and `--restart`, `mcp add`/`remove`, the `history` subcommands and
options, and the `hub` subcommands including `drain` and `upgrade`.
Rewrite the JSON section around the agent_event and run_result lines,
with a jq filter that prints the final answer. Note that -k also saves
the key, drop the `-i` image example (-i opens the TUI), and use the
Cline provider's model id in the API auth example.
Co-authored-by: Harshil Mistry <125483347+harshil-mistry@users.noreply.github.com>
Co-authored-by: MarMar Labs <marmar9615@icloud.com>
* docs: correct CLI defaults and JSON notes from review
--retries defaults to 3, not the 6 that `cline --help` prints; note the
discrepancy under the pasted help. Without --thinking, Cline uses the
reasoning level saved from the TUI before the provider's default. Drop
--page, which the CLI accepts but ignores. Say that a --timeout stops
the run without a run_aborted line, and that scripts should skip line
types they don't use.
Use Claude Sonnet 5.5 in the auth examples, and say "in your terminal"
where the pages described commands that need one.
* fix(cli): make --help match what the CLI does
`cline --help` said --retries defaults to 6, but runs use 3. The help
now reads the same CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES constant that
main.ts passes to the session, and a test ties the two together.
--thinking now says that, without the flag, the CLI uses the level
saved in the TUI before the provider default. -k says the key is also
saved as the provider's key. `history --page` is hidden from help: the
CLI never reads it, but it stays accepted so existing scripts keep
working.
The CLI reference shows the corrected help and no longer notes the
wrong --retries default. The CLI README's -k and --thinking rows match.
* fix(cli): name /model in the --thinking help
Readers don't know what "the TUI" is. The level --thinking falls back to
is the one chosen in the model picker, which users open with /model, so
the help, the CLI reference, the overview and the README now say that.
* fix(cli): warn that cline history --page is ignored
cline history lists the newest sessions up to --limit and has never
read --page. The option stays accepted so existing scripts keep
working, but it now prints a deprecation notice to stderr. The
terminal tests that expected --page in help, or ran it as if it
selected a page, are removed.
* fix(cli): say hub upgrade does not wait for --zen tasks
cline hub upgrade waits only until no client is attached. A --zen run
detaches once the hub accepts it, and scheduled runs never attach, so
the upgrade can stop both mid-run. The help text and the hub command
lists in the docs now say so.
* docs: drop dashboard from the root help listing
cline --help no longer lists dashboard; it is cline hub dashboard.
* fix(cli): require a count for --retries; fix connect --restart example
--retries was declared with an optional value, so a bare --retries set
it to true and the CLI crashed calling .trim() on it. The option now
requires a count, and a bare --retries fails with commander's
"argument missing" error.
cline connect passes options after the channel to the channel's
connector, so "cline connect telegram --restart" never reached
connect. The examples now put --stop and --restart before the
channel, and the reference says why.
* docs: scope the JSON line format to agent runs
The JSON section read as the format of every --json, but only agent
runs print typed lines. cline history --json prints one array, and
each cline config target prints its own shape. The heading and both
pages now say the line format is for tasks, and name the others.
---------
Co-authored-by: Dominic Cooney <55120+dominiccooney@users.noreply.github.com>
Co-authored-by: Harshil Mistry <125483347+harshil-mistry@users.noreply.github.com>
Co-authored-by: MarMar Labs <marmar9615@icloud.com>
* refactor(cli): scope hub options to their subcommands
* feat(cli): move dashboard under hub and document its usage
---------
Co-authored-by: Cline <cline@users.noreply.github.com>
The CLI logger wrote to CLINE_LOG_PATH when it was set, but cline doctor
built the default path itself, so `cline doctor log` opened the wrong
file and `doctor --verbose`/`--json` read recently spawned processes
from it.
Move the path into resolveCliLogPath() in logging/log-path.ts and call
it from the logger and from both doctor readers. The module is separate
from the logger so cline doctor doesn't load pino.
The config page, the CLI reference, the proxy troubleshooting page and
the CLI README now say that `cline doctor log` opens the CLINE_LOG_PATH
file.
Co-authored-by: Dominic Cooney <55120+dominiccooney@users.noreply.github.com>
* docs: correct shared paths, log files, commands and tool names
Several pages repeat the same facts about where Cline keeps its files,
which commands exist and what the built-in tools are called, and many of
them no longer match the shipped CLI and SDK:
- Workflows live in ~/.cline/workflows/, not ~/.cline/data/workflows/.
The session index is ~/.cline/data/db/sessions.db, each session has a
folder of JSON files, and hub locks and logs are under ~/.cline/data/.
- cline start and cline dev log do not exist; the log command is
cline doctor log, and the CLI log is ~/.cline/data/logs/cline.log.
- The built-in tools are run_commands, search_codebase,
fetch_web_content and skills, not bash, search, fetch_web and
use_skill.
- CLINE_HUB_ADDRESS is read only by cline schedule; the hub port is
CLINE_HUB_PORT.
- No CLI 3 release reads CLINE_COMMAND_PERMISSIONS. The pages that
offered it, including the PR review sample, now say the CLI has no
command allow list and point to a PreToolUse hook. The unused
permissionDeniedError string in the VS Code prompts goes with it.
Part of #14853.
Co-authored-by: Mikołaj Kondratek <19799111+mkondratek@users.noreply.github.com>
Co-authored-by: Manpreet Kaur <26463231+Manpreet2298@users.noreply.github.com>
Co-authored-by: Renee Huang <100229782+reneehuang1@users.noreply.github.com>
* docs: qualify log, tool routing and command-approval advice
- cline doctor log always opens the default log file, so say so where
CLINE_LOG_PATH is described.
- The editor and apply_patch choice is a default that SDK callers can
replace with toolRoutingRules.
- The PR review sample now warns that hooks and plugins in the checked-out
pull request run with the job's environment, and says how to keep them
from running before relying on a global PreToolUse hook.
- The conditional-approval example no longer auto-approves git diff,
which runs a configured external diff program, and notes that Git can
run programs named in a repository's config.
* docs: run the PR review sample with a read-only token
The sample gave an auto-approved Cline run a token that can write pull
requests. Split it into two jobs: `review` runs Cline with read-only
permissions on a checkout of the base branch and writes review.md;
`post` runs no repository or model code and posts the file with
`gh pr review --comment`.
Skip pull requests from forks and Dependabot, which get no secrets,
and warn against `pull_request_target`. Fence the workflow with four
backticks so the code block inside the prompt no longer ends it early.
---------
Co-authored-by: Dominic Cooney <55120+dominiccooney@users.noreply.github.com>
Co-authored-by: Mikołaj Kondratek <19799111+mkondratek@users.noreply.github.com>
Co-authored-by: Manpreet Kaur <26463231+Manpreet2298@users.noreply.github.com>
Co-authored-by: Renee Huang <100229782+reneehuang1@users.noreply.github.com>
* docs: state telemetry defaults and scope accurately
The Enterprise and monitoring pages called Cline telemetry opt-in and
anonymous, and said code never leaves the machine. Telemetry is on by
default in the VS Code and JetBrains extensions, Cline Desktop and the
CLI. It identifies signed-in accounts and organizations, and includes
prompts for requests to the Cline and ClinePass providers.
Rewrite the telemetry page around what is collected and how to turn it
off in each product. Scope the remote-configuration restrictions to the
products that enforce them, add a per-product support table, and tell
admins to ignore the folders Cline writes into workspaces. Align the VS
Code setting description and host-telemetry warning with the docs.
Part of #14853
* docs: drop bold from remote-config support table rows
The bold marked dashboard switch names, but nothing on the page said so,
so the rows looked inconsistent.
* docs: address review of the telemetry and remote-config pages
State only what the telemetry setting enforces in the extensions: the
lock, and that members can't turn telemetry on when the organization
turns it off. Scope the support-table introduction to the controls
marked Yes, since no product enforces YOLO or Kanban. Use recursive
.gitignore patterns and say why: the cached settings can include prompt
storage access keys, and a member may open a subfolder of a repository.
Narrow the indexing card to content: Cline lists file paths to search
them but doesn't index or embed file contents.
* docs: say products support remote-config controls, not enforce them
Organization rules and workflows reach sessions as instructions that a
member can edit, so "enforces" overstated what the CLI does with them.
The section heading already says "support".
---------
Co-authored-by: Dominic Cooney <55120+dominiccooney@users.noreply.github.com>
* docs(mcp): correct the CLI mcp config path
* docs(tools): correct the same stale .cline/mcp.json reference
* docs(cli): correct the MCP config entry in the configuration tree
The CLI reference listed `mcp.json` under the project-root `.cline/` tree,
but `resolveMcpSettingsPath()` only ever resolves a global path:
`~/.cline/data/settings/cline_mcp_settings.json` (overridable via
`CLINE_MCP_SETTINGS_PATH`). There is no project-level MCP config reader.
Move the entry to the `~/.cline/data/settings/` tree where the resolver
actually looks, and drop the project-root entry.
Three in-site links point at anchors that no longer exist, so they load
the target page without jumping anywhere. Verified against the live docs
DOM by counting the rendered heading ids.
* security(docs): override adm-zip >=0.6.1 and fast-uri >=3.1.6 in docs tooling
Closes CVE-2026-77301 (adm-zip) and CVE-2026-75899/-75931/-75975/-76172 (fast-uri),
all on docs/package-lock.json via mintlify. Resolved: adm-zip 0.6.1, fast-uri 3.1.8.
Produced by the VMP Automation, 2026-09-25 run.
* security(docs): raise js-yaml override floor to >=4.3.2 <5
The ^4.3.1 override resolved the vulnerable 4.3.1 in docs/ (CVE-2026-84375, Dependabot #699).
Produced by the VMP Automation, 2026-09-25 run.
---------
Co-authored-by: TheRealSpencer <32678829+TheRealSpencer@users.noreply.github.com>
Reorganize the Cline Overview page and add Cline Desktop to the
install docs.
cline-overview.mdx:
- Move Applications above Model access, so the page leads with
"what do I install" before "how do I pay".
- Add Cline Desktop App as the first application card, linking
directly to the cline.bot download.
- Merge the SDK into the Applications grid as its final card and
drop the standalone "Agent Core (SDK)" section, leaving a clean
2x3 grid with no orphan row.
- Reword the Applications intro, which claimed every entry was
"built on top of Cline's agent core" -- no longer true once the
core itself is listed.
installing-cline.mdx:
- Add a Desktop App install path as the first option, covering
download, workspace/branch selection, model choice, and sessions.
- Link both the Desktop and Desktop SSH pages.
Also fixes an invisible icon: the Font Awesome "monitor" icon used
for the desktop card returns 403 from the CDN, so the card rendered
with no glyph at all. Switched to "desktop", which resolves. All 13
icons on the overview page were verified against the CDN.
SSH ignores the system HTTP(S) proxy, which surprised a user who
expected the desktop SSH feature to use it. Document the ~/.ssh/config
route (ProxyJump, HTTP and SOCKS ProxyCommand) with the alias entered as
the SSH host, which the app already supports.
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
* docs(desktop): add Remote Development over SSH guide
Adds a Cline Desktop page that walks first-time SSH users through
creating a key, installing it on the host, trusting the host key, then
adding the host under Settings > Remote, connecting from the environment
selector, and opening a remote project. Includes GIFs and screenshots
captured from the app, a limitations list, a troubleshooting table for
the SSH errors the status panel surfaces, and a short how-it-works
section. Links the page from the Cline Desktop overview and nav.
* docs(desktop): nest the SSH guide under a Cline Desktop group
Follows the Kanban pattern: the existing overview page becomes the
group's first entry with sidebarTitle Overview, and the SSH page sits
beneath it as Remote over SSH.
* docs(desktop): embed the SSH walkthrough clips as MP4 instead of GIF
Same footage re-encoded from the original recordings as H.264 at
1280x800: 323 KB and 428 KB instead of 2.7 MB and 3.5 MB, with full
color instead of a 256-color palette. Embedded with the same <video>
markup the auto-approve and multi-root pages use. Squash merge keeps
the GIF blobs out of main.
* shared: expose workspace/global rules path helpers and search redirected Documents
resolveWorkspaceRulesConfigPaths returns both supported workspace rule
layouts (.clinerules and .cline/rules) so hosts can stop hardcoding one
of them (#14186). resolveGlobalRulesConfigPaths returns every global
rules location and now also includes OneDrive Known-Folder-Move
Documents candidates: the VS Code extension resolves the real Documents
folder through the OS and creates global rules there, so on Windows
machines with redirected Documents the SDK resolver (used by the
desktop app and CLI) never found them (#14144).
* vscode: surface rules from every shared resolver location in the Rules panel
The Rules panel's toggle refresh was hardcoded to the workspace
.clinerules directory and the Documents global directory, so rules the
SDK runtime loads from .cline/rules (and global ~/.cline/rules,
~/Cline/Rules) were applied to the model but silently missing from the
panel (#14186). Synchronize toggles across every directory the shared
resolver searches, combining per-directory results the same way the
Cursor rules multi-location handling already does.
Also drop the ambient @cline/shared/storage stub: it shadowed the real
module declaration and hid every export the stub didn't re-declare;
tsc resolves the real dist types fine.
* desktop: classify .cline/rules workspace rules as Project in Customize view
The Rules tab grouped project rules only when their path contained
/.clinerules/, so rules in the .cline/rules layout were shown as Global
(#14186, #14144).
* fix(desktop): anchor rule scope to workspace roots and document layouts
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
* feat(branding): add canonical Cline logo assets
* feat(vscode): refresh extension logo surfaces
* feat(web): update Hub and example branding
* docs: update Mintlify branding assets
* build(brand): lock asset generator tooling
* chore(branding): limit logo refresh to assets and required wiring
* fix(vscode): restore accessible logo names
* fix(branding): retain favicon contrast in dark browser tabs
* [2/3] Refresh desktop logo assets (#13966)
* chore(desktop): refresh native logo assets
* chore(menubar): refresh native logo assets (#13967)
part of logo migration
* docs: use latest adjusted navigation logo
* fix(hub): keep favicon visible in dark browser tabs
Point the Hub favicon at the dedicated favicon.svg and give it the same
prefers-color-scheme fallback as the example app. cline-logo-filled.svg
stays untouched since the sidebar renders it with dark:invert.
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
---------
Co-authored-by: Saoud Rizwan <7799382+saoudrizwan@users.noreply.github.com>
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
* docs: cline desktop page
* docs: move cline desktop page to usage section
- Relocate page from getting-started/ to usage/ and move nav entry to top of Usage group
- Remove Plan/Act mode bullet (not supported in Cline Desktop)
---------
Co-authored-by: Renee Huang <renee@cline.bot>
* docs: add enforced .clineignore guard plugin example
Adds clineignore-read-files-guard.ts, a beforeTool hook plugin that blocks
read_files, editor, apply_patch, and run_commands calls targeting paths
matching gitignore-style patterns in a workspace .clineignore file, and
protects .clineignore itself from modification. Features it on the
.clineignore docs page as the enforced replacement for the deprecated
built-in feature.
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
* docs: use a PreToolUse file hook for the enforced .clineignore example
Replaces the plugin-based guard with a PreToolUse hook script that works in
the VS Code extension today (.clinerules/hooks/PreToolUse plus the Enable
Hooks setting) as well as the CLI (.cline/hooks/PreToolUse.sh). The script
handles both hook payload shapes, blocks read_files/editor/apply_patch/
run_commands calls matching .clineignore patterns, and protects .clineignore
itself from modification.
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
* fix: canonicalize paths in .clineignore guard hook
Lexically collapse '.', '..', and empty segments before the ignore match
and the .clineignore self-protection check, closing bypasses via
noncanonical paths like ./.clineignore, secrets/../.env, or
/root/./file (Greptile review finding on #13649).
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
* docs: note symlink limitation in .clineignore guard hook docs
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
---------
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
* fix(vscode): enforce enterprise MCP controls on the Customize marketplace
The unified Customize marketplace replaced the old MCP marketplace
without carrying over enterprise remote-config enforcement: the catalog
RPC returned every MCP entry and installs were never policy-checked,
so orgs with mcpMarketplaceEnabled=false or an allowedMCPServers
allowlist saw (and could install) all marketplace MCP servers.
- Filter MCP entries out of getMarketplaceCatalog when the marketplace
is disabled, and restrict entries to the allowlist when configured
(matching entry id, display name, installed server name, or source
repo URL, mirroring legacy GitHub-URL allowlist ids)
- Reject installMarketplaceEntry requests that violate the policy
- Map the published catalog's repo/homepage fields onto
sourceUrl/homepageUrl so URL-based allowlists can match
- Update the enterprise MCP server controls docs
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
* refactor: simplify MCP marketplace policy enforcement
Fold the policy check into marketplace-helpers, drop the dedicated
test suite, and trim the docs edit to the strictly necessary line.
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
---------
Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
* chore(ui): replace font dependencies
* refactor(ui): migrate shared typography tokens
* refactor(ui): adopt Inter and Geist Mono in apps
* fix(hub): preserve variable font weight tokens
* feat(ui): tune font weights for dark mode
* docs(ui): add font migration screenshots
* (chore)ui: misc typography adjustments
* fix(hub): make dark-mode font-weight overrides take effect
Tailwind's @theme inline bakes literal values into utilities, so the
.dark --font-weight-* overrides were dead code and dark mode rendered
the heavier light-mode weights. Declare the weights in :root instead so
font-* utilities keep their var() references, matching the @cline/ui
tokens approach. Also rewrap --font-mono to satisfy biome format.
* fix(ui): restore light-mode semibold to 640 and pin weight scales in test
The PR intent is a 480/560/640/640 light scale with 400/500/600/600
dark overrides, and the Hub already uses 640; tokens.css had drifted to
600 for light semibold. Regenerate scoped-tokens.css and assert both
the light and dark weight scales in the theme contract test.
* chore(desktop): remove stray double space in provider header class
---------
Co-authored-by: Saoud Rizwan <7799382+saoudrizwan@users.noreply.github.com>
* refactor(ui): introduce Cline-owned semantic color system
* refactor(desktop): adopt shared semantic theme roles
* refactor(ui): set 15px root and recalibrate xs/sm type scale
Scale rem steps so xs/sm stay 12/13px visually, and slightly lift dark-mode neutral-4.
* refactor(ui): align SearchCombobox with package type and hover tokens
Use host-safe cline-ui utilities and keep option font inheritance from CSS.
* fix(ui): use standard stroke-2 utility on approval spinner
* refactor(desktop): modernize shared UI primitives for Tailwind v4
Replace legacy arbitrary/has selectors with current utility syntax.
* refactor(desktop): bump chat chrome typography to text-sm
Keep composer controls and pickers on the shared sm type step.
* refactor(desktop): use max-w-344 for page frame content width
* chore(desktop): disable Next.js dev indicators
* chore: ignore desktop-app Cursor settings
* docs(pr): add before/after screenshots for #12941
* chore: retrigger checks
---------
Co-authored-by: Saoud Rizwan <7799382+saoudrizwan@users.noreply.github.com>
* docs: fix typos and incorrect slash command reference
- Fix double period in MiniMax provider description
- Remove duplicate 'through' in kanban install description
- Fix /new -> /newtask (correct slash command name)
* docs(hooks): fix description to reference SDK Plugins, not SDK Hooks
The description said 'SDK Hooks page' but the content links to the
SDK Plugins page (/sdk/plugins). Align the description with the
actual destination.
* docs: update ClinePass wording from '2-5x API rate limits' to '2-5x the usage on popular open coding models compared to standard API rate'
* docs: update ClinePass wording in cline-provider.mdx for consistency
* nit
* docs: mark .clineignore as deprecated soon
Add a deprecation notice to the .clineignore page and update pages that recommend it. Enforcement of ignore rules is extremely difficult (agents can get around them via @ mentions or shell commands), and the feature is orphaned in the VS Code/JetBrains extension (ClineIgnoreController), not part of the Cline SDK or CLI.
* docs: update clineignore deprecation wording
* wording changes
* update clineignore docs with plugin reference
* fix plugin example url
* edit clineignore docs file
* update formatting for clineignore doc
* clean up clineignore docs file
---------
Co-authored-by: Cline <bot@cline.bot>
Co-authored-by: TheRealSpencer <spencer@cline.bot>
TheRealSpencer