Mysti Architecture

Technical documentation for contributors and developers.

Table of Contents

• Project Structure
• Core Components
• Data Flow
• Type System
• Extension Points

---

Project Structure

Mysti/
├── src/
│   ├── extension.ts               # Extension entry point
│   ├── types.ts                   # Shared type definitions
│   ├── constants.ts               # Configuration constants
│   ├── managers/                  # Business logic managers
│   │   ├── ContextManager.ts
│   │   ├── ConversationManager.ts
│   │   ├── ProviderManager.ts
│   │   ├── BrainstormManager.ts
│   │   ├── PermissionManager.ts
│   │   ├── ResponseClassifier.ts
│   │   ├── PlanOptionManager.ts
│   │   ├── SuggestionManager.ts
│   │   ├── AutocompleteManager.ts
│   │   ├── AgentLoader.ts            # Three-tier agent loading from markdown
│   │   ├── AgentContextManager.ts     # Agent recommendations & prompt building
│   │   ├── AgentLifecycleManager.ts   # Session lifecycle & idle timeout
│   │   ├── SetupManager.ts           # CLI auto-setup & authentication
│   │   ├── TelemetryManager.ts       # Anonymous usage analytics
│   │   ├── AutonomousManager.ts      # Autonomous mode orchestration
│   │   ├── MemoryManager.ts          # Long-term preference learning
│   │   ├── SafetyClassifier.ts       # Operation safety classification
│   │   ├── CompactionManager.ts      # Context window compaction
│   │   ├── MentionRouter.ts          # @-mention parsing & routing
│   │   └── SlashCommandManager.ts    # Centralized slash command registry
│   ├── providers/                 # AI provider implementations
│   │   ├── ChatViewProvider.ts    # Main UI coordinator
│   │   ├── ProviderRegistry.ts    # Provider registration & discovery
│   │   ├── base/
│   │   │   ├── IProvider.ts       # Interfaces + persona definitions
│   │   │   └── BaseCliProvider.ts # Abstract CLI provider base
│   │   ├── claude/
│   │   │   └── ClaudeCodeProvider.ts
│   │   ├── codex/
│   │   │   └── CodexProvider.ts
│   │   ├── gemini/
│   │   │   └── GeminiProvider.ts
│   │   ├── cline/
│   │   │   └── ClineProvider.ts
│   │   ├── copilot/
│   │   │   └── CopilotProvider.ts
│   │   ├── cursor/
│   │   │   └── CursorProvider.ts
│   │   ├── openclaw/
│   │   │   └── OpenClawProvider.ts
│   │   ├── opencode/
│   │   │   └── OpenCodeProvider.ts
│   │   ├── qwen/
│   │   │   └── QwenCodeProvider.ts
│   │   ├── ollama/
│   │   │   └── OllamaProvider.ts
│   │   ├── localai/
│   │   │   └── LocalAIProvider.ts
│   │   └── manus/
│   │       └── ManusProvider.ts   # Experimental HTTP API provider
│   ├── mcp/
│   │   └── permissionServer.ts    # MCP permission intermediary
│   ├── utils/
│   │   ├── validation.ts          # Model name validation
│   │   ├── processTree.ts         # Cross-platform child process scanning
│   │   └── platform.ts            # Platform-specific helpers
│   └── webview/
│       └── webviewContent.ts      # HTML/CSS/JS for UI
├── resources/
│   ├── Mysti-Logo.png
│   ├── icon.svg
│   ├── icons/                     # UI icons
│   ├── agents/                    # Agent definitions (markdown)
│   │   ├── core/                  # Bundled agents
│   │   └── plugins/               # Synced community agents
│   ├── marked.min.js
│   ├── prism-bundle.js
│   └── mermaid.min.js
├── package.json
├── tsconfig.json
├── webpack.config.js
└── docs/
    ├── ARCHITECTURE.md
    ├── FEATURES.md
    ├── PROVIDERS.md
    ├── BRAINSTORM.md
    ├── PERSONAS-AND-SKILLS.md
    ├── AUTONOMOUS-MODE.md
    ├── MENTIONS.md
    ├── COMPACTION.md
    └── screenshots/

---

Core Components

Entry Point: extension.ts

The extension entry point wires everything together:

• Instantiates all managers
• Creates ChatViewProvider with all dependencies
• Registers commands and keybindings
• Sets up view providers and context subscriptions

Managers

ContextManager

Manages code context for AI conversations with per-panel isolation.

Key Design:

• _panelContexts: Map<string, ContextItem[]> for per-panel context isolation
• Auto-context tracks active editor
• Language detection for 30+ languages

Key Methods:

addFile(uri: vscode.Uri, panelId?: string): void
addSelection(editor: vscode.TextEditor, panelId?: string): void
clearPanelContext(panelId: string): void
getContextForPrompt(panelId?: string): ContextItem[]

ConversationManager

Persistent conversation storage using VSCode's globalState.

Key Methods:

createConversation(settings: Settings): Conversation
addMessage(id: string, message: Message): void
updateAgentConfig(id: string, config: AgentConfiguration): boolean

ProviderManager

Facade over the ProviderRegistry for provider management.

Key Methods:

sendMessage(content, context, settings, ...): AsyncGenerator<StreamChunk>
sendMessageToProvider(providerId, ...): AsyncGenerator<StreamChunk>
cancelRequest(panelId?: string): void

BrainstormManager

Orchestrates multi-agent team collaboration using structured reasoning frameworks.

Key Design:

• Per-panel sessions via _panelSessions: Map<string, BrainstormSession>
• 5 collaboration strategies: quick, debate, red-team, perspectives, delphi
• Parallel discussion via _interleaveGenerators()
• Convergence detection via agreement/disagreement keyword tracking

Brainstorm Flow:

1. User submits query
2. Individual Phase: Each agent analyzes independently (parallel)
3. Discussion Phase: Strategy-specific role-based discussion
   - Debate: Critic vs Defender
   - Red-Team: Proposer vs Challenger
   - Perspectives: Risk Analyst vs Innovator
   - Delphi: Facilitator vs Refiner
4. Convergence Check: Track agreement, optionally exit early
5. Synthesis Phase: Designated agent creates unified solution

Key Methods:

startBrainstorm(query, context, config, panelId): AsyncGenerator<BrainstormStreamChunk>
cancelBrainstorm(panelId?: string): void

AutonomousManager

Enables AI to work independently with configurable safety controls.

Key Design:

• Integrates SafetyClassifier for operation classification
• Integrates MemoryManager for learned preference queries
• Continuation modes: goal-based and task-queue
• Audit logging of all autonomous decisions

Key Methods:

activate(config: AutonomousConfig): void
deactivate(): void
handlePermission(request: PermissionRequest): AutonomousDecision
handleQuestion(question: AskUserQuestionData): AutonomousDecision

SafetyClassifier

Classifies operations into safety levels for autonomous mode.

Safety Levels:

• safe: Auto-approve (read-only, tests, version checks)
• caution: Mode-dependent (file create/edit, unknown commands)
• blocked: Always deny (deletion, force push, sudo, chmod 777)

Safety Modes: conservative, balanced, aggressive

MemoryManager

Long-term memory for learning user preferences.

Key Design:

• Dual-layer storage: VSCode globalState (fast) + ~/.mysti/memory/preferences.json (persistent)
• Confidence decay (0.95/day) ensures recent decisions are weighted more
• Auto-pruning when over capacity (default 500 entries)

Categories: permission-preference, question-preference, project-context

CompactionManager

Prevents context window overflow via smart conversation compaction.

Key Design:

• Per-panel cumulative token tracking (input, output, cache read, cache creation)
• Threshold-based triggering (default 75%)
• Two strategies: native-cli (/compact) and client-summarize
• Brainstorm agents tracked independently via panelId-brainstorm-agentId keys

MentionRouter

Handles @agent and @file mentions in user messages.

Key Design:

• File mentions resolve to transient ContextItems
• Agent mentions generate task lists (heuristic-based, AI fallback)
• Sequential execution with dependency tracking
• Auto-retry failed sub-agent tasks

SlashCommandManager

Centralized registry for slash commands.

Key Design:

• Organized by sections: Context, Model, Customize, Commands, Settings, Support
• Provider-specific commands: /compact (Claude), /thinking (Claude), /profile (Codex), /plan-act (Cline)
• QuickPick dialogs for model, provider, mode selection

AgentLifecycleManager

Manages agent session lifecycle.

Key Design:

• Per-panel session tracking (active/busy/idle/shutting-down)
• Configurable idle timeout (default 1 hour)
• Cross-platform process tree tracking via pgrep/wmic
• Child process protection — blocks shutdown if active builds detected

PermissionManager

Handles permission requests for file operations.

Key Methods:

createRequest(type, details): PermissionRequest
resolveRequest(id, decision): void
checkPermission(type, path): boolean

Other Managers

• ResponseClassifier: AI-powered response analysis using Claude Haiku
• SuggestionManager: Context-aware quick action suggestions
• AgentLoader: Three-tier progressive loading for agent definitions
• AgentContextManager: Builds agent context for prompt injection with token budgets
• SetupManager: CLI auto-setup and authentication
• TelemetryManager: Anonymous usage analytics via Application Insights

Providers

Per-Panel Session Isolation

Provider instances are singletons, but mutable state is per-panel:

// Each provider tracks sessions per panel
private _panelSessions: Map<string, PanelSessionState> = new Map();

// Base session state
interface PanelSessionState {
  panelId: string;
  process: ChildProcess | null;
  sessionId: string | null;
  autonomousMode: boolean;
}

Each provider subclass extends with its own session type (e.g., ClaudeSessionState, CodexSessionState).

BaseCliProvider

Abstract base class implementing common CLI functionality.

Key Methods:

// Build prompt with context, persona, skills
protected buildPrompt(content, context, conversation, settings, persona?, agentConfig?): string

// Build CLI arguments — takes session (not boolean)
protected abstract buildCliArgs(settings: Settings, session: PanelSessionState): string[]

// Parse provider-specific output — takes session for per-panel parse state
protected abstract parseStreamLine(line: string, session: PanelSessionState): StreamChunk | null

// Process CLI output stream
protected *processStream(stderrCollector): AsyncGenerator<StreamChunk>

Provider Implementations

Provider	Type	Key Differences
ClaudeCodeProvider	CLI	Thinking mode, native /compact, MCP permission server
CodexProvider	CLI	Profile switching
GeminiProvider	CLI	Thinking support, Google ecosystem
ClineProvider	CLI	Plan/Act mode
CopilotProvider	CLI	14+ models via GitHub subscription
CursorProvider	CLI	Auto model selection, cumulative streaming dedup
OpenClawProvider	CLI + WebSocket	Dual-transport: WebSocket gateway + CLI fallback
ManusProvider	HTTP API	Async polling workflow (experimental)

MCP Permission Server

Intermediary between Claude Code CLI and VSCode for fine-grained permission control.

Flow:

Claude CLI --stdin/stdout--> MCP Server --HTTP--> VSCode Extension --postMessage--> Webview UI

ChatViewProvider

Main UI coordinator and webview provider.

Responsibilities:

• Webview creation and management
• Per-panel state (conversations, processes)
• Message routing between webview and all managers
• Threads panelId to all context/session/cancel calls

Constructor (dependency injection):

constructor(
  extensionUri, extensionContext,
  contextManager, conversationManager, providerManager,
  suggestionManager, brainstormManager, permissionManager,
  setupManager, telemetryManager, autonomousManager,
  memoryManager, compactionManager
)

---

Data Flow

Message Flow

User Input (Webview)
       ↓
ChatViewProvider.handleMessage()
       ↓
MentionRouter.parse()  ← Check for @-mentions
       ↓
[If @-mentions: Generate task list → Execute sub-agents sequentially]
       ↓
ProviderManager.sendMessage()
       ↓
BaseCliProvider.sendMessage()
       ↓
[Spawn CLI Process]
       ↓
BaseCliProvider.processStream()
       ↓
[Parse JSON chunks per panel session]
       ↓
StreamChunk events → CompactionManager.trackUsage()
       ↓
ChatViewProvider → Webview
       ↓
UI Update

Brainstorm Flow

User Query
       ↓
BrainstormManager.startBrainstorm()
       ↓
┌──────────────────────────────────────────────┐
│ Individual Phase (Parallel)                  │
│ ┌──────────┐ ┌──────────┐                   │
│ │ Agent 1  │ │ Agent 2  │                   │
│ │ (stream) │ │ (stream) │                   │
│ └──────────┘ └──────────┘                   │
└──────────────────────────────────────────────┘
       ↓
┌──────────────────────────────────────────────┐
│ Discussion Phase (strategy-dependent)        │
│ Parallel via _interleaveGenerators()         │
│ Roles assigned by strategy:                  │
│   Debate: Critic vs Defender                 │
│   Red-Team: Proposer vs Challenger           │
│   Perspectives: Risk Analyst vs Innovator    │
│   Delphi: Facilitator vs Refiner             │
│                                              │
│ Convergence tracked per round                │
│ Auto-exit if agents converge                 │
└──────────────────────────────────────────────┘
       ↓
┌──────────────────────────────────────────────┐
│ Synthesis Phase                              │
│ ┌──────────────────────────────────────────┐ │
│ │ Synthesis Agent combines all perspectives│ │
│ │ Fallback: other agent → raw concat       │ │
│ └──────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘
       ↓
Unified Solution

@-Mention Flow

User: "@claude Write tests, then @gemini review them"
       ↓
MentionRouter.parse()
       ↓
Generate Task List (heuristic or AI)
  Task 1: { agent: claude, type: execute, task: "Write tests" }
  Task 2: { agent: gemini, type: execute, task: "Review tests" }
       ↓
Execute Task 1 → Stream Claude response
       ↓
Build context from Task 1 response
       ↓
Execute Task 2 → Stream Gemini response (with Task 1 context)
       ↓
Return combined results

Autonomous Flow

Permission/Question from CLI
       ↓
AutonomousManager.handlePermission() / handleQuestion()
       ↓
SafetyClassifier.classify(operation)
       ↓
[If safe]: Auto-approve → audit log
[If caution]: Check safety mode → approve/deny/ask user
[If blocked]: Auto-deny → audit log
       ↓
MemoryManager.query() → Check learned preferences
       ↓
Decision → audit log → notify ChatViewProvider

---

Type System

Core Types

// Provider types (7 providers + manus experimental)
type ProviderType = 'claude-code' | 'openai-codex' | 'google-gemini' |
                    'cline' | 'github-copilot' | 'cursor' | 'openclaw';
type AgentType = ProviderType;

// Streaming
interface StreamChunk {
  type: 'text' | 'thinking' | 'tool_use' | 'tool_result' | 'error' | 'done' | 'session_active';
  content?: string;
  toolCall?: ToolCall;
  sessionId?: string;
  usage?: UsageStats;
}

// Brainstorm
type CollaborationStrategy = 'quick' | 'debate' | 'red-team' | 'perspectives' | 'delphi';
type DiscussionRole = 'critic' | 'defender' | 'proposer' | 'challenger' |
                      'risk-analyst' | 'innovator' | 'facilitator' | 'refiner';

// Autonomous
type SafetyLevel = 'safe' | 'caution' | 'blocked';
type AutonomousContinuationMode = 'goal' | 'task-queue';

// @-Mentions
interface MentionTask {
  type: 'execute' | 'switch';
  agent: AgentType;
  task: string;
  order: number;
}

// Compaction
type CompactionStrategy = 'native-cli' | 'client-summarize';
type CompactionStatus = 'idle' | 'evaluating' | 'compacting' | 'complete' | 'error';

---

Extension Points

Adding a New Provider

1. Create provider class extending BaseCliProvider in src/providers/newprovider/
2. Implement abstract methods: discoverCli(), getCliPath(), buildCliArgs(), parseStreamLine(), getAuthConfig(), checkAuthentication(), getAuthCommand(), getInstallCommand()
3. Register in src/providers/ProviderRegistry.ts (_registerBuiltInProviders())
4. Add type to ProviderType union in src/types.ts
5. Add agent style in BrainstormManager.ts AGENT_STYLES record
6. Add settings in package.json (mysti.* settings)

Adding a New Persona/Skill (Markdown)

Create a markdown file with YAML frontmatter in one of the agent directories:

Location	Scope	Priority
.mysti/agents/personas/ (or skills/)	Workspace	Highest
~/.mysti/agents/personas/	User	Medium
resources/agents/core/personas/	Core	Lowest

See Personas & Skills documentation for the full format.

---

Build & Development

Commands

npm install                # Install dependencies
npm run watch              # Development build with watch
npm run compile            # Production build
npm run lint               # ESLint check
npm run sync-agents        # Sync community agents
npx vsce package           # Package extension

Debugging

1. Open project in VSCode
2. Press F5 to launch Extension Development Host
3. Set breakpoints in TypeScript files
4. Filter Debug Console with [Mysti] prefix