Actually you don't need to read our docs, just ask Clark questions
Ask from a terminal:
clarkcant ask "how do I connect Cursor to you?"
The CLI runs from a ClarkCant checkout for now, so without an alias the same question is:
# From a ClarkCant checkout (the CLI is not published to npm yet)
node apps/cli/src/main.ts ask "how do I connect Cursor to you?"
Or, from any AI tool that speaks MCP (Claude Desktop, Cursor, …), call the ask_clark tool:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "ask_clark", "arguments": { "text": "how do I connect Cursor to you?" } } }
The rest of these pages are for when you want the exact routes, frames and flags.
Built on open standards
ClarkCant is one conversation with one Clark. The same Clark is reachable through ordinary, open interfaces, so any third-party app, script or AI tool can drive it without a custom SDK:
- HTTP/JSON + SSEA REST API described by OpenAPI 3.1, with replies streamed as Server-Sent Events.
- MCPModel Context Protocol over Streamable HTTP, plus a stdio bridge for desktop AI tools.
- WebSocketAny REST call as a frame, several at once, over one socket.
- CLI
clarkcant: ask, read, stop, or call any route from a terminal.
One token, one gateway, the same semantics everywhere. Every surface is served by the same runtime node, on the same origin, with the same bearer token. There is no second business-logic stack: an MCP tool, a WebSocket request and a CLI command all end up at the same HTTP gateway handler, so they behave exactly like the REST call underneath.
Approvals are deliberately not exposed to MCP. Deciding an approval is a human surface. An AI client must not be able to approve its own guarded action, so there is no MCP tool for it.
Slash commands
Type / in the composer to see the commands, listed ahead of your skills. With nothing typed, commands and skills share the list (half each when both have plenty), so your skills are always there too; type a few letters to reach the rest. Each one is answered by Clark in the conversation, as a message with a small card you act on right there, so nothing opens a screen of its own, except /settings, which opens the same Settings dialog the gear opens.
/newstarts a new conversation. The current one is kept, and you can reopen it with/sessions. It works at once while Clark is still writing a reply, too: the reply is not stopped, it goes on in the conversation you left, and a note says so./sessionslists background work and your earlier conversations, each with Open. A conversation Clark is still answering is marked./changelogshows what is new in this version. See below./loginsigns in to an AI provider from the card, using the provider's account page, a device code or an API key, whichever the provider offers. What you type goes straight to the model runtime; it never appears in the conversation and no later read returns it. Once signed in, the card names the provider and checks which of its models Clark can run. It then offers Choose a … model, which opens the/modelpicker for that provider in the same card, or Keep current model. Signing in never switches the model by itself. If the provider is not listed as signed in yet, or has no models, the card says so and offers Check again. Signing in from Settings → AI & Routing ends with the same step./modelchooses the model that answers. The card lists the models this node can run, marks the one in use, and shows whether each provider is signed in. You can search, or start with words:/model large. Opening it changes nothing. After you pick a model and confirm Switch model, that model answers from your next message. If this node runs no model yet, it starts with that model the next time it starts. A signed-out provider's models are shown but cannot be chosen until you sign in with/login. The node itself refuses one, soPOST /modelfrom the API orclarkcant apigets the same answer:409 CAPABILITY_NOT_AUTHENTICATEDwith the reason./logoutsigns out of a provider whose key Clark stored. If a key comes from the environment, such as.envor the shell, the card says so and you remove it there./thinkingchooses how hard the next turns think, from a list, or directly:/thinking high, or/thinking autoto let the model use its own default. It is the same setting as Settings → AI & Routing → Thinking level./settingsopens Settings, the same dialog as the gear in the header;/settings <tab>opens it on that tab, such as/settings ai,/settings memory, or a tab's label as Settings shows it in either language, whole or either side of its “&”, like/settings bộ nhớ,/settings voiceor/settings AI & Routing. It works while Clark is still writing a reply, too. Closing it returns you to the conversation as you left it. Commands other than/settingsand/newtyped while Clark is replying stay in the composer, with a note that they can be sent once the reply finishes./background <request>runs the request as background work beside the conversation and reports back in it./reportreports a bug or asks for a feature in ClarkCant itself. See below./developchooses a folder to develop a widget from, live in the conversation;/develop <folder>offers that folder, and/develop forgetlists the folders you chose so you can take one back. See developing a widget in the conversation.
When a press on a command card does not reach your node, or gets no answer in time, the card says so and offers Try again beside it, which sends the same press again; this works for /thinking, /login, /logout, /develop and forgetting a chosen folder. A press your node refused says why and offers nothing to repeat, because sending it again would get the same answer.
A skill whose name is also a command's is listed and written as /skill:<name>, so choosing it uses the skill; typing /new yourself still runs the command.
A command typed in the middle of a sentence is just text. Commands are not sent to the model. See provider sign-in routes.
Report a bug or request a feature
Type /report to get a card where you choose Bug or Feature, say what happened or what you want in your own words, and open “What will be shared” to see exactly what goes with it. /report bug … and /report feature … (also lỗi and tính năng), a sentence to Clark, or your voice go one step further: Clark prepares the report and shows the issue exactly as it would be filed. None of these sends anything. Only your own press on Create issue files the report; Clark, its tools and voice cannot. Reports go to digitopvn/clarkcant and nowhere else.
Your execution policy applies to that press. If it denies the action, the report is refused and nothing is sent; if it would ask first, your press is the answer. Before filing, Clark looks through open issues and issues closed in the last 90 days, and when an open issue clearly matches, your report is added to it as a comment instead of opening another.
The result card says which way it went: Issue opened or Added to an existing issue (only once Clark has read the report back from GitHub), Outcome not known yet, Not filed, GitHub access needed or Refused by your policy. When GitHub's answer never arrived, Check again only looks; it never sends. Send again appears only once GitHub shows the report missing at least two minutes after the attempt. If Clark cannot tell whether GitHub kept it, the card says so, links the issues you opened since then and a prefilled new-issue page, and offers Send anyway, which may file it twice. Clark never sends a report again on its own: after a restart, reports left unsettled are checked, not resent, and the result is posted in their conversation.
If your press on Create issue does not reach your node, the card offers Try again, which sends the same report the same way. If it was sent and anything other than a refusal your node decided came back (the connection dropped, it timed out, a relay in between failed, or your node hit an error of its own), your node may have filed it, so the card never says it was not filed: it says the outcome is not known yet and offers Check again, which only asks your node where the report stands, with Try again beside it when sending the press again can get through. A press that arrives while your node is still sending the report is told so, in your language. Your node takes a report for one send before it asks GitHub anything, so a report it already sent, or is sending, is checked rather than sent again, even when two presses overlap; a retry never files a report twice. A Check again that does not go through leaves the outcome not known. If your node answers but this version of the app cannot read the answer, the card says the report may or may not have been filed, never that it failed, and offers Check again. A refusal your node decided offers nothing to repeat and does not suggest trying again. After Try again or Check again, keyboard focus stays on the card's status.
Filing uses the GitHub token (github_token) you stored for signal sources. Without one, the card shows GitHub access needed with a link to GitHub's new-issue page, already filled in, so you can file it yourself. The repository also has Bug report and Feature request issue templates for filing by hand.
What is shared, and what never is. Your words, with secrets redacted, and safe diagnostics unless you turn them off: the ClarkCant version, OS and architecture, runtime, locale and input mode, the part of ClarkCant it is about, the provider and model, and an error as a short redacted excerpt with a fingerprint. Never sent: the conversation, system prompts, files, environment variables, raw logs or credentials. Your home folder is written as ~, and @mentions in your words are neutralised so a report notifies nobody.
Asking Clark to work on an issue you filed is not available yet; the result card says why. See the report routes.
Signing in to AI providers
Open Settings → AI & Routing to sign in to the AI providers pi can answer with, under the provider and model picker. Each provider shows only the ways in pi offers for it: an account sign-in when the provider has one, an API key when it takes one. The sign-in runs inside the row: open the provider's page and paste the code it shows, or type a key into a password field. What you type goes straight to pi and is never shown again. Typing /login or /logout in the conversation does the same.
A signed-in provider says where its credential comes from: stored by pi, the node's environment (.env or the shell), handed over when the node started, pi's models.json, or a key pi finds on its own. Only a credential pi stored can be signed out or replaced here. For the others the row says so and where to remove the key. After a sign-in or sign-out the provider list and the model list refresh, so a newly available model can be chosen right away.
Inbox and notifications
Open the inbox from its header badge, with the keyboard, or by asking Clark in text or voice: “open the inbox”. It brings together command approvals, package permissions, approvals a running task raised, open questions and stored notices about background work, expired requests and available updates. Clark's control_app tool reaches the same inbox.
Granting an approval raised by a running task lets the node run it again; if the node cannot accept the run, Clark says nothing has run and you can ask again. Denial or expiry ends the task. That decision belongs to you; machine interfaces refuse it. See task approval decisions.
Settings → Control offers desktop OS notifications and browser Web Notifications, with per-group toggles and quiet hours. The browser must grant notification permission. Notifications appear only while the app is hidden, unfocused or in orb/compact mode, and their redacted text never includes command lines. Clicking one opens the inbox on its item; an item already dealt with is reported as such.
If the OS refuses or fails to show a notification, an inline status beside the OS notification toggle explains why and says the item remains in the inbox. It clears after a notification is shown again. Update checks offer only versions the installer accepts on your host and stay silent while the node is offline.
Where packages come from
When you ask Clark to find a package, the results card lists packages from your own index file, from any catalog your operator added, and from the official ClarkCant Marketplace, which is on by default. Each row names its source, and a source that did not answer is named rather than shown as an empty list. The official Marketplace may list few packages or none yet. A package keeps the source it was installed from: its updates come only from there, and the update notice names that source. Configuration, precedence and the error codes are in where package listings come from; hosting your own catalog is in the directory feed.
The desktop window
The desktop app reopens the conversation window where you left it: same position and size, maximized or full screen if it was. If that display is no longer attached, or the window would open out of reach, it opens at the default place and size instead. A window remembered from a larger screen is shrunk to fit.
Window controls on Linux: X11, Wayland and Hyprland
The compact bar, the orb, expanded, full screen and the pin behave the same on macOS, Windows and Linux under X11, including a Wayland session where the app runs through XWayland (started with --ozone-platform=x11): the app sets the window's size and position and can keep it above other windows. Under XWayland your compositor may still override placement or stacking.
Under native Wayland, which the desktop app uses by default in a Wayland session, the compositor decides where windows go, and no standard protocol lets an app keep its window above others. So there the app only asks for a size, which a tiling compositor may also ignore for a tiled window, and it never pretends otherwise: the pin button is not shown, a pin request is refused with the reason instead of being sent, and every change of window mode reports position as unsupported.
On Hyprland, for example Omarchy, you can opt in to a Hyprland backend that drives the window through Hyprland's own commands: compact and orb float the window at their size, the orb is also pinned to every workspace, expanded maximizes it, and pin floats and pins it. Minimize is refused, because Hyprland has no minimized state. Turn it on by starting the desktop app with --window-backend hyprland or with the environment variable CLARKCANT_WINDOW_BACKEND=hyprland. It takes effect only when Hyprland is actually running; anywhere else the app keeps its default behaviour. If talking to Hyprland fails once, the window goes back to the native Wayland behaviour above for the rest of the session.
Not yet verified on a real Hyprland. The Hyprland backend is off by default because it has only been tested against a stand-in, not on a real Hyprland or Omarchy desktop, and no Omarchy package ships yet. Of the Linux sessions, only X11 has automated coverage. The steps to check it on your own machine are in the platform smoke guide.
Version and what's new
Ask Clark “what's new?” or “what version is this?”, type /changelog (or /changelog 1.4 for what came after 1.4), or open Settings → Experience → Version & what's new. Each shows the same card, drawn by your node: the installed version and channel, and the release notes that came with this build, grouped as breaking changes, features, fixes and other changes. The notes are embedded in the build, so the card works offline. Clark may sum the entries up in your language, but it cannot add one: the card is your node's, and the entries are the ones the release recorded. The card has no Update button, update status or channel choice, because there is no update service yet. See GET /changelog.
Run from source. A checkout carries the release notes that were committed with it, and those stop at a recorded commit. For a source install, the card, /changelog and Clark name that commit and its date, and say the checkout may include later changes that are not listed. A git pull does not add them. Until the first release is published, the card's link reads “Full change history” and opens the commit history up to that commit.
To update a source install, follow Updating in the installation guide: git pull, then node tools/setup.mjs. If you edited a file that the update changes, git pull stops with an error instead of replacing your edit; keep or undo your change, then pull again. This is the only update path today: Clark has no self-updater.
Versions and channels
The version comes from the commits since the last release, written as Conventional Commits, and follows semantic versioning: a breaking change is a major release, feat a minor one, and fix or perf a patch. main is the stable channel (1.4.0); dev is the beta channel (1.5.0-beta.1, …), and a beta never reaches the stable channel. The full rules, and how to run the release plan from a checkout, are in releases; run corepack pnpm install at the repository root before the release tooling's own install, because the planner reads the app's shared contracts.
Not available yet. No release is published. Installers, signed builds, published release notes and updating from inside Clark come later.
Labels in your interface language
Task cards name their status and evidence in the interface language, for example “needs your decision” or “outcome unknown”; a status this version does not know is shown as sent. In the widget library, each widget's source (Built-in, Installed package, Local development package) and status (Stable, Experimental) are worded the same way. Settings → Extensions lists each tool by what it does, with its name beside it, under “On this node” and “The agent's own (pi)”; the instructions the model is given for a tool are behind “What the model is told”.
Text your node writes into the conversation itself follows the interface language you choose in Settings (Tiếng Việt or English, the preference experience.language; Vietnamese when none is set). It is written in that language when it is written, not translated by the app afterwards, so lines already in a conversation keep the language they were written in. This covers Clark's reply cards and their notes (which model is answering, no model, a model failure, a stopped reply, turn metrics, a refused block), the start-screen samples and the labels of surfaces Clark composes, reports on background work and tasks (started, done, stopped, failed, queue full, retries, deadlines), stop and approval receipts, recovery after a restart, automation messages, the labels of rows for tools your node defines, question rows and their expiry, and the status of work handed to a paired node and the files it brought back. It also covers the model note and the other cards your node writes; the rows and receipts an approved command or package call leaves, including the notes on what a command printed (“No output.”, the truncation marker); approval cards for installing a package, granting it a permission and loading map tiles, and the reason a task is waiting for an approval; how a task ended, when your node wrote that itself (a refusal before the task ran, a run with nothing to show, a stop, and an answer you recorded for an action whose outcome was unknown); the notice that an automation run could not start; inbox notices, including the word used for a notice with no title; the start-screen suggestions; the tool labels under Tools in Settings → Extensions; and the answer when you decline a spoken or typed command, or when its confirmation has expired or was already used.
Kept as written. Text already written keeps its language when you switch: an approval card asked before the switch keeps its wording, and so does the notice of its expiry where it quotes that card. Suggestion chips already on screen stay as they are until the next fetch. Labels and summaries written by a package or extension are shown in their author's words. Text sent to a paired node stays as it is, because your node does not know the language of that node's owner. Text your node did not write, such as an error message or what a run reported, is quoted as written rather than worded into the sentence. The message stored for a task, and what a paired node is sent about it, keep their original wording. What the model is told is not translated: it is the model's input, not text you read.
Coding terms when you speak
When you speak a sentence that mixes Vietnamese and English coding terms, your node fixes how the terms were heard before the sentence is read as a message, a command or an answer: “sửa lỗi stale closer trong use effect” becomes “sửa lỗi stale closure trong useEffect”, and “cài core pack rồi bật p and pm” becomes “cài Corepack rồi bật pnpm”. The fixed sentence replaces the line being written, so each thing you say is one line, not two.
The fixes are fixed rules, not a model: casing, spacing, known mis-hearings, and a one-letter slip in a tool, provider or model name. Each needs evidence in the sentence, and the terms come from what your session knows: your projects, the active branch, the symbols, paths and issues the conversation mentioned, skills, extensions, the current model and a built-in coding glossary. A one-letter fix never reaches a symbol, path, branch or package name, or a word with a digit in it, because its neighbours are other real names or another version. A real word or a person's name is never treated as a mis-hearing, part of a longer written word is never touched, a span that could be two terms is left as heard, and a sentence already written correctly comes back unchanged. No model rewrites what you said.
A dedicated recognizer, if the operator turns it on
By default your words come from the live voice session's own transcription. An operator can have one node use a dedicated recognizer instead by starting it with CC_VOICE_RECOGNIZER=gemini-transcribe. It uses the same Gemini credential as the live session, which stays the voice and still hears you interrupt. While you speak, its first reading is shown and replaced, and only the settled sentence is sent, once. A sentence cut by the provider's session limit stays one sentence. If the recognizer cannot open in time or fails partway, the live transcription takes over, starting from what the recognizer had not delivered. With it on, an unclear technical part of one sentence may be heard again from that sentence's own audio, and a fixed rule picks between the readings. There is no setting for this in the app. An unknown value is ignored and the node says so on stderr.
What the recognizer is sent. Besides your voice, which the live session hears anyway, the dedicated recognizer is sent your session's terms as Gemini's customVocabulary: names such as identifiers, file paths, branch names and issue numbers from the conversation. Every term passes the same secret redaction, and a term redaction would change is left out. The conversation's sentences are used only to rank the terms; they are never sent. Without the setting, the terms stay on your node and are only used to fix the transcript. See the system architecture and ADR-003.
Terminal in the conversation
Ask Clark in text or voice to “open a terminal in the project folder” to open a real shell in the conversation. Full-screen programs such as vim and htop work there. A command Clark proposes follows your execution policy; when it needs your approval it is prefilled and runs only when you press Enter. Clark does not type over a line you are editing. Press F6 to move focus out of the terminal.
Send the selection, the last finished command's result or the screen back to the conversation; the button says which will be sent, and credential-like strings are redacted before the model sees them. A terminal has one driver at a time: other cards observe it and offer “Drive here”. Its Progress panel lists other terminals, command invocations and background work. The card reports connecting, disconnected with reconnect, ended with an exit code, gone from the node or unavailable because the node has no PTY.
Settings → Widgets → Browse lists Terminal under System cards with a description, a static illustration labelled as an illustration and a hint to ask Clark. It has no live preview or open button. Search works with or without Vietnamese tone marks; choosing a family other than All hides System cards. The /terminal socket belongs to this app card.
Long conversations
A long conversation stays one conversation. It opens on its newest messages, and older history loads as you scroll up, with no button to press; it is put in above without moving the line you are reading. When you are more than a screen above the bottom and something new arrives, a Jump to latest button appears over the foot of the conversation, and it goes away once you are at the bottom. If older history cannot be read, the conversation says so where it would have appeared, keeps everything on screen, and offers Try again.
To stay fast, only the messages around the screen are kept in the page; the one you are focused on, a playing player, the embedded video or map you last used, a selection and the newest message always stay. A card you scroll away from and back to keeps how you left it, such as an open fold, a draft or a search, but never a secret typed into a credential card. Because of this, the browser's find-in-page sees every message only in a conversation of up to 60 messages; in a longer one it finds only the messages near the screen. Searching further back is not available yet. See reading a long conversation.
Charts and tables in answers
When an answer has structure, such as numbers to compare, a trend or a list of options, Clark shows it as a chart or a table in the same reply without being asked. Asking “compare the benchmarks of model A and B” is enough; you do not have to add “as a chart”. Clark draws the numbers it actually gathered, says where they came from, and never invents values to fill a chart.
Numbers Clark gathered for an answer are kept on your node as saved data you own, and the chart labels them as saved data rather than live. A bar chart can put several series side by side, with a legend, so two models can be compared on each benchmark. Rows that do not fit, such as too many rows or a cell that is too long, are refused whole with the reason; nothing is shown half-drawn. Today these rows draw in a chart or table shown on its own, not inside a composed overview. See the widget developer standard (§8.6.1).
Kanban boards in the conversation
When a reply has a board, move a card with a mouse, touch or keyboard. The built-in board is a view of work Clark already knows; it does not connect to a project service by itself. If a board is bound to change data elsewhere, that request goes through Clark's normal action and policy path. See the widget developer standard (§8.10).
Tree view
When Clark already has hierarchical information, it can appear as a nested outline using canvas.tree@1. Each item has a stable id and label, with optional secondary text, a closed-set icon and children. This is a view of known information, not a file browser: the tree reads no service and changing selection or expanding a branch does not edit source data. Its selection and expanded branches are saved with the widget and restored with its pin; saved ids absent from a later tree are ignored.
Arrow keys move through visible items and open or close branches; Home and End move to either end, type-ahead finds a label, and Enter or Space selects an item. Screen readers receive each item's level, position, set size, selected state and expanded state. The node validates a bounded hierarchy before it is shown. See the tree contract and bounds and the internal widget development guide.
Diagrams and graphs
When Clark has a flow, a dependency graph or a small tree to show, it can draw it with canvas.diagram@1. Your app draws the SVG itself and nothing in it runs: labels are text, shapes and lines are numbers from a shared layout, and there is no HTML, foreignObject, link, image, style or handler a label could name.
A diagram holds at most 60 nodes and 120 edges. A node id is at most 64 ASCII letters, digits, _ and -. A label is one line of at most 80 characters, an edge label at most 40, a group name at most 40 and the title at most 200. A node's shape is box, round, diamond or circle. An edge's direction is forward, both or none, and it can carry a label. Groups are one level deep. The node refuses a repeated node id, an edge to a node that is not there, an edge from a node to itself, the same edge twice, too many nodes or edges, an unknown field and a hidden character, and each refusal says why in the host's own sentence.
layout is layered (the default) or tree, and direction is TB (top to bottom) or LR (left to right). The layered layout breaks cycles, layers nodes by longest path and bends long edges through the layers they cross. The tree layout centres children under their parent and refuses a graph that is not a forest. A gap that holds an edge label is widened to fit it, and edges joining the same two nodes are drawn apart. The layout is deterministic: the same props give the same drawing on the node and in every client, and the largest accepted graph is laid out in bounded time.
Mermaid flowcharts
Clark can also hand show_view a Mermaid flowchart: { "mermaid": "flowchart LR ...", "title"?, "layout"? }. The node reads a documented subset of the flowchart syntax itself and keeps only the resulting diagram model. It never stores the Mermaid source and never loads Mermaid's renderer. The subset is:
flowchartorgraphwithTB,TDorLR;- nodes written
id,id[box],id(round),id{diamond}andid((circle)); - links
-->,---,<-->,-->|label|and-- label -->; - one level of
subgraph, which becomes the node's group; a node named outside first joins the subgraph that names it later, and a node named in two subgraphs is refused; accTitleas the title.%%comments and a one-lineaccDescrare passed over, since neither draws anything.
A source naming more than 60 nodes or 120 links is refused as soon as it passes the limit. Everything that configures or extends Mermaid's renderer is refused by line, with the reason: click, href, call, style, classDef, class, :::, linkStyle, %%{init}%% directives, front matter, HTML or entity codes in labels, Markdown strings, fa: icons, other node shapes, other link styles, & chains, nested subgraphs and other diagram types.
Selection and keyboard
Choosing a node sends diagram.select with { selectedId }. The node checks it against the current diagram and keeps it as widget state, so the selection survives a reload; a restored id the diagram no longer has is ignored.
Each node is a button, and one node is in the tab order. The key along the flow (Down for TB, Right for LR) follows an edge forward and the opposite key follows one back. The cross keys step within a layer, and Home and End go to the first and last node. Enter or Space selects the focused node, or clears it if it is already selected, and Escape clears the selection. A node's accessible name gives its label, shape and group, and the nodes it leads to, comes from and is linked with, each with the label of the edge between them (“leads to Ship (yes)”). The selected node marks its edges and neighbours with stroke width and dashes as well as colour, and a live region announces the change. A wide drawing keeps its size and scrolls inside its card, so the page never scrolls sideways. The diagram has no motion of its own and follows both themes.
The semantic document gives the node and edge counts, the layout and direction, and the selected node with its neighbours and their edge labels. A text alternative, also shown under the drawing, lists every node with its outgoing edges. See the Mermaid subset parser and the widget developer standard (§8.12).
Current limits. When two labelled edges leave the same node into the same gap, their labels can sit close together; labels always stay clear of nodes. Like the tree, a diagram cannot yet be placed as one part of a view Clark lays out.
Maps
When Clark has places to show, it can draw them on a map with canvas.map@1: points with labels, lines such as routes, and areas. The map is drawn over an offline basemap that ships with the app, so with the default settings a map makes no request beyond your node and nobody learns which part of the world you are looking at.
The basemap is Natural Earth 1:110m land, version 5.1.2, which is in the public domain. It is generated by a build script that pins the source file's SHA-256, and the map credits Natural Earth under every drawing.
What a map holds
Positions are WGS84 [longitude, latitude] in a strict subset of GeoJSON geometry: Point, LineString and Polygon, an outline with up to 15 holes, each ring closed. A map holds at most 200 features and 5,000 positions in total. An id is at most 120 characters, a label 120, a description 300 and the title 200. The map fits its features, or an optional view of { center, zoom }, with a whole zoom from 0 to 18, replaces the fitted view. Geocoding, routing, your device's location, vector tiles, 3D, clustering and editing are not part of this widget, and the map never asks for your location.
The node refuses a map before it is shown, and says why: coordinates outside the globe, an unknown geometry type, too many features or positions, over-long or repeated text, hidden characters, and any URL. A key that names a link (url, href, src, tile, endpoint and the like) or a value that is one (https://, //, data:, javascript:, blob:) is refused, so a map's props can never name a host. Places Clark puts on a map are Clark's statement, and the map carries no “live” badge.
Map tiles, only if you choose a provider
Map tiles. Maps draw an offline basemap and work fully without tiles, which are off by default. To add provider tiles, open Settings → Extensions → Map tiles and enter the provider's origin, tile path, attribution and maximum zoom. This sets your node's tile policy, the preference maps.tilePolicy, which names one provider. If the provider needs a key, enter it with the header or query parameter it goes in. The key is bound to the origin you entered it for: ClarkCant sends it only to that origin and never shows it again. You can also ask Clark to turn tiles on or off. Clark follows your execution policy: in Autonomous mode the change happens at once and can be undone in Settings; in Ask every time mode you approve it on a card. In Guarded mode, naming a provider asks on a card and turning tiles off happens at once, and Deny everything refuses both. Clark can never move your key. If Clark sets a provider that needs a key at a different origin, the map stays offline until you enter the key again for that provider. GET /map-tiles reports why maps are offline in its offline field: no-provider, key-unavailable (no usable key saved) or key-origin-mismatch (the saved key belongs to another origin).
AI clients over MCP, the WebSocket relay and clarkcant api cannot write the policy or the key directly: those routes answer 403 PERSON_ONLY, and a client that wants tiles changed asks Clark. The routes are listed in the node's API.
- Your node fetches the tiles itself. The page asks only your node, and never contacts the provider, so the page's content policy is unchanged.
- Only the one provider the policy names is asked, at a zoom up to its maximum (at most 19). Redirects are not followed.
- Only PNG or WebP tiles are served, checked by both the provider's content type and the bytes, at most 512 KiB each.
- Requests are rate limited to 12 a second with a burst of 48, and up to 256 tiles or 24 MiB are cached for an hour.
- The key is your node's own secret
maps:tiles, bound to one origin. Your node adds it as a header or query parameter only to requests to that origin. It never reaches the page, the map's props or state, logs, the cache key, an error message or the model. - Showing tiles tells the provider which area you are viewing, so the line under the map names the tile origin and its attribution.
- Setting the policy back to none turns tiles off at once: your node refuses every tile request from then on and asks nobody.
Selection, keyboard and the table
Choosing a feature sends map.select with { selectedId }, empty to clear it, and moving the map sends map.view with { center, zoom }. The node checks both against the current map and keeps them as widget state, so the selection and the view survive a reload. A pan is saved 400 ms after it settles, so a run of key presses is one write. In a view Clark lays out, map.select is also an event with a selectedId field that other parts can follow.
The map can be focused and used by keyboard:
- the arrow keys pan, and Shift pans further;
- + and - zoom, and 0 resets the view;
- N and P step through the features, and Escape clears the selection.
Dragging with a pointer pans too. On a touch screen, a swipe over a map you have not tapped scrolls the conversation; once you tap the map, a drag pans it. The zoom-in, zoom-out and reset buttons are 44 px. A live region states the view once it settles, and the selection. A pan slides only when motion is allowed; with reduced motion the view moves at once. The map follows both themes, and a narrow map moves its controls under the picture and draws its labels larger, without overflowing at 390 px.
Below the map, a table lists every feature with its kind and position. Its Select button selects the feature on the map and brings it into view, and selecting on the map highlights its row. That table is also the map's text alternative.
The semantic document gives the feature count and the count of each kind, the visible bounds and zoom, the selected feature's label and coordinates, and whether tiles are offline or from the policy's origin. See the map contract and bounds and the widget developer standard (§8.13).
Current limits. The map is one world that does not repeat: the view stops at the antimeridian, and a map does not wrap across the 180° meridian. The basemap, features and tiles are each drawn once, so they always agree.
Audio player and document preview
Clark can play a sound with canvas.audio@1 and show the text of a PDF or text file with canvas.document@1. The page never fetches anything for either widget. Clark names a source, and your node reads it, checks it under its media content policy and stores only what it checked.
Where the sound comes from
Clark names exactly one source, a title and, if it has one, a transcript of at most 4,000 characters:
- A file in this conversation, by its artifact or attachment id: a WAV you sent (the
audioattachment kind) or a WAV a package service rendered; - An
httpsURL on an origin your node's media policy allows. Your node fetches it once, checks it and keeps it as a sealed file of the conversation, granted to the player, in the same step that places the player. Clark can place that file again later by its id, and your node does not fetch it again.
Your node fills in the reference the page plays, the type, the length and the size, and for a fetched file the origin it came from. Clark cannot supply any of these, so a player never claims a type or a length nobody checked. The page only ever sees a reference to a file your node holds, never the outside URL. The same checks of type, size and length apply to an audio file you already hold.
Playing
The player uses the browser's own controls, keyboard included: focus it and press Space to play or pause. It never plays by itself, neither when it first appears nor when it comes back. It keeps whether it was playing, where it was and how long it is, written the same way as a video's, so after a reload it opens paused where you left it. A transcript, when there is one, is plain text in a section you can open with the keyboard, and a hidden character in it is drawn as a visible marker. Voice, the note added to your next turn and inspect_ui know the title, whether it is playing, its position and its length, and whether it has a transcript.
Previewing a document
Clark names a PDF or a text file in this conversation (plain text, Markdown, CSV, tab-separated values or JSON), by its artifact or attachment id. Your node reads its text, a PDF's through your node's own reader, and keeps at most 20,000 characters in at most 10 pages of at most 2,000 characters each, breaking at a line end or a space. A notice says when the preview was cut short and how much of it is shown. The preview is text only: pictures and layout are not shown, and nothing in the file is treated as markup or run. A hidden character is drawn as a marker, with a warning.
The page's text sits in a region a keyboard can reach. Tab moves to the Previous and Next buttons and Enter turns the page. At the first or last page the button stays focused and is announced as unavailable, a new page opens at its top, and the page number out of the total is announced politely. The page you are on is kept with the widget, so it is still open after a reload, and voice, the next-turn note and inspect_ui know it. A WAV is not a document, and the preview refuses it.
Both widgets follow both themes and fit at 390 px. With reduced motion they add no animation or transition. Neither can yet be placed as one part of a view Clark lays out: each is shown on its own, where your node checks its source. The Widget Library shows sample cards; the audio sample says it cannot be played rather than pretend.
The media content policy
Your node fetches audio from the web only from origins you list in CC_MEDIA_ORIGINS, a comma-separated list of bare https origins, at most 32. It is empty by default, so your node fetches nothing until you name an origin. A list with any entry that is not a bare https origin is ignored as a whole: your node allows nothing and says why once at startup. Each fetch follows these rules:
- Only
https, with no user name or password in the URL. - Redirects are followed only within the same origin, at most 3.
- A name that resolves to a loopback, private, link-local or other reserved address is refused, checked on the address actually dialled. An origin you wrote as an address or as
localhostnames that address and is allowed. - No cookie, authorization or referrer is sent.
- Only MP3, Ogg, WAV or WebM audio, checked against the bytes themselves; a compressed transfer is refused.
- At most 25 MiB and an hour long. A file that does not state its length is refused, because a bound that cannot be checked is not a bound. The whole fetch must finish within 30 s.
Every refusal ends with the rule it broke, as (media policy rule: <rule>), so Clark can tell you what to change. A file that passes counts against your storage. The page's own content policy is unchanged. See the rule names, the media content contract and the widget developer standard (§8.14 and §14.5).
Current limits. When a conversation loads, the page reads the whole file of every placed player, even though it plays nothing until you press play; reading it only when needed is tracked in #403. Each saved playback position is a full widget-state write, a cost tracked in #380.
Pictures and video in the conversation
A gallery or carousel keeps the picture you chose. The choice is stored with the widget, so it is still selected after a reload or a pin restore. A local video keeps whether it was playing, where it was and how long it is. When it comes back it opens paused at that position and never starts playing by itself.
Clark knows what you are looking at. Voice, the note added to your next turn and Clark's inspect_ui tool describe the selected picture (“showing picture 2 of 3”, with its alt text) or the video's playback state. While a video plays, its position is saved at most once every three seconds, and at once when you pause, seek or it ends. Saving when you leave the page is best-effort, so a “playing” state older than eight seconds is reported as paused at the last saved position. If your machine refuses a save, the widget says why beside it: a gallery or carousel shows the stored picture again, and a video stays where it is.
A view Clark lays out can include a gallery or carousel of your own imported pictures, newest first. Clark names only the widget and how it is wired; pictures it names are ignored. Choosing a picture sends media.select with { selectedIndex }, counted from 0, so another part of the view wired to the same value follows it and the view's state reports it.
The app's page and desktop window policy allow media-src 'self' blob:, only so a video can play from an object URL the app creates from bytes it fetched with your node's token. No remote media origin and no data: media are allowed.
Current limits. Your node cannot import video files yet, so a local video plays only from a reference your node already serves. A composed gallery or carousel keeps the pictures that were there when the view was laid out; pictures imported later appear only in a newly composed view. Each playback save is still a full widget action; reducing that cost is tracked in #380. See the widget developer standard (§8.11).
Quickstart
- Run a node. The installer sets one up; from a checkout it is
node apps/runtime/src/main.ts. It listens onhttp://127.0.0.1:8765, loopback only by default. - Find the token:
localTokenin<data-dir>/identity.json. The default data dir is~/.clarkcant; in Docker the data dir is/data(token in/data/identity.json). - Check the node and discover its surfaces. These three routes need no token:
export CLARKCANT_URL="http://127.0.0.1:8765"
export CLARKCANT_TOKEN="<token>" # localToken from <data-dir>/identity.json
# Public: no token needed
curl -s "$CLARKCANT_URL/health"
curl -s "$CLARKCANT_URL/.well-known/clarkcant.json"
curl -s "$CLARKCANT_URL/openapi.json"
/health reports liveness, the runtime platform and the negotiated protocol, and no node identity. /.well-known/clarkcant.json lists every surface (api, mcp, websocket, cli) and its endpoints. /openapi.json describes the stable REST surface.
Then send Clark a first message:
# 1. Create a conversation → 201 { "conversationId": "…", "homeNodeId": "…" }
curl -s -X POST "$CLARKCANT_URL/conversations" \
-H "Authorization: Bearer $CLARKCANT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "title": "From my app" }'
# 2. Talk to Clark in it
curl -s -X POST "$CLARKCANT_URL/conversations/<conversationId>/messages" \
-H "Authorization: Bearer $CLARKCANT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "text": "What can you do on this machine?" }'
Authentication and errors
- Every route except the three public ones needs
Authorization: Bearer <token>. The WebSocket sends it in its first frame instead. - A missing token and a wrong token both answer
401 UNAUTHENTICATED. - Errors are JSON with an HTTP status:
{ "code": "UNAUTHENTICATED", "message": "…" }
Keep the token private. It gives full access to your Clark. The node binds to loopback by default; --allow-public-bind exposes it and needs TLS in front. Sign-in with OAuth is not available: the bearer token is the only credential.
How Clark picks context
These environment variables on the node choose what context Clark sends the model with each message:
CLARKCANT_CONTEXT_PLANNER(default on): On, the memory brief and a fresh session's recap focus on the message being answered. Earlier matching messages from the conversation reach the model as labelled data, never as instructions. Background runs and task workers you started can read the same context on demand.offrestores the fixed recap (newest 12 messages) and memory brief (newest 12 notes), and stops background runs and task workers from receiving retrieved context. Two improvements stay in both modes: a memory brief that cannot be read gives a turn without it rather than a failed turn, and a turn can be stopped while its context is being read. The recap also reads the newest 40 messages in both modes. Only work a person asked for in the conversation receives retrieved context; tasks a peer delegated, an automation started, or the node raised itself get none.CLARKCANT_CONTEXT_DECIDER(defaultrank):jevlets Jev, your node's selector, which only chooses among options your node already allowed and never grants anything (how to configure it), reorder the top 8 matches when their ranking is close and its answer could change what is sent. Under progressive disclosure, it can also pick one tool family for a first message that names none. A failure or timeout keeps the deterministic order. Any other value isrank.CLARKCANT_TOOL_DISCLOSURE(defaultall):progressiveoffers the core tools plus the families the conversation's messages name, growing within a session. It stays off because an offline, in-sample estimate found it cost about 7% more once prompt-cache rewrites were counted. Any other value isall.
What goes to the Jev provider (only with CLARKCANT_CONTEXT_DECIDER=jev, and only when it is asked): the message being answered, redacted, at most 300 characters (400 for a tool-family choice), plus each candidate memory note or earlier message that is public or internal as a whole, redacted, at most 200 characters. Nothing else leaves the node, and Jev grants nothing.
Choosing the decision provider
Jev, from TypeSafe, answers your node's selector by default. The selector is separate from the conversation model: it only answers the small typed questions Clark asks while composing a reply. Instead of Jev you can choose Cloudflare Clef on Workers AI, or a decision model through OpenRouter's decisions API. Clark's policy (what is offered, what is redacted, the thresholds, the time budget and every fallback) is the same whichever provider answers, and every provider receives the same redacted request; only the endpoint, the credential and the pinned model differ. Changing provider changes who receives that request, so it is a data-sharing decision as well as a technical one. With OpenRouter two parties receive it: OpenRouter, and the company serving the model you pick.
Choosing it in Settings. Open Settings → AI & Routing → Decision provider, beside Provider sign-in and separate from the conversation model. The section shows the provider and model in effect, a badge saying what chose them (Settings, the environment, or the default), its status (ready, local only, misconfigured, no key, or off) with the reason and what to do about it, and the last call since the node started. Pick Follow environment, TypeSafe Jev, Cloudflare Clef or OpenRouter. Cloudflare adds its two models and an account-id field; OpenRouter adds a model-slug field, and nothing is saved until you enter a pinned slug (OpenRouter's own routers, such as openrouter/auto, are refused). Each provider has a key card that says where its key comes from (saved on its card, saved in Credentials for TypeSafe, the environment, or none). The Cloudflare and OpenRouter cards have Save and Remove; a key you type is cleared once saved and never shown again. The TypeSafe key has one place, the Credentials list on the same tab, so the TypeSafe card has no field of its own and its Go to Credentials button moves focus to that row's key field. Saving or removing the key there updates the card at once, without a reload. A reason the app does not know yet is shown as a generic message in your language. Your choice wins over the environment variables below, and Follow environment hands the choice back to them. A change applies from the next decision; the node does not restart. The same choice is available over the node's API, and only a person can make it: an AI client or another machine surface cannot choose which third party receives a decision.
GET /decision-provider: the provider and model in effect, what chose them, where its key comes from (vault,environmentornone, never the key), whether a call would be made and why not, and the outcome of the last call. Every reason, on the status and on the last call, carries a stablereasonCode(for exampleno-credential,budget-exhaustedorprovider-rejected-key) for a client to word in the person's language; the Englishreasonbeside it is for logs. A client that meets a code it does not know should show a generic message.PUT /decision-providerwith{"selection": {"provider": "cloudflare", "model": "clef"}},{"selection": {"provider": "openrouter", "model": "cloudflare/clef-flash"}},{"selection": {"provider": "typesafe"}}, or{"selection": null}to follow the environment.PUT /decision-provider/credentialwith{provider, value}saves a key, andDELETE /decision-provider/credential/<provider>removes it. Cloudflare and OpenRouter keys saved here are only ever used for decisions, and the general credential form refuses their names.
Choosing it in the environment. An operator who configures the node without Settings uses these variables:
CLARKCANT_DECISION_PROVIDER(defaulttypesafe):typesafe(Jev),cloudflare(Clef) oropenrouter. Any other value refuses every decision call rather than falling back to TypeSafe.CLARKCANT_DECISION_MODEL: the exact model id. With Cloudflare it is required and must becleforclef-flash. With OpenRouter it is required and must be a pinned slug such ascloudflare/clef-flashortypesafe/jev-1.13; a~alias and OpenRouter's own routers (openrouter/auto) are refused, because a router never answers as one pinned model. With TypeSafe it wins overCLARKCANT_JEV_MODEL(defaultjev-1.13.0) when set, and another provider's model id there is refused before any call.TYPESAFE_API_KEY: the TypeSafe credential. A key saved in Settings (the Credentials list on AI & Routing) wins over it.CLOUDFLARE_ACCOUNT_ID: Cloudflare only, 32 hexadecimal characters. The endpoint is built from it and cannot be overridden. An account id saved in Settings wins over it.CLOUDFLARE_API_TOKEN: Cloudflare only, a token allowed to run Workers AI. A token saved in the decision provider's Cloudflare card wins over it. The TypeSafe key is never used in its place, and the token is kept out of the commands the model runs, like other provider keys.OPENROUTER_API_KEY: OpenRouter only. A key saved in the decision provider's OpenRouter card wins over it. Decisions use it only when OpenRouter is the selected decision provider.
CLARKCANT_DECISION_PROVIDER=cloudflare
CLARKCANT_DECISION_MODEL=clef # or clef-flash
CLOUDFLARE_ACCOUNT_ID=<account-id> # 32 hexadecimal characters
CLOUDFLARE_API_TOKEN=<token> # allowed to run Workers AI
# or
CLARKCANT_DECISION_PROVIDER=openrouter
CLARKCANT_DECISION_MODEL=cloudflare/clef-flash # a pinned slug
OPENROUTER_API_KEY=<key>
Environment changes, including CLARKCANT_JEV_LOCAL_ONLY and CLARKCANT_JEV_ENABLED, still need a restart, and nothing in Settings can lift local-only.
When the provider is unavailable, your node falls back and says so. A missing credential, a malformed setting, CLARKCANT_JEV_LOCAL_ONLY=1 (which refuses every provider), a credential left in the request, a timeout, an error or an answer it cannot trust all end the same way: the call is reported unavailable with its reason, it is not retried, and the work goes on along the deterministic path. Composed surfaces compile without the selector, search ranks with BM25 and context keeps its ranked order. At startup the node prints one line about the selector, such as selector: clef-flash pinned on cloudflare, 4000 ms per turn or selector: disabled (no credential or local-only); composed surfaces use the deterministic path. Telemetry lines and stored decision records name the provider only when it is not TypeSafe. See the selector configuration.
Decision calls carry only public and internal content. Whichever provider answers, what a person, a file or a record supplied is limited to those two classes, and anything above them is removed before the request is built, never sent and filtered afterwards. A candidate that stands for your data (a search result, a memory note or an earlier message) is offered only when the whole record is within that limit; when fewer than two search results remain, the ranking stands and no provider is asked. Free text (your words, a directory name, a description, your own guardrail rules) is redacted, cut and checked again, and text still above internal is sent empty. When that empties the message or query the decision is about, no provider is asked and your node keeps its usual answer: its own ranking, every tool family, or no change to the turn. What your node writes itself is exempt, because a dated model id reads as a phone number: identifiers such as option ids, refs and counts, the node's fixed instructions, and catalogue descriptions such as a model route's alias (provider/modelId), a template label or a tool family's description. The credential check still covers them.
Size limits. A request over 64 KiB serialized is not sent. A provider's error body is never read: it is cancelled unread, and never returned, logged or stored. An answer over 256 KiB is not read past the limit and is treated as malformed, whichever provider or transport delivered it. Each case falls back as described above.
Switching back to TypeSafe. Choose TypeSafe (or "follow the environment") in Settings, or unset CLARKCANT_DECISION_PROVIDER (or set it to typesafe) and restart. A surface another provider chose still replays without asking any provider, and its record still names that provider and model. Rolling the node itself back to an older release is different: a release that does not know that provider cannot read a surface it chose, so replaying or refreshing it fails. Switch the provider back first, and keep a release that reads those surfaces for as long as they matter.
Checked live on 2026-10-08, with synthetic requests only. Cloudflare clef and clef-flash answered correctly both directly and through OpenRouter. On that day TypeSafe Jev did not answer in time, directly or through OpenRouter, so there is no fresh live result for it. OpenRouter marks its decisions API as alpha. Cloudflare's benchmarks of Clef against Jev are the vendor's numbers on the vendor's workload, which is why TypeSafe stays the default.
What a model may be sent
Every block your node adds to a model's context is labelled public, internal, confidential or secret, from its text alone and before anything is ranked or sent:
secret: a credential shape, such as a bearer token, a JWT, a PEM private key, an AWS access key id, a GitHub or Google API token, a password in a URL, an issued-prefix token (sk-,ghp_,xoxb-…) or a value assigned to a secret-named field. Code in that place is not a value: a schema call such asz.string(), a type, a member reference or a placeholder (${…},{{…}},<…>), in a field or a URL.confidential: an email address, a phone number or a home-folder path.internal: everything else a person or Clark wrote, including code identifiers such astoken_refresh_worker_2, commit hashes and digests. Memory notes are redacted when written, so they read asinternal.
A model profile may say what it receives with trustClass (local, first-party, approved-third-party or untrusted) and allowedDataClasses. By trust class, local may receive everything, including secret; first-party and approved-third-party up to confidential; untrusted only public. With both set, the profile receives only what both permit. A list with no trust class is taken as written, so it can add secret to an unlabelled profile. A profile with neither receives everything but secret, and a model several profiles name receives only what all of them permit.
With CLARKCANT_CONTEXT_PLANNER on, a block above the answering model's ceiling is left out of the recap, the memory brief, the earlier messages, the context a background run or task worker retrieves (including its read_context reads), project instructions, and the results of search_history, each judged on the whole stored entry, not only the snippet shown. Each says how many blocks were withheld, never what they said, and the recap does not point at a tool to read them back. Jev is offered only public and internal candidates.
Background work leaves out a model profile that may not receive the work's class (the class of the request or the task goal), whether the planner is on or off. When no profile qualifies, or routing fails, the work falls back to the node's configured model only if that model may receive what the work sends, with the retrieved context narrowed to that model first. When the class is what left every profile out, the node writes one JSON line to stderr (model-route, with the class and a count only); when routing itself fails, the line is marked route-failed and carries no error text. When neither a routed model nor the configured one may receive the work, it does not start and nothing is sent: a background run fails with a sentence naming the class, saying nothing was sent and what you can change, and a task is refused before its worker starts, with an audit record that names only the model and the class.
When a message is not sent
The ceiling is a hard limit on what a model is sent, not a routing preference. One check runs immediately before every send, against the model about to receive it, however that model was chosen. It enforces confidential and secret only: each of those a request carries must be allowed for that model. public and internal steer routing and what context is gathered, but never stop a message, so a profile limited to public still holds an ordinary conversation.
A message that carries confidential or secret data the chosen model may not receive is not sent, and Clark does not move it to another model for you. The reply says which class stopped it, that nothing was sent, and that your message and model choice are kept, and it says what you can change:
- choose a model that may receive the class, such as one running on this machine;
- allow the class for that model in Settings → AI & Routing;
- or send the message again without that part.
In English it reads, for example: “This message carries confidential data, and {model} may not receive confidential data, so nothing was sent to the model. Your message is saved and your choice of model is unchanged. To continue, choose a model that may receive confidential data (such as one that runs on this machine), allow confidential for that model in Settings → AI & Routing, or send it again without that part.”
If the model's ceiling could not be read, the reply says so instead of naming a ceiling; an ordinary message still goes, and one carrying confidential or secret data does not. When a provider refuses a turn and Clark moves to the fallback model, that model is checked the same way; if it may not receive the message, you read both why the chosen model did not answer and why the fallback was not sent the message. Each refusal writes one line to stderr (model-send-blocked) naming the class and the model, never the text.
Credentials are refused by default. A profile with no list receives everything but secret, so a credential-shaped string (an API key, a password, a bearer token, HTTP Basic credentials, a SendGrid key) is refused to a third-party model rather than sent. Obvious placeholders such as your_api_key, changeme, example or xxxx are not treated as credentials; a value with a digit, or any other real-looking value, still is. The credentials in a URL such as postgres://app:<password>@db.example.com are not read as an email address.
The check covers everything a turn sends: your words (including the text of attached text files), the recap, the memory brief, references, project instructions, earlier messages and what is on screen, a sentence steered into a running reply, and every tool result and tool error fed back to the model. It covers a background run's request and the context it retrieves, and a task's goal and project instructions before its worker starts. Three parts are handled without stopping the message:
- Tool results. A tool result above the answering model's ceiling is withheld from the model, which reads a note that it was withheld for its class, and any image in it is dropped. This includes file reads inside approved project folders: those results name the absolute path they read, so a file under your home folder is
confidential. You still see the real result in the conversation. - Your personal instructions. If they carry a class the model may not receive, they are left out of that message, and the message is still sent.
- Project context files. An
AGENTS.mdorCLAUDE.md, aSYSTEM.md, a skill or a prompt template that carries a class the session's model may not receive is not loaded for that model. A skill kept under your home folder is therefore left out for a model that may not receiveconfidential. Once per session, the model card of the next reply tells you which files, and whether your own instructions, were left out, by file name and class only.
Scope. The boundary does not cover image content, which is not classified (an image is dropped only with a withheld result); text the agent composes into its own system prompt, such as the working directory, a context file's path and tool descriptions; native Pi extensions, which are trusted code on your machine; or what a session already holds from earlier turns when a profile's ceiling is narrowed while it continues. CLARKCANT_CONTEXT_PLANNER=off turns withholding off, search_history included, but the check still runs, so a turn whose recap, memory or history carries a class above the answering model's ceiling is refused rather than sent. Routing by data class applies with the planner on or off. The ceiling decides what a model may be sent, never which tools it may call.
Project instructions
A project can keep instructions that apply only to part of it. Your node reads them only from a project inside a folder you already granted: .clarkcant/instructions.json holds up to 32 rules, and each included name is the file .clarkcant/instructions/<name>.md.
{
"version": 1,
"rules": [
{
"when": { "path": "src/payments/**", "operation": "write" },
"include": ["payments"],
"pin": false
}
]
}
whencan match onpath,operation,capability,role,skillandproject.operationisread,write,test,deployorcommand.pathis a glob relative to the project.**as a whole segment crosses folders, and a pattern with no/matches a file name anywhere. Case is folded on Windows and macOS and kept on Linux and every other platform, both in a glob and when your node finds which granted folder holds a path: on Windows and macOS a path typed in another case than the folder you granted still gets its instructions. Whether a path lies inside a project, and which project it is, are decided on the disk's real paths, so on a case-sensitive volume two folders whose names differ only in case stay two projects. A glob longer than 200 characters, with more than 16 wildcards or more than 32 segments leaves its rule out, and so does a rule that would take the file's globs over 4,000 characters in all;clarkcant instructions checkreports both, together with any other problem in the file. Matching is bounded whatever the file says: a path that would cost more than its matching budget, or one longer than 4,096 characters, meets nopathcondition, so guidance may be missing but is never stated for a path it is not about. One ask checks at most 96 touched paths: your session's newest 64, and at most 32 of the places a message points at.- A rule applies when what the work touches matches it: files and folders a message references (read), paths in the conversation's tool calls (a file tool's path, a command's working folder), and for a task, the folders it was granted, with writable folders counted as written.
- When a tool call makes a rule apply, the instruction is appended to that call's result; otherwise it goes into the next turn. An unpinned instruction is stated once per session. A pinned one (
"pin": true) is restated every turn it applies, so it survives a recap or a session rebuild. A task worker gets the instructions for its grant when it starts. - With links resolved, the project must lie inside the granted folder, and the rules file, the instructions folder and each instruction inside the project. A link that leads out is ignored.
- The file is a versioned contract: a file must state
"version": 1. An older file without a version is still read as version 1, and an editor's$schemakey is allowed. A file with a newer version is not read until you update ClarkCant. Any other unknown top-level key means the file is not read, and an unknown key inside a rule leaves out only that rule. clarkcant instructions check [file|folder]checks a file, or a project folder's.clarkcant/instructions.json, against the same contract your node reads with. It runs offline, without a node, and reports each problem on its own line, including a version that needs a newer ClarkCant. It also warns when a rule includes a name that has no.mdfile; a warning does not change the exit code.
Instructions reach the model as project data: a header says they come from the project's .clarkcant files, are neither your words nor your node's, and grant nothing. Each is wrapped in a tag carrying a code your node draws once per session (a rebuilt or handed-off session gets a new one) and states once, in its own guidance at the start of that session, as the only code that marks project guidance; a task worker's brief names its own code. An instruction cannot close its own block, even with a tag written in fullwidth or look-alike characters, split by invisible ones, decorated with combining marks or spaced out after < or /, and a project folder's name cannot break the tag that names its source, and a block copied into a file or a tool's output carries a code your node never stated to that session, unless the session itself repeated it. This is a signal the model reads, not an enforced boundary: the execution policy decides what any action may do, and instructions grant nothing either way. There is no opt-in step: a project's instructions apply because you granted its folder, and every effect still goes through the execution policy. Instructions are labelled like any other block and withheld above the model's ceiling. Limits: 8 names per rule, 4,000 characters per instruction, 6,000 per turn and a 64 KB rules file. A file your node cannot use is reported once on stderr (instructions-invalid, with the folder name and a reason: too-large, not-json, shape or unknown-version) and changes nothing. CLARKCANT_CONDITIONAL_INSTRUCTIONS=off (default on) turns this off.
Instructions from a package
An installed package can carry rules in the same contract through an instructions facet, which needs "schemaVersion": 3 in its clarkcant.json; a package declares at most one. A node that knows only version 2 refuses such a package as a whole rather than misreading it. Installing the package applies none of its rules:
- You turn them on, per project. Ask Clark to use a package's instructions in a project. Your execution policy decides that change like any other local write: it happens, it asks you on a card, or it is refused. A card covers the package at the version it showed: if the package is updated or rolled back while the card waits, approving it changes nothing and Clark has to ask again. The project must be a folder inside one you already granted, and turning instructions on grants no folder. Settings → Extensions → Installed on this node lists the projects where each package's instructions are on, with Turn off.
- Where they apply. Only to work inside that project, while it is still inside a granted folder.
pathglobs are relative to the project. A rule can include only its own facet's instructions, never the project's or another package's. - Your project comes first. The project's own instructions are stated first. Packages share what is left, at most 2,000 characters a turn in all, and one instruction is cut at 1,500 characters. A package's
pinis ignored. - Labelled as the package's. Each instruction is wrapped like project data, carries
package="<id>@<version>", is withheld above the model's ceiling, and is written to the audit log with the package id, version and instruction name, never its text. A withheld instruction is written once per conversation. - Removal. Turn off removes that one project, and its rules are gone from the next turn. Uninstalling the package turns its instructions off in every project right after the uninstall, and restoring it or installing it again clears anything left for it, so it starts with them off until you turn them on again. Your node also clears, when it starts, any left for a package that is not installed. Updating or rolling back the package keeps them on where they were.
clarkcant instructions check <package folder>checks a package's manifest and itsinstructionsfacet offline, and warns about apin, about an instruction longer than your node states, and about a facet kind it does not understand.
When a conversation gets a fresh session
A conversation keeps one model session until it fails, is evicted or changes to a model that cannot take it over (below). CLARKCANT_SESSION_POLICY (default off) decides at each turn whether to keep it:
observewrites one JSON line per turn to stderr (session-policy) with counts only, never text: the session's age, idle time, turns, context size, cache tokens, cost, latency, the share of the message's terms that are new, and what it would decide.rebuildalso acts. It never rebuilds a session's first turn or one with a turn running, and rebuilds only when the provider cache has gone cold (idle 5 minutes or more), the context holds at least 20,000 tokens, and at least 75% of the message's terms are absent from the session's last 6 messages. Between 50% and 75% it reuses the session, unlessCLARKCANT_CONTEXT_DECIDER=jev; then Jev is shown counts only, never text, and only a decisive answer counts.
A rebuild starts a fresh session briefed by the planned recap, restates instructions and tools, and leaves the conversation itself untouched. If the fresh session cannot be created, or the policy step fails, the turn continues on the old one. A message sent during a rebuild waits for it and lands in the new session, and Stop during a rebuild discards the new session and sends nothing. Any other value is off. The thresholds are judgements from a scripted cost simulation, not live measurements.
When you change the model
Changing the model or the thinking level never cuts off a reply Clark is writing: the change applies from your next message. Usually that message carries on in the same session on the new model, which keeps everything the session already holds, so nothing is briefed again. The session is kept only when the new model may receive every data class any model the session has run could, and nothing was left out of the session that the new model may receive. Otherwise, after a provider has refused a turn in that session, when you go back to a model's default thinking level, or when moving the session fails, your next message starts a new session on the new model, briefed with a recap of the conversation narrowed to what that model may receive. Clark never answers on the previous model instead. If the switch fails, the turn says so in your language and the conversation is left as it was, for example: “Could not switch this conversation to {provider/model}: {reason}. Your message is saved and the conversation is unchanged. Retry, or choose another model.” Local file paths are removed from the reason. If getting ready to answer takes longer than the turn's time budget, the turn stops with “Could not get ready to answer within {N} s, so this turn was stopped. Your message is saved. Retry, or choose another model if this keeps happening.”
How long a turn may run
By default a turn has no time limit: it runs until it is done, and you can press Stop at any time. To cap it, choose 5, 15, 30 or 60 minutes in Settings → AI & Routing → Thinking and time. An operator can also set CC_MODEL_MAX_WALL_CLOCK_MS. A turn that reaches its cap stops and says so in minutes; your message is kept.
Where to next
- REST & SSE: every route, request body and stream event.
- MCP: connect Claude Desktop, Cursor or your own MCP client.
- WebSocket: the frame protocol for browsers and long-lived clients.
- CLI: the
clarkcantcommand.