CLAUDE.md · DeepMyst/Mysti

Sections

1. Project Overview
2. Build Commands
3. Development
4. Architecture
5. Visual observation (look / act)
6. Major subsystems
7. Token accounting, compaction and caching
8. CLI version detection
9. Updating the CLI backends
10. CLI resolution
11. Provider-native commands
12. Key Types (src/types.ts)
13. Constants (src/constants.ts)
14. Conventions
15. VSCode Integration Points
16. Webview UI
17. Extension Points

First lines (shown under the repo's Apache-2.0 license)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Mysti is a VSCode extension providing a unified AI coding assistant interface supporting 15 AI backends (Claude Code, OpenAI Codex, Google Gemini, Cline, GitHub Copilot, Cursor, OpenClaw, OpenCode, Qwen Code, Ollama, LocalAI, Hermes, Continue, OpenRouter, and Kimi Code). It features sidebar/tab chat panels, conversation persistence, multi-agent brainstorm mode (any 2 of 15 agents with 5 collaboration strategies), autonomous mode with safety classification, @-mention agent routing, permission controls, plan selection, context compaction, and a three-tier agent loading system for personas and skills.

## Build Commands

```bash
npm run compile           # Production build: generates the core-agent manifest, then webpack
npm run watch             # Dev build with watch mode (also regenerates the manifest first)
npm run lint              # check-provider-literals + core-manifest --check + eslint (src + media)
npm run typecheck         # TypeScript contract check
npm run test              # Vitest unit and Chromium browser suites
npm run test:vscode       # Extension-host integration tests (tests-vscode/, real VS Code, mocha)
npm run build:core-manifest # Regenerate src/generated/coreAgentManifest.ts from resources/agents/core
npm run sync-agents       # Sync plugins from wshobson/agents repo
npm run sync-agents:force # Force sync (ignores 24h cache)
npm run package           # vsce package (pinned vsce 3.9.2)
npm run check:package -- path/to.vsix # Verify the built archive
```

Two webpack bundles compile the same `tsconfig.json` (via `tsRule(instance)` in
`webpack.config.js`): the extension host bundle `dist/extension.js` (target
`node`, CommonJS2, entry `src/extension.ts`) and the **canvas webview renderer**
`dist/canvasWebview.js` (target `web`, ESM, entry `src/webview/canvas/index.ts`).
The canvas bundle deliberately has no `vscode`/node externals, so it can only
import real bundled code shared from the host (`CanvasSandbox`, `protocol.ts`,
`DocPatch`).

**Tests:** the repo has a Vitest suite (`npm test` → `vitest run`)
plus `npm run typecheck` for type-checking, plus extension-host
integration tests (`npm run test:vscode`). Run the Vitest suite and tsc BEFORE
and AFTER changes — regressions in the coordinator/provider code are caught
here. `vscode` is aliased to `tests/helpers/mockVscode.ts`.

**Mysti agent (coordinator):** alongside the registered backends, Mysti has a first-class *coordinator* agent (`settings.provider === 'mysti'`) that streams its own model (OpenRouter / DeepMyst gateway) and acts through native tools or a per-run nonce-fenced directive protocol parsed by `MystiTagScanner`. The ReAct loop is `ChatViewProvider._runMystiAgentic`; local reads use `MystiLocalTools`, optional local writes/shell use the default-off `mysti.mysti.localExecution` gate and `MystiLocalExec`/`MystiSandbox`; delegations run through the gated `CollaboratorPool`; durable background jobs use `BackgroundJobManager`. Plan 30: the default model is free Space Bunny Alpha (free-only chain); `delegate` also targets `mysti` (a native child in `src/coordinator/MystiSubagentRunner.ts` using the coordinator's own gated tools, report-only results, read-only children in parallel) and `advisor` (subscription CLI first, else one paid call under `PaidSpendGuard`). Every untrusted result re-entering the model is nonce-redacted and UNTRUSTED-fenced; the `dm_` gateway key is sent only to `*.deepmyst.com`; workspace settings may only lower authority (see `settingsClamp` and machine-scoped `mysti.mysti.*` settings).

Use Node from `.nvmrc` and `npm ci`. Lint and package shape are blocking CI
checks; do not lower rules or add blanket retries to get green. See
`docs/ARCHITECTURE.md` and `docs/MAINTENANCE.md` for the current module map and
release workflow. New chat interaction behavior belongs in `src/chat/` with
explicit panel/run ownership; webview routing uses the host's sender identity.

## Development

Press `F5` in VSCode to launch Extension Development Host for debugging. Set breakpoints in TypeScript files and filter Debug Console with `[Mysti]` for extension logs.

**CLI requirements**: At least one of these CLIs must be installed for the extension to function. The npm-based CLIs install identically on macOS/Linux/Windows; the non-npm ones differ by OS — the in-app setup wizard shows the OS-correct command automatically (each provider's `getInstallMethods()` is platform-tagged and filtered to `process.platform` extension-side; see `src/utils/platform.ts` `filterInstallMethodsForOS`).

npm-based (cross-OS):

- `npm install -g @anthropic-ai/claude-code` (Claude Code)
- `npm install -g @openai/codex` (OpenAI Codex)
- `npm install -g @google/gemini-cli` (Gemini)
- `npm install -g cline` (Cline)
- `npm install -g @github/copilot` (GitHub Copilot)
- `npm install -g openclaw@latest` (OpenClaw — then `openclaw onboard --install-daemon` for the Gateway daemon)
- `npm i -g opencode-ai@latest` (OpenCode)
- `npm install -g @qwen-code/qwen-code@latest` (Qwen Code)
- `npm i -g @continuedev/cli` (Continue — binary `cn`; models/keys configured in `~/.continue/config.yaml`, first interactive run walks through onboarding)

OS-specific (handled per-platform by the wizard):

- **Cursor** — macOS/Linux: `curl https://cursor.com/install -fsS | bash`; Windows (PowerShell): `irm 'https://cursor.com/install?win32=true' | iex` (binary is `cursor-agent`/`agent`; login: `agent login`)
- **Ollama** — Linux: `curl -fsSL https://ollama.com/install.sh | sh`; macOS: `brew install ollama` (or download from ollama.com); Windows: `OllamaSetup.exe` from ollama.com/download
- **LocalAI** — Docker (all OSes): `docker run -p 8080:8080 --name local-ai -ti localai/localai:latest`; macOS/Linux can also use the prebuilt binary; Windows requires Docker Desktop or WSL (there is no `localai.io/install.sh`)
- **Hermes** — macOS/Linux/WSL2: `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash`; Windows (PowerShell): `iex (irm https://hermes-agent.nousresearch.com/install.ps1)` (auth: `hermes setup` or `hermes setup --portal`; Mysti drives it over the ACP transport `hermes acp`)

## Architecture

### Core Pattern: Manager + Provider Facades

```
extension.ts (entry — activate() wires everything)
    │
    ├── Managers (business logic, src/managers/)
    │   ├── ContextManager        - File/selection tracking (per-panel contexts)
    │   ├── ConversationManager   - Message persistence via globalState
    │   ├── ProviderManager       - Provider registry facade
    │   ├── PermissionManager     - Access control
    │   ├── BrainstormManager     - Multi-agent orchestration (5 strategies)
    │   ├── ResponseClassifier    - AI-powered response analysis
    │   ├── PlanOptionManager     - Implementation plan extraction
    │   ├── SuggestionManager     - Quick action suggestions
    │   ├── SetupManager          - CLI auto-setup & authentication
    │   ├── AgentLoader           - Three-tier agent loading from markdown
    │   ├── AgentContextManager   - Recommendations & prompt building
    │   ├── AgentStudio           - Create/import/reload personas & skills (uses SkillDiscoveryService)
    │   ├── TelemetryManager      - Anonymous usage analytics
    │   ├── AutocompleteManager   - Autocomplete functionality
    │   ├── AutonomousManager     - Semi/full autonomous mode orchestration
    │   ├── MemoryManager         - Learning memory for autonomous preferences
    │   ├── SafetyClassifier      - Three-level safety evaluation (safe/caution/blocked)
    │   ├── CompactionManager     - Context overflow prevention
    │   ├── MentionRouter         - @-mention routing to specific agents
    │   ├── SlashCommandManager   - Unified slash command menu system
    │   ├── AgentLifecycleManager - Session idle timeout & child process tracking
    │   ├── ActiveModeManager     - OpenClaw daemon WebSocket connection
    │   ├── VisualSessionManager  - Warm dev-server + browser session (`look`/`act`)
    │   ├── ChannelBridge         - Routes messages between daemon channels and panels
    │   └── Later subsystems (all in src/managers/)
    │       ├── Canvas*            - Canvas design sessions (CanvasManager, CanvasSandbox,
    │       │                        CanvasOpParser/Executor, CanvasToolDispatch,
    │       │                        CanvasPromptBuilder, CanvasValidator, CanvasFormats,
    │       │                        CanvasMcpBridge, CanvasSessionLinker, CanvasThemePresets,
    │       │                        CanvasScaffolds, CanvasCapabilityRegistry, DesignSpecManager)
    │       ├── ArtifactStore      - Canvas artifact persistence (schema-versioned op log)
    │       ├── Desk*              - Cross-machine teamwork (DeskPairing, DeskPeerBook,
    │       │                        DeskPairingFlow, DeskAudit, DeskStandup, DeskServingGate,
    │       │                        DeskProposalStore, TeamPresenceManager)
    │       ├── CheckpointManager  - Shadow-repo snapshot before each turn + rewind
    │       ├── SmartCompactor     - Cache-aware compaction (+ SavingsLedger, RetrievalCoordinator)
    │       ├── BoostManager       - One-switch measured-defaults overlay (Plan 24)
    │       ├── MystiOrchestratorManager - DAG decompose/execute/synthesize for @mysti
    │       ├── CollaborationManager    - Collaboration-role routing (advisor/critic/…)
    │       ├── DeepMystAuthManager     - Signed-in DeepMyst account (`dm_` key)
    │       ├── ConnectionsPanelManager - DeepMyst Connections panel + MCP broker wiring
    │       ├── AnnouncementManager     - New-model notifications (with ModelAnnouncementService)
    │       ├── ProjectContextManager   - Project-level context
    │       ├── VisualTestManager       - Visual test dashboard
    │       ├── EngagementManager       - Onboarding/engagement tips
    │       └── CommitSignatureManager  - Team commit attribution (Desk)
    │
    └── ChatViewProvider (UI coordinator, src/providers/ChatViewProvider.ts)
            │
            ├── Webview UI (src/webview/webviewContent.ts — embedded HTML/CSS/JS)
            │
            └── Providers (CLI integrations, src/providers/<name>/)
                ├── ClaudeCodeProvider  (extends BaseCliProvider)
                ├── CodexProvider       (extends BaseCliProvider)
                ├── GeminiProvider      (extends BaseCliProvider)
                ├── ClineProvider       (extends BaseCliProvider)
                ├── CopilotProvider     (extends BaseCliProvider)
                ├── CursorProvider      (extends BaseCliProvider)
                ├── OpenClawProvider    (extends BaseCliProvider + Gateway WebSocket)
                ├── OpenCodeProvider    (extends BaseCliProvider)
                ├── QwenCodeProvider    (extends BaseCliProvider)
                ├── OllamaProvider      (extends BaseCliProvider)
                ├── LocalAIProvider     (extends BaseCliProvider)
                ├── HermesProvider      (extends BaseCliProvider, ACP JSON-RPC via persistent process)
                ├── ContinueProvider    (extends BaseCliProvider, cn headless print mode)
                ├── OpenRouterProvider  (extends BaseCliProvider, OpenAI-compatible SSE API — no CLI)
                └── KimiCodeProvider    (extends BaseCliProvider, ACP transport via `kimi` CLI)
```

`src/providers/manus/ManusProvider.ts` is legacy, unregistered code — it was
removed from `ProviderRegistry` and from the `ProviderType`/`AgentType` unions;
do not revive it. The 15 registered providers are: Claude Code, Codex, Gemini,
Cline, Copilot, Cursor, OpenClaw, OpenCode, Ollama, LocalAI, Qwen Code, Hermes,
Continue, OpenRouter, Kimi Code.

Lifecycle services live in `src/services/` alongside the providers (`CliDiscoveryService`,
`CliUpdateService`, `ModelRegistryService`, `ModelAnnouncementService`, `NativeCommandDiscovery`,
`CollaboratorPool` for gate dispatch, `CoordinatorModelClient`/`OpenRouterClient`/`DeepMystGatewayClient`
for the coordinator's own model, `MystiLocalTools`/`MystiLocalExec`/`MystiSandbox`/
`MystiMemoryStore` for the standalone agent, `McpClient`/`McpConfigManager`/`DeepMystClient`
for brokered tools, `BrowserManager`/`visualTestPolicy`/`PageObservationService` for `look`/`act`,