Cowork

Experimental

The Cowork adapter is experimental and not yet verified on a live Cowork build. Which hooks fire in Cowork is confirmed by a diagnostic probe, not from code, so install to-hook-probe first and confirm the fire matrix before relying on any automatic feature. See the rollout steps below.

Claude Cowork runs the same Claude Code engine inside a cloud or local VM. It uses the same Claude model ladder and runs Token Optimizer as the same plugin, but the plugin arrives by account sync, not from local files: Cowork does not read ~/.claude. So Cowork is not a separate runtime: detect_runtime() still returns claude inside Cowork, and is_cowork() is a refinement signal layered on top of it. The work to run on Cowork is packaging and distribution plus the assumed hook subset, to be verified on the target host, not a rewrite of the engine.

Since October 6, 2026, new Cowork tasks on Pro and Max plans run in the cloud. A cloud session leaves no local transcript on your machine.

How Token Optimizer reaches Cowork

Cowork does not read local plugin files. Plugins arrive in a Cowork session, cloud and local alike, through the Anthropic org admin plugin console, which account-syncs a pushed plugin into every org user’s sessions. So the Cowork “install” never edits local config. It builds a clean plugin payload for the admin to push.

bash install.sh --cowork

This builds the org-console payload under dist/cowork/ (the main plugin plus the to-hook-probe diagnostic) and prints the console steps. It never touches ~/.claude, and it refuses to write inside ~/.claude if pointed there. A self-contained Cowork plugin is also committed at cowork/token-optimizer/ under the distinct name token-optimizer-cowork, so a marketplace source lists it separately from the desktop token-optimizer entry.

Two distribution paths work:

• Org admin console. Register the payload as available to install, installed by default, or required. This is the org-wide path, and it is a licensing decision before a technical one (see the license note below).
• Personal upload. Claude desktop accepts a custom plugin uploaded by an individual user, which account-syncs into that user’s own sessions only. This runs the whole probe-and-verify flow today with no org-admin involvement, though availability tiers and the domain allowlist stay org-controlled.

Runtime detection

Inside Cowork, is_cowork() returns true while detect_runtime() still resolves to claude, so the engine paths are unchanged and the human-facing label reads Claude Code (Cowork). Any of these host markers is enough to detect Cowork:

Signal	Notes
CLAUDE_CODE_REMOTE=true	The only documented cloud-vs-desktop signal. Primary.
CLAUDE_CODE_CONTAINER_ID	Observed in every Cowork VM, undocumented. Fallback.
CLAUDE_PLUGIN_ROOT under /plugins/synced/	Where org-console account-synced plugins land.

AI_AGENT is deliberately not a signal: the local Claude Code CLI also exports AI_AGENT=claude-code_<version>_harness into every hook subprocess, so that marker cannot tell a Cowork VM from a desktop session.

Model-routing advice carries a cowork row that mirrors the Claude ladder exactly, with native thinking-budget effort, so a caller that has resolved is_cowork() gets a consistent table rather than a generic fallback.

The Cowork hook set

The Cowork packager retains a subset of Claude Code hook events. These are the adapter’s intended events, not proof that a live Cowork build fires them, and Keep-Warm is dropped because its keep-a-local-CLI-warm premise does not transfer.

Event	What rides it in Cowork
UserPromptSubmit	Per-turn: prompt-continuity hint, verbosity steer, quality-cache warn. Plus the run-once features that normally ride SessionStart: ensure-health, forced cache warm, compact-restore pointer.
PreToolUse	read_cache on Read, bash_hook on Bash, checkpoint trigger on Agent and Task, refetch guard on MCP.
PostToolUse	Large-result archiving and post-tool bookkeeping.
Stop	compact-capture and session-end flush.

SessionStart, PreCompact, PostCompact, SessionEnd, StopFailure, PostToolUseFailure, and CwdChanged are omitted from the payload. Without PostToolUseFailure, failed Bash output is not archived on Cowork. A missing event can remove automatic behavior, including in-place restore; the probe must establish the actual host matrix.

The design avoids a second plugin. The run-once SessionStart features are wired onto UserPromptSubmit in the master hooks.json behind a per-session run-once guard keyed on the session id. On native Claude Code, SessionStart runs them first and sets the marker, so the UserPromptSubmit copies no-op (one stat). In the Cowork payload, where SessionStart is omitted, the first UserPromptSubmit does the work. So the normal plugin is Cowork-native in place, and the Cowork packager is a trim to the intended events.

What works

Because Cowork runs the full engine and the four retained events carry the feature set, these work the same as on Claude Code, subject to live probe confirmation:

• Quality scoring and the per-prompt quality-cache warn
• Prompt-continuity hint and lean-output verbosity steering
• Read cache, delta read, and structure-map substitution (via read_cache on the Read PreToolUse hook)
• Bash output compression (after the command runs, on the PostToolUse hook)
• Checkpoint capture on subagent dispatch and MCP refetch guarding
• Large-result archiving on PostToolUse
• Session-continuity capture on Stop

Degraded

Feature	Behavior in Cowork	Cause
In-place compaction restore	Capture-only. State is saved on Stop (compact-capture) and read back on the next session’s first prompt (compact-restore, new-session-only). The in-place restore at the moment Cowork auto-compacts is lost.	PreCompact and PostCompact are not wired in the Cowork payload.

Not available or not measurable

• Keep-Warm is dropped. Its premise, keeping a local CLI warm, does not transfer to a VM.
• Local context footprint is a floor, not the whole picture. The platform overhead, the Cowork system prompt, the deferred MCP tool catalog, and the roughly 40 platform skills, is not measurable from inside a Cowork session, because there is no documented way to read a session’s own token usage from within it. The context command labels its total LOCAL FOOTPRINT (measurable) and prints a Cowork caveat, so the reported figure covers only the slice Token Optimizer can see and control (CLAUDE.md, skills, memory), never a fabricated platform number.
• OTel to trends.db ingestion is not built yet. The bundled collector captures and summarizes Cowork OTel and probe phone-home, but does not yet write the trends database or feed the dashboard.
• Cloud token accounting has no local window. Cloud sessions leave no local transcript, the Compliance API carries no token fields, and OTel is org-gated, so per-session cloud token figures are only available through org telemetry.

Doctor command

python3 skills/token-optimizer/scripts/cowork_doctor.py

The doctor reports what is verifiable from the local machine: the desktop build, the live domain-allowlist state, the local VM session tree, whether the payload is built with the right hook events, the probe fire matrix, and OTel wiring. What it cannot see, the org admin console state and whether hooks fired in a cloud session, it reports as NEEDS-LIVE so the live-verification checklist is explicit rather than silently green. It exits non-zero only on a real FAIL.

Updates and plugin reloads

Cowork installs arrive through Claude’s plugin sync, which swaps in each new version automatically. If you reload plugins or start a session in the moment an update is being swapped in, that session can keep a path to a temporary folder ending in ~g2 (or another ~g number) that Claude Code removes a few seconds later. You will see commands path not found, or Stop hook error: Failed to run: Plugin directory does not exist, on every hook in that session until it reloads. The update itself is fine: run /reload-plugins in the affected session (or restart it) and the errors stop. Sessions started before or after the update are not affected, and no reinstall or cleanup is needed.

License note

Token Optimizer is licensed PolyForm-Noncommercial-1.0.0, plus a written small business permission. An org-wide Cowork rollout at a company is commercial use, so an org-console push is a terms decision before it is a technical one: it needs a commercial license unless the whole company qualifies for the small business permission (fewer than 5 people and under $20k/month revenue). Personal, noncommercial use is what the noncommercial license covers.