Damocles

A powerful AI coding assistant, just keep in mind that just because something works doesn't mean it's good.

Chat interface with Edit tool cards showing syntax-highlighted inline diffs

Plan View displaying implementation plans for review

Subagent View showing nested agent actions with real-time tool visualization

• Chat Interface: Integrated chat panel for conversing with Claude — available as a secondary sidebar view (right side) or an editor panel (Ctrl+Shift+U). Both modes support all features and can run simultaneously with independent sessions

• Collapsible User Messages: Long user-message bubbles collapse by default (canvas and pinned sticky header alike) with a chevron toggle. Expansion state follows the message across inline↔pinned transitions. Drag the handle below an expanded bubble to set the scroll-cap height — the value becomes the global default and persists across webview reloads. The pinned sticky header can also be hidden entirely via the × button; when hidden, a small floating pin chip at the top-right of the chat expands on hover to preview the active pinned message and click-to-restore. Hidden state persists globally via damocles.pinnedHeaderHidden. Queued / injected messages (sent mid-stream) are skipped by the sticky header and never pin

• Code Assistance: Get help with coding, debugging, refactoring, and more

• Syntax Highlighting: Shiki-powered code blocks with VS Code-quality highlighting and one-click copy

• Diff Approval: Review and approve file changes with syntax-highlighted unified diffs (supports concurrent diffs)

• Inline Diff Preview: Edit/Write tool results show inline diff previews with click-to-expand full-panel view

• Tool Visualization: See what tools Claude is using in real-time with expandable details. Each completed tool card shows a subtle duration badge (123ms / 1.2s / 1m 23s) sourced from the SDK's PostToolUseHookInput.duration_ms

• Tool Overlays: Click tool cards to view full output in a full-screen overlay — supports built-in tools (Bash, PowerShell, Read, Grep, Glob, WebFetch, WebSearch, ToolSearch, CronCreate, CronDelete, CronList) with syntax highlighting or markdown rendering, and MCP tools with markdown output and image rendering (base64 image blocks displayed as thumbnails with click-to-enlarge lightbox). Read overlays show a file metadata card with line range, total lines, and a progress bar for partial reads. Cron tool overlays show human-readable schedules, job IDs, recurring/one-shot badges, and job lists

• Subagent Visualization: Nested view of Task tool calls showing agent type, model, tool calls, results, and real-time progress summaries. Background agents display a "Background" badge

• Background Tasks: Track background agent tasks and run_in_background Bash shells (e.g. "run sleep 300 in the background") with a dedicated overlay showing status, elapsed time, progress summaries, token/tool stats, and stop/dismiss actions. Results appear as labeled assistant messages. Indicator pill in session stats shows active task count

• Workflows: When Claude runs a dynamic multi-agent Workflow, a dedicated card and 3-view overlay (workflow list → detail → per-agent drill-in, with Agents/Result tabs) track it live. Per-agent cards stream as the run progresses — spinner while running, checkmark on completion, click to open the agent's full transcript — and the script's structured return value renders as formatted sections rather than raw JSON. An indicator pill shows the active workflow count. Enabled by the Ultracode reasoning option (or a workflow prompt)

• Streaming Responses: Watch Claude's responses as they're generated

• Refusal Cards: When the model declines a turn, a dedicated refusal card shows the explanation and an optional category pill (cyber / bio) instead of a generic error line. Detection is structured (SDK stop_reason: "refusal"), never text-matched

• Model Fallback Notices: When the engine swaps to a fallback model mid-session (primary overloaded, no access, server errors), an inline divider notice shows from → to with the trigger. Survives reload and rewind/fork; the primary model is retried on your next message

• @ Mentions: Type @ to reference workspace files or agents (@agent-Explore, etc.) with fuzzy search autocomplete

• Custom Agents: Define custom agents in .claude/agents/*.md (project) or ~/.claude/agents/*.md (user)

• Voice Input: Three modes via damocles.voice.mode:

  • off — voice disabled, mic button hidden.
  • push-to-talk (cloud STT) — click the microphone in the chat input to dictate messages. Supports OpenAI Whisper, Deepgram, and Google Cloud STT. Audio is recorded extension-side using native platform APIs (Windows/macOS/Linux) and transcribed via your configured provider. Configure provider, API key, and language in the settings panel.
  • wake-word (local Jarvis) — hands-free. Say "Hey Jarvis, …" and Damocles transcribes once you stop speaking; optionally speaks the assistant's reply aloud. A Python sidecar runs OpenWakeWord + Silero VAD + Parakeet TDT 0.6B v2 ASR + optional VibeVoice-Realtime TTS. Fully on-device — no audio bytes or transcript text ever leave your machine. Wake phrase is stripped before transcription via a two-layer defense (ASR offset + regex). VRAM ~3.7 GB with TTS, ~2.2 GB without; CPU fallback automatic. On Linux/macOS the installer surfaces actionable per-distro commands if a C++ toolchain or PortAudio is missing (apt install build-essential libportaudio2 on Debian/Ubuntu/WSL, brew install portaudio on macOS, etc.); on WSL2 with a CUDA GPU it falls back to /usr/lib/wsl/lib/nvidia-smi for driver detection. Full guide: docs/voice-jarvis-mode.md.

  Note: Requires local audio hardware — not available when connected to a remote host via SSH (the extension host runs server-side where no microphone is present).

• Image Attachments: Paste images from clipboard directly into chat (supports PNG, JPEG, GIF, WebP up to 5MB)

• IDE Context: Automatically include the active file or selected code in your message (toggleable in input bar)

• Slash Commands: Type / for built-in commands (/clear, /compact, /rewind, /btw, etc.) and custom commands from .claude/commands/

• Prompt History: Navigate previous prompts with arrow keys (shell-style)

• Prompt Navigator: Ctrl+K / Cmd+K opens a searchable overlay listing every user prompt in the active session — grouped by task node in recall mode, flat list otherwise. Each row shows index, time, recall-mode node badge, tools invoked during the response, and a kebab menu with Copy / Use as draft / Rewind to here. Type to fuzzy-match prompt text, tool names, or node titles; arrow keys navigate, Enter jumps to the bubble in the canvas (with a primary-color flash ring), Escape closes. The header chip shows live prompt count plus the platform-correct keybind (⌘K on macOS, Ctrl+K elsewhere). Each user bubble also exposes the same actions via a hover-revealed kebab so mid-canvas navigation never requires the overlay

• Session Management: Create, rename, tag, resume, delete, and search sessions with confirmation. Tags are persisted via SDK APIs and shown as badges in the session picker

• Panel Persistence: Panels and active sessions survive VS Code restarts

• Multi-Panel Sync: Prompt history syncs across all open panels instantly

• Context Stats: Live tracking of token usage, cache activity, context window %, and session cost — context % is SDK-sourced (accurate per-turn via getContextUsage()). "View Details" button opens the Context Usage Overlay — a full-screen view with SVG ring chart, stacked category bar (SDK-provided colors), per-category breakdown, collapsible message breakdown (user/assistant/tool calls/results/attachments with per-type drilldowns), detail sections for MCP tools, memory files, agents, system prompt sections, system tools, deferred tools, skills, and slash commands, auto-compact threshold badge, and API usage footer. Also accessible via /context

• Session Logs: Quick access button to open the raw JSONL session file (also works for subagent logs)

• Model Selection: Switch between Anthropic models (Opus 4.8, Sonnet 4.6, Haiku 4.5) and OpenAI Codex models (gpt-5.5 — recommended default, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex, gpt-5.2) from one unified dropdown. All Codex models work via ChatGPT subscription or API key. Per-panel selection plus a workspace-wide default for new panels

• OpenAI / GPT Backend: GPT models run through an in-process Anthropic↔Codex translator on a loopback proxy, so the SDK, permission diffs, MCP tools, session persistence, and Compass / Memory / Recall keep working unchanged. Two auth paths: ChatGPT subscription via Codex OAuth (PKCE, tokens in SecretStorage) and OPENAI_API_KEY. Codex wins when both configured; damocles.openai.preferApiKey inverts. Main chat, Team specialists, Team Lead (auto-selected per panel backend), and the Explore subagent can each independently run on GPT. Background sub-calls (memory, recall, /btw) auto-pick Haiku 4.5 on Anthropic and gpt-5.4-mini on OpenAI. Backend-aware cost display (Input | Cached Input | Output | Reasoning) with configurable per-model pricing

• Adaptive Thinking (per-panel): Model-aware thinking configuration driven by SDK-reported capabilities — adaptive models use configurable reasoning effort (Low/Medium/High/Max, plus xhigh and Ultracode for Opus 4.8), legacy models use the classic toggle + token budget (1K-64K). Ultracode combines maximum thinking with the SDK's dynamic workflows (see Workflows above); selectable per-panel or as a default for new panels (listed after Max), and applies only to Anthropic Opus 4.8 (stripped before the OpenAI/Codex bridge). Each panel has independent reasoning state: a thinkingDisabled flag plus a per-(panel, model) matrix of effort and max-tokens, so switching models within a panel preserves prior intent — flip back to a previously-configured model and its effort/tokens restore automatically. Settings panel splits into four sections (This Panel / Defaults for New Panels / Workspace / Voice); the panel and defaults reasoning blocks track different model dimensions independently — switching the active model in the panel section never drags the defaults section's effort capabilities along with it. Workspace defaults persisted via damocles.thinkingDisabled / damocles.effortByModel / damocles.maxThinkingTokens. Thinking blocks always visible (display: 'summarized' overrides Opus 4.8's omitted default)

• Fast Mode: Toggle for faster output using the same model. Bolt icon in the chat input bar with state tracking (off/cooldown/on) from SDK stream events. Currently requires the Bun-compiled CLI native binary — the UI shows a toast explaining the limitation when toggled in Node.js extension context

• Per-Panel Permission Mode: Each panel can have its own permission mode independent of the global default

• YOLO Mode: Toggle to auto-approve all tool calls (except plan approval and questions). Ephemeral setting that resets on session clear.

• Custom Permission Rules: Define persistent allow/deny rules for tools in Claude Code CLI-compatible settings files. Rules support pattern matching (e.g., Bash(git:*), Edit(*.ts)). Permission prompts include "Always allow" and "Always deny" options that save rules to your chosen settings file.

• Subagent-Scoped Accept All: When you click "Accept all edits" on a subagent's permission prompt, only that subagent is auto-approved—the global session mode stays unchanged. Each subagent can be independently auto-approved without affecting the main session or other subagents.

• Plan Mode: When enabled, Claude creates implementation plans for your approval before making changes. Review plans in a modal, approve with auto-accept or manual mode, or request revisions with feedback. Dismissing the overlay (Escape) hides it without canceling — click the tool card to reopen, or press Escape again to reject. View session plan anytime via the header button

• Clear Context & Auto-Accept: Plan approval option that clears conversation context and starts fresh with the plan injected (matches Claude Code CLI behavior). Preserves planning session as reference while implementation runs in a clean session. The overlay header shows a context usage badge with threshold-based colors so you can make an informed decision

• Bind Plan to Session: Inject a custom plan file into the session via the link icon in the header. Claude is notified of the plan file path so it can reference the plan.

• File Checkpointing & Session Forking: Track file changes and rewind to any previous state, or fork the conversation into a new panel without touching the source. Three entry points — the Rewind Browser (/rewind), the inline rewind button on any user message bubble (hover to reveal), or Escape Escape. The Restore Options modal offers three actions: Fork conversation (spawn a new panel branched at the selected message; source untouched), Roll back files (restore files in the current panel with conversation linear), and Fork and roll back files (restore files in source AND spawn a forked panel). Forked panels inherit the source's model, betas, strategy, provider profile, permission mode, and YOLO state, hydrate with the source's history up to the fork point, and pre-fill the rewound prompt. Files modified after the selected message are listed in a collapsible disclosure; clicking a file opens a VS Code side-by-side diff comparing its state at the checkpoint against its current state. Powered by the Claude Agent SDK's forkSession API. Fork variants are disabled in recall mode (recall is stateless)

• Loop Jobs: Schedule recurring prompts with /loop (e.g., /loop 5m check the deploy). The Jobs Overlay shows active/stopped jobs with status badges, interval labels, and per-job cancellation. Accessible via an amber indicator pill in session stats or the clock button in the header

• Side Questions (/btw): Ask ephemeral side questions that share conversation context without interrupting the main session. Token-efficient via prompt caching — only the question and response are new tokens. Responses appear in dismissable inline aside bubbles with markdown rendering, visually distinct from the main conversation. Not persisted to session history

• Task List: Visual display of Claude's current tasks with status tracking, dependencies (blockedBy), and active form indicators

• Message Queue: Send messages while Claude is working - they're injected at the next tool boundary

• Recall Mode: Alternative context strategy that replaces the SDK's built-in session resume. Based on the RLM paper (arXiv 2512.24601v2). Each panel independently chooses default or recall via "This panel" and "Default for new panels" dropdowns in the settings panel.

  The problem: Normally, Claude remembers prior turns because the SDK replays the full conversation history. As conversations grow long, this gets expensive and slow. Worse, a 50-turn session may contain 5 different tasks — when you ask about auth, turns from a previously resolved auth bug pollute the results. Recall mode uses stateless queries (persistSession: false) — Claude has no built-in memory of prior turns. Instead, task nodes scope conversation turns to specific tasks, and the recall system retrieves context only from the active node.

  Task Node System:

  Users manage task nodes via a non-blocking chip in the chat input bar. The recall system retrieves context only from the active node's turns, with optional summary cards from related closed nodes. This eliminates context poisoning at the structural level.

  Component	What it does
  Node Chip	Non-blocking popover in the chat input bar. Shows the active node (emerald), pending new node (indigo), or "select task" (amber pulse). Click to switch between active nodes or create new ones (max 5). When no node is set or pendingNewNode is true, the next prompt auto-creates a new node
  Node Close Prompt	Inline banner after each response. User selects outcome (Resolved/Partial/Abandoned) via color-coded buttons, then Haiku generates summary fields (title, description, files, decisions, entities)
  Session Node Overlay	Dedicated full-screen overlay (top toolbar Layers button). Two-column graph view — closed nodes left, active nodes right — with canvas-drawn bezier edges connecting related nodes. TaskNodeCard components show title, status, entities, turn count, outcome, and default badge. Seed context regeneration with custom extraction instructions via inline editor. Recall Attempts section shows per-node REPL history with orientation data
  Node Context Tab	Per-message "Node Context" tab in the Context Injection Overlay. Shows injected turns as conversation cards (Cards view) or raw text (Raw view) with a toggle
  Cross-Node /btw	/btw as prompt prefix searches across all nodes for ephemeral cross-cutting questions

  Two roles across two models:

  	Root Model (Sonnet)	Sub Model (Haiku)
  Role	REPL orchestrator — writes JavaScript to search node-scoped history (fallback only)	Title generation, summary generation, turn indexing, query expansion, chunk investigation, extraction/summarization worker
  When it runs	Only when node context exceeds 400K chars (max 8 iterations with orientation, 15 without)	Node creation (~1s), node closing (~1s), turn indexing (async, per-turn), orientation investigation (pre-REPL), seed regeneration, sub-calls during REPL
  Cost	Medium (rare)	Cheap

  How context retrieval works:

  User submits prompt
       │
  ┌────▼──────────────────────────────────────────────┐
  │  NODE RESOLUTION                                  │
  │  pendingNewNode? → auto-create node               │
  │  activeNodeId set? → use it                       │
  │  no nodes? → auto-create first node               │
  └────┬──────────────────────────────────────────────┘
       │
  ┌────▼──────────────────────────────────────────────┐
  │  buildNodeContext()                               │
  │                                                   │
  │  1. Get active node's turns (full detail)         │
  │  2. Append related closed nodes' summary cards    │
  │  3. IF total chars ≤ 400K → return directly       │
  │     (zero LLM calls — the common path)            │
  │  4. IF total chars > 400K → two-stage retrieval:  │
  │                                                   │
  │   STAGE 1: Auto-Orientation (no root model)       │
  │   ┌──────────────────────────────────────┐        │
  │   │ expandQuery() → Haiku synonyms       │        │
  │   │ BM25 index → rank all turns          │        │
  │   │ IF top score < 2.0 (vague query):    │        │
  │   │   chunk investigation → Haiku        │        │
  │   └──────────────┬───────────────────────┘        │
  │                  ▼                                │
  │   STAGE 2: Oriented REPL (max 8 iterations)       │
  │     Root Model (Sonnet)    JsRepl Sandbox          │
  │     ┌──────────────┐     ┌──────────────┐          │
  │     │ Sees ranked  │─c─▶ │ turn_index   │          │
  │     │ results +    │◀─o──│ text_search() │          │
  │     │ orientation  │     │ context[]    │          │
  │     ├──────────────┤     │ llm_query    │          │
  │     │ FINAL_VAR()  │─r─▶ │ _batched()   │──▶ Haiku │
  │     └──────────────┘     └──────────────┘          │
  └───────────┬───────────────────────────────────────┘
              ▼
   Context injected as <recall_session_context>
              │
  ┌───────────▼───────────┐
  │  MAIN MODEL           │
  │  Sees node-scoped     │
  │  context + prompt     │
  │  Responds normally    │
  └───────────────────────┘
  

  The common path (node with <400K chars) returns context directly with zero LLM calls. The REPL loop is a rare fallback for large nodes. When it fires, it first runs an auto-orientation pipeline (query expansion via Haiku, BM25 ranking across all turns, and optional chunk investigation for vague queries) — all before the root model starts. The root model then enters the sandbox pre-oriented with ranked results, a turn_index array, and a text_search() BM25 function, needing only ~8 iterations instead of 15. Each turn is also indexed at write-time by Haiku (turn-indexer.ts), generating a one-line summary and domain-specific keywords that persist as turn-index JSONL entries and enrich BM25 scoring on reload. The loop enforces a 120-second total timeout. If max iterations are exhausted without a FINAL() call, a forced-answer prompt extracts whatever was gathered; if that also fails, the last 3 turns are used as fallback.

  Implementation details

  Turn persistence: Each turn is persisted client-side to per-node JSONL files at <sessionId>/nodes/<nodeId>.jsonl, with lightweight node-turn-ref entries in the main session JSONL for branch tracking. Each StructuredTurn has a nodeId field joining it to its task node (null for orphan turns predating the node system). A fresh stateless SDK query is created per prompt with a rotating sessionId, while a stable persistenceSessionId is used for the JSONL filename, checkpoints, and webview display.

  Node lifecycle: NodeManager handles create (Haiku generates title + entities), close (Haiku generates NodeSummary with outcome/files/decisions), reopen, and entity accumulation (two-tier: Haiku-seeded on creation, deterministic extraction on subsequent turns). Cross-node entity overlap (≥40% with min() denominator) links related closed nodes for summary card injection. Node state persists to JSONL via event entries and full node-state checkpoints.

  Recall trigger: The UserPromptSubmit hook fires before the query reaches the API. On the first prompt, no recall is needed. From the 2nd prompt onward, ClaudeSession.sendMessage() resolves the active node synchronously — auto-creating when pendingNewNode is set or no nodes exist. RecallService.getContextForInjection() calls buildNodeContext() which gets the active node's turns, formats them with buildDirectContext(), appends related closed node summaries, and returns directly if under maxInjectedChars. Only if the node's context exceeds the limit does the two-stage retrieval fire — auto-orientation (query expansion + BM25 + optional investigation) followed by oriented REPL loop — scoped to that node's turns only.

  Turn indexing: After each turn completes, indexTurnAsync() sends a compressed version to Haiku which returns { summary, keywords }. Persisted as turn-index JSONL entries via TurnPersistence.persistTurnIndexQueued(). On session reload, applyTurnIndices() in history-builder.ts patches these back onto turns. BM25 uses keywords for enriched scoring; the turn_index sandbox variable provides compact metadata for the REPL model.

  Stateless execution: The SDK query runs against the API with no prior conversation state. As Claude responds, turn data is accumulated via onStreamDelta, onToolUse/onToolResult, and onThinkingBlockComplete. Subagent tool calls are routed to separate agent-{id}.jsonl files with parentToolUseId guards preventing leaks into the main JSONL. On response completion, the full structured turn (with nodeId) is persisted and added to in-memory history.

  Context injection viewer: Each user message shows a pill that opens the Context Injection Overlay — a full-screen tabbed UI (Recall | Memory | Node Context) with push-based live streaming. Always shows technical view. The Recall tab shows two-stage orientation data (expanded terms, BM25 results, investigation report) followed by REPL iterations, with live phase streaming during execution. The Memory tab shows catalog entries per tier with score breakdowns, pinned memories, FTS query terms, and retrieval boost indicators. The Node Context tab shows the actual turns injected for that prompt — as structured conversation cards (default) or raw text — with a Cards/Raw toggle. Separately, the Session Node Overlay (Layers button in toolbar) provides a dedicated full-screen view of all session nodes with drill-down to full conversation history and per-node recall attempt history.

  Internal flow:

  User sends message
  │
  ├─ IF /btw prefix → cross-node search (all turns, ephemeral)
  ├─ IF pendingNewNode or no nodes → auto-create node
  │
  ├─ RecallService.onPromptSubmit(prompt, nodeId) — persist to JSONL
  ├─ QueryManager creates stateless query (persistSession: false)
  │
  ├─ UserPromptSubmit hook fires:
  │   ├─ getRecallContext(userPrompt) called
  │   │
  │   ├─ IF promptIndex === 0: return null (no history)
  │   ├─ IF activeNodeId exists:
  │   │   └─ buildNodeContext():
  │   │       ├─ Get active node's turns
  │   │       ├─ Append related closed node summary cards
  │   │       ├─ IF ≤ maxInjectedChars → return directly (common path)
  │   │       └─ IF > maxInjectedChars → runRecallLoop() within node scope
  │   ├─ ELSE (no nodes): buildFlatContext() with full history
  │   │
  │   └─ Inject context as <recall_session_context>
  │
  ├─ Main SDK query proceeds normally (tools, permissions, streaming)
  │
  ├─ As response streams: accumulate turn data
  ├─ onResponseComplete: persist turn to JSONL, show NodeClosePrompt
  └─ Next turn: updated history available
  

• Auto-Compact: Optional automatic context compaction via configurable thresholds (damocles.autoCompact; opt-in, disabled by default). Visual warnings at warningThreshold/softThreshold, auto-triggers /compact at hardThreshold to prevent context overflow. Applies uniformly to every backend — GPT sessions compact only when you enable it, same as Anthropic

• Persistent Memory: Every memory has a kind (fact, preference, observation, note, episode) and a scope (session, project, global), stored in WASM-based SQLite (~/.damocles/memory.v2.db). No native modules — works cross-platform without compilation. Memories survive compactions and sessions, giving Claude continuity across conversations. Uses a pull-first catalog model: each prompt receives a compact relevance-ranked catalog (~300-800 tokens) of available memories, and Claude retrieves full details on demand via get_memory_details. This matches how CLAUDE.md works — a reference Claude consults selectively — and eliminates token displacement from irrelevant auto-injection

• Automatic Memory Extraction: After a conversation goes idle (or on session switch), a background pass extracts durable facts, preferences, and episodes from the turns — deduping exact and near-duplicate content, resolving contradictions, and decaying time-bound episodes (~30-day TTL, promoted when reused) — so memory accrues without manual /remember. Runs on a cheap model; crash-safe (a batch is never lost mid-extraction). Gated by damocles.memory.autoExtract.enabled

• Fact Graph & Versioning: Facts evolve through UPDATES / EXTENDS / DERIVES / SUPERSEDES edges. When a fact is updated the old version is retained (not deleted) and browsable via get_memory_history; get_related_memories traverses the graph. forget_memory drops a memory by id or content — by default forgetting the entire version chain so an older version cannot resurface

• User Profile: A short auto-maintained summary of you — a static section plus a recent-activity dynamic section, per project and global scope — regenerated during consolidation and injected once at the start of each session. Edit it inline in the Memory Panel; budget via damocles.memory.profile.tokenBudget

• Pinned Memories: User-designated memories that are always injected in full content, bypassing the catalog. Pin/unpin via the overlay UI. Configurable budget (default 500 tokens)

• Retrieval Tracking: When Claude calls get_memory_details, retrievals are recorded and fed back into catalog ranking. Memories Claude actively uses rank higher in future catalogs — a closed feedback loop

• Observation Staleness: When source files referenced by an observation are modified, the observation is automatically marked stale. Claude sees [stale] tags in context and can verify whether the observation is still accurate, then mark it fresh via the reset_observation_staleness MCP tool

• Memory Commands: /remember <text> saves session memory (prefix project: or global: for broader scope), /note <text> saves to a searchable knowledge base, /memories opens the management panel

• Observations: Claude voluntarily records rich observations via MCP tool after significant work — structured entries with type, title, narrative, facts, tags, and file paths. Zero additional API cost

• Memory MCP Tools: 10 in-process tools for Claude: save_memory, save_observation, search_memories (semantically reranked), get_memory_details, get_memory_history, get_related_memories, forget_memory, save_note, list_notes, reset_observation_staleness. Progressive disclosure keeps token usage efficient

• Smart Session Handoff: New sessions automatically receive the previous session's summary and top-ranked observations from recent sessions, weighted by file proximity to the active editor

• Memory Panel: Full-screen overlay for browsing, creating, deleting, pinning/unpinning, forgetting, and searching memories — with kind/scope filter chips, a forgotten toggle, version-history and related-memories dialogs, and an inline editor for the auto-maintained user profile. Pinned memories show an amber left-border accent

• Consolidation Panel: A header pill beside the prompt navigator opens a view of the conversation turns queued for the next extraction pass plus the last pass's extracted memories (with outcome badges), and a Run now button to trigger consolidation manually

• Injected-Context Viewer: Each user message has a "View context" pill that opens an overlay showing exactly what was provided to Claude for that prompt — a Memory tab lists the injected memories with per-entry relevance scores and the FTS query used, so you can see why each memory surfaced

• Collaborative Teams: Multi-agent team system where 2-5 specialist agents collaborate in real-time on complex tasks. A lead agent orchestrates — spawning specialists with domain expertise profiles, coordinating via direct messaging, sharing decisions on a scratchpad, and synthesizing a final result. 161 bundled agent profiles across 13 categories (Engineering, Design, Game Development, etc.) give specialists genuine domain knowledge. TeamCard in chat shows live status; TeamOverlay provides full details (Agents, Timeline, Scratchpad, Result tabs). All agent communication persisted to JSONL. Each Damocles panel owns its own team runner, so multiple panels can run independent teams concurrently without cross-interference. Disabled by default; enable via damocles.team.enabled

• Compass — Workspace Knowledge Graph: Converts your workspace into a persistent, queryable knowledge graph via tree-sitter AST extraction across 15 languages (Python, JS/TS/TSX, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Vue SFC). Backed by SQLite (sql.js-fts5) — the graph survives VS Code restarts with zero re-indexing. Claude queries the graph via 8 MCP tools: core (compass_search, compass_query, compass_context, compass_stats), impact (compass_blast_radius, compass_review_context), analysis (compass_dead_code), and admin (compass_build). compass_review_context auto-detects changed files via git when no file list is provided. Every compass_query response states what the target resolved to (name, kind, path:line), lists alternate matches on ambiguity, and flags empty relationship results for verification — so a "none" is diagnosable rather than silently wrong. Key capabilities: FTS5 BM25 search with camelCase/snake_case tokenization (plus parent-class and directory tokens, so a query naming a class surfaces its methods), blast radius analysis (BFS from changed files through all edge kinds, bounded non-lossily on hub nodes), risk-scored review context (flow-criticality-weighted impact + test gaps + affected flows, with a context-savings estimate), test-coverage edges (tests_for / test-gap risk, derived from tests that call production code — recognizing Rust #[test], PHPUnit camelCase, and @Test/[Fact]-family annotations, with a class-name fallback for DI-heavy tests), dead-code detection (unreferenced functions/classes, excluding entry points and framework-managed classes; constructor/static calls and type-hint/DI-injected dependencies are now tracked across all languages, so constructor-injected services aren't false-flagged), execution flow tracing with criticality scoring (framework decorators and entry-name conventions across 15+ stacks; test files excluded from production flows), and Louvain community detection (adaptive resolution scales inversely with graph size; directory-based fallback above 20K nodes). Interactive D3 force-directed graph visualization in the webview with community coloring, blast radius overlay, and click-to-navigate. VS Code sidebar tree view, search panel, validation panel (broken edges, orphans, stale files), editor gutter decorations for blast radius, and status bar. Incremental updates are watcher-fed — newly created files are indexed within seconds without a rebuild (large bursts like branch switches fall back to one git diff) — with SHA-256 caching, transitive dependent invalidation, and disk writes only when the graph actually changed. Resilient by design: a corrupt graph cache self-heals on startup, and repeated worker crashes trip a circuit breaker ("Compass failed — run Rebuild to retry") instead of looping. Works correctly on Windows (drive-letter casing, /-style excludePatterns) and in monorepos where the workspace is a subfolder of the git repo. All tools support detail_level (minimal/summary/full) for token efficiency. Disabled by default; enable via damocles.compass.enabled

• Damocles Browser: Integrated browser with full CDP automation — launches a headless Chromium inside a VS Code editor panel with toolbar (back, forward, reload, URL bar, element picker, DevTools). Claude gets 15 MCP tools (browser_open, browser_navigate, browser_click, browser_type, browser_screenshot, browser_query, etc.) for full page interaction. Element picker lets users select elements and attach DOM/CSS/screenshot context to chat messages. Multi-page session tracking via CDP Target.setAutoAttach for popup-spawned pages — they attach, take focus on spawn, and the screencast restores to the parent page when the popup closes; background-spawned pages stay attached but don't steal the panel. Zero external dependencies — CDP commands route through a raw WebSocket. Disabled by default; enable from the MCP status panel toggle or via damocles.browser.enabled. Known limitation: popup-based "Sign in with Google" / Apple / Microsoft (window.open() flows including Google Identity Services) does not complete inside the panel — Chromium's --headless=new flag does not allocate paint surfaces to popup windows (Chromium 696439), so the popup attaches but never renders and there's nothing for the user to click. Same-window OAuth that redirects the parent page (e.g., Wizards SSO) is unaffected. For popup-based providers, sign in via your normal browser before bringing the URL into the panel.

• Chrome Browser Integration: Built-in MCP server for Chrome browser automation — take screenshots, execute JavaScript, click elements, navigate pages, and more. Disabled by default; enable from the MCP status panel toggle or via damocles.chrome.enabled. Requires the Claude Code Chrome Extension installed in Chrome. The server appears as a toggleable entry in the MCP status panel alongside external MCP servers

• MCP Elicitation: MCP servers can request user input during tool execution — form mode renders JSON Schema-driven fields for structured input, URL mode opens an external browser for OAuth flows. Prompts appear above the chat input with Accept/Decline actions

• MCP Server Management: Enable/disable MCP servers from the UI with settings persisted to Claude config. Status panel shows per-server tool counts with expandable details and annotation badges (read-only, destructive, network), error messages for failed servers, and reconnect/authenticate actions

• Hooks Support: Claude Code hooks (shell commands that run on events like tool calls) work automatically

• Plugins Support: Enable/disable Claude Code plugins from the UI - plugins can provide agents and slash commands

• Skills Support: Approve or deny skill invocations. Includes the SDK-bundled /batch skill for decomposing large changes into parallel background agents in isolated git worktrees

• Provider Profiles: Define and switch between API providers (Anthropic, Z.AI, OpenRouter, etc.) with per-panel profile selection

• Remote Control (REPL Bridge): Toggle the SDK's WebSocket-based remote session control from the chat header. Enables external tools and scripts to connect to the running Claude session via REPL. The globe icon opens a popover with an on/off switch, connection status, and per-URL copy buttons for the session and connect endpoints. State persists across query recreations (model change, MCP restart)

• Localization: UI translated into multiple languages, automatically matches VS Code's display language

1. Clone the repository
2. Run npm install
3. Run npm run build
4. Press F5 in VS Code to launch the Extension Development Host

• Open the Damocles sidebar view in the secondary sidebar (right side), or click the Damocles icon in the editor title bar (top right) to open a panel
• Type your question or request in the chat input
• Press Enter to send (Shift+Enter for new line)
• Review any file changes in the diff view before approving

• Ctrl+Shift+U / Cmd+Shift+U: Focus the chat panel
• Ctrl+K / Cmd+K: Toggle the Prompt Navigator overlay
• ↑ / ↓: Navigate through prompt history (like terminal shell)
• Shift+Tab: Cycle through permission modes
• Escape: Cancel current request (when processing)
• Escape Escape: Open rewind popup to restore previous state

The input bar shows a context indicator that tracks your active editor:

• Eye icon + line count: When you have code selected, shows "N lines"
• Code icon + filename: When a file is open without selection, shows the filename

Click the indicator to toggle whether the context is included in your next message. When enabled, the selected code (or entire file) is automatically injected into your prompt—no need to manually @mention or paste code.

Paste images directly into the chat input with Ctrl+V / Cmd+V:

• Supported formats: PNG, JPEG, GIF, WebP
• Size limit: 5MB per image
• Max attachments: 10 images per message

Attached images appear as compact chips (icon + filename + WIDTH×HEIGHT) below the input. Hover over a chip to reveal the remove button. Click any image in the conversation to open it in a lightbox.

• @: Trigger autocomplete popup for files and agents
• ↑ / ↓: Navigate suggestions
• Tab / Enter: Insert selected item
• Escape: Close popup

Mention types:

Custom agents are loaded from .claude/agents/*.md (project) and ~/.claude/agents/*.md (user). Project agents override user agents with the same name. Plugin agents are loaded from enabled plugins' agents/ directories.

• /: Trigger command autocomplete popup
• ↑ / ↓: Navigate suggestions
• Tab / Enter: Insert selected command
• Escape: Close popup

Built-in commands:

Custom commands are loaded from .claude/commands/*.md (project) and ~/.claude/commands/*.md (user). Plugin commands use the format /<plugin>:<command> (e.g., /myplugin:build).

Skills are specialized tools that extend Claude's capabilities. You can invoke skills in two ways:

Via slash command (recommended):

• Type /skill-name to invoke a skill directly - it appears in the autocomplete popup alongside regular commands
• Skills invoked this way are auto-approved (no approval prompt)
• Pass arguments after the skill name: /skill-name additional context here

Via Claude's autonomous invocation:

When Claude decides to use a skill on its own, you'll see an approval prompt:

• Yes: Approve this invocation (manual mode)
• Yes, don't ask again: Auto-approve this skill for the session
• No: Deny the skill
• Tell Claude what to do instead: Provide custom feedback

Skills are loaded from .claude/skills/<name>/SKILL.md (project) and ~/.claude/skills/<name>/SKILL.md (user). Plugin skills use the format /plugin:skill-name. The skill description is parsed from the YAML frontmatter.

Define persistent allow/deny rules for tools in Claude Code CLI-compatible settings files. Rules are evaluated before each tool call and can automatically allow, deny, or prompt for specific patterns.

Settings file priority (first match wins):

Example settings file:

{
  "permissions": {
    "allow": ["Bash(git:*)", "Bash(npm run *)", "PowerShell(Get-ChildItem:*)"],
    "deny": ["Bash(rm:*)", "Bash(sudo:*)", "PowerShell(Remove-Item:*)"],
    "ask": ["Bash(npm publish:*)"]
  }
}

Bash and PowerShell rules are evaluated independently — a Bash(git:*) rule does not auto-allow a PowerShell git status call. Cross-shell isolation is intentional: PowerShell flag semantics and sandboxing differ from Bash on Windows, so users who want both must write both rules explicitly.

Pattern syntax:

Quick rule creation:

When a permission prompt appears, you can click "Always allow {pattern}" or "Always deny {pattern}" to create a persistent rule. A destination picker lets you choose which settings file to save the rule to (local, project, or global).

Damocles gives Claude persistent memory that survives across compactions and sessions. Memories are stored locally in WASM-based SQLite (~/.damocles/memory.v2.db) — no native modules, works on every platform without compilation.

Kinds and scopes:

Every memory carries a kind and a scope:

Facts, preferences, and episodes are created automatically by extraction; you can also create them explicitly with /remember (project: / global: prefixes set scope) or have Claude call save_memory. Notes are created with /note and retrieved on demand. Observations are recorded by Claude via save_observation; the most recent surface in context. Episodes decay on a ~30-day TTL unless reused (then promoted to durable). Pinned memories of any kind are always injected in full.

How the catalog works:

Every prompt you send receives a relevance-ranked catalog of available memories. The catalog builder:

1. Runs FTS5 full-text search against your prompt to find relevant memories
2. Scores each memory using a composite signal:
   • Prompt relevance (50%): BM25 text similarity (FTS5 with porter stemming)
   • Recency (15%): How recently was the memory created/updated?
   • Scope priority (15%): Session > Project > Global
   • File proximity (10%): Does the memory mention the file you have open?
   • Retrieval boost (10%): How often has Claude actively retrieved this memory?
3. Takes the top N entries per scope/kind (entry-count limits, not token budgets); notes are excluded (browse-on-demand)
4. Formats as a compact catalog: short text for session/project/global (truncated entries include ID for retrieval), title + ID for observations
5. Injects pinned memories as full content, plus the auto-maintained user profile on the first message

search_memories reranks its BM25 hits with a cheap LLM (ungraded hits keep their BM25 standing); the per-turn injected catalog can optionally be reranked too under a hard ~2 s cap (damocles.memory.rerank.injectMode).

When the prompt doesn't match any memories, scoring falls back to a recency-dominant heuristic. Claude browses the catalog and calls get_memory_details to retrieve full content for observations that look relevant to the current task.

Example — catalog output:

<damocles_memory>
<project_memories>
- JWT tokens expire after 1 hour. Refresh logic lives in auth-service.ts
- Database uses Knex with PostgreSQL. Migrations in db/migrations/
</project_memories>
<recent_observations>
- [obs-auth-uuid] Fixed authentication token refresh race condition (src/auth-service.ts)
- [obs-deploy-uuid] Deployment pipeline fix for staging environment
</recent_observations>
<pinned_memories>
- [mem-arch-uuid] Architecture: always use repository pattern for data access
  Full content of the pinned memory here...
</pinned_memories>
</damocles_memory>

Claude sees the catalog (~300-800 tokens) and decides what to retrieve. For complex problems, Claude naturally retrieves less. For context-heavy tasks, Claude pulls exactly what it needs.

Smart session handoff:

When you start a new session in the same workspace, the first message automatically includes:

• Top-ranked observations from recent sessions, scored by prompt relevance, file proximity, and recency

MCP tools for Claude:

Claude has 10 memory tools it can use autonomously:

• save_memory — Save a typed memory with an explicit kind and scope (fact / preference / episode)
• save_observation — Record structured observations after significant work
• search_memories — Full-text search (semantically reranked) returning a compact index (~30 tokens/result)
• get_memory_details — Fetch full content for specific memory IDs (also records retrievals for feedback)
• get_memory_history — Inspect the version chain of a fact (root → latest)
• get_related_memories — Traverse the fact graph over updates/extends/derives/supersedes edges
• forget_memory — Forget a memory by id or content (default forgets the whole version chain)
• save_note / list_notes — Knowledge base management
• reset_observation_staleness — Mark an observation as fresh after verifying its content

Memory panel:

Type /memories to open the management panel where you can browse, create, delete, pin, forget, and search memories — with kind/scope filter chips, a forgotten toggle, version-history and related-memories views, and an inline editor for the user profile.

Plugins extend Claude's capabilities with additional agents and slash commands. Installed plugins are discovered from:

• Registry: ~/.claude/plugins/installed_plugins.json (managed by Claude Code CLI)
• Manual: <project>/.claude/plugins/*/ directories with .claude-plugin/plugin.json

Enable or disable plugins from the plugin status panel in the UI. Plugin settings are persisted to Claude's settings files.

Plugin-provided features:

Provider profiles allow you to define and switch between different API providers (Anthropic, Z.AI, OpenRouter, etc.) directly from the settings panel. Each profile stores environment variables that configure the SDK's connection.

Security: API credentials are encrypted using VS Code's SecretStorage API (backed by the OS keychain) and never stored in settings.json. Profile names are visible in settings, but all environment variables containing API keys are stored securely.

Creating a profile:

1. Open the settings panel (gear icon in chat header)
2. Scroll to "Provider Profiles" section
3. Click "Add Profile"
4. Enter a profile name and add environment variables

Common environment variables:

Example: Z.AI Profile

Name: zai
ANTHROPIC_BASE_URL: https://api.zai.com/v1
ANTHROPIC_AUTH_TOKEN: your-zai-api-key
ANTHROPIC_DEFAULT_SONNET_MODEL: claude-sonnet-4-20250514

Per-panel profiles:

Each open panel can have its own provider profile independent of other panels. The settings panel shows two profile selectors:

• This panel: The provider profile for the current panel only
• Default for new panels: The global default that new panels inherit when opened

This allows you to have multiple panels open simultaneously, each connected to a different provider (e.g., one panel using OpenRouter while another uses Z.AI).

When you activate a profile, the session automatically restarts with the new provider configuration. Set to "Default" to use the Anthropic API with your ANTHROPIC_API_KEY environment variable.

Per-panel models:

Each open panel can also have its own model independent of other panels. The settings panel shows two model selectors:

• This panel: The model for the current panel's session (applies immediately)
• Default for new panels: The global default that new panels inherit when opened

Changing the default does not affect any existing panel's session — only new panels pick up the new default.

The extension automatically uses VS Code's display language. Currently supported:

To change the language, set VS Code's display language via Configure Display Language command (Ctrl+Shift+P → "Configure Display Language").

• VS Code 1.95.0 or higher
• A Claude subscription (Pro, Max, Team, Enterprise) or an ANTHROPIC_API_KEY or a supported cloud provider — see Authentication below
• Supported platforms: Windows (x64, arm64), macOS (Apple Silicon), Linux (glibc and musl, x64 and arm64). Intel Macs are not supported — the bundled Claude Code runtime ships as a per-architecture native binary and Intel-Mac (darwin-x64) builds were dropped in v1.8.10 to streamline the release pipeline

Damocles uses the Claude Agent SDK and ships the Claude Code runtime as a bundled native binary — no separate npm install -g step is required. Authentication is handled end-to-end inside the installed extension.

┌─────────────────────────────────────────────────────────┐
│  Damocles Extension (VS Code)                           │
│         │                                               │
│         ▼                                               │
│  @anthropic-ai/claude-agent-sdk                         │
│         │                                               │
│         ▼ (spawns bundled binary per platform)          │
│  Claude Code runtime (shipped inside the VSIX)          │
│         │                                               │
│         ▼ (handles authentication)                      │
│  Anthropic API                                          │
└─────────────────────────────────────────────────────────┘

• The SDK resolves a per-platform sidecar package (@anthropic-ai/claude-agent-sdk-{platform}-{arch}) that carries the claude / claude.exe binary inside the VSIX.
• The binary owns OAuth session management, API-key loading, and cloud-provider credential discovery.
• Damocles maintains its own OAuth grant, fully isolated from the standalone Claude Code CLI. Damocles credentials live at ~/.damocles/auth/.credentials.json; the CLI's ~/.claude/.credentials.json is never read, written, or deleted by Damocles. Signing in or out in either tool only affects that tool's authorization on Anthropic's server. Existing Claude Code CLI users must run Damocles: Sign In to Claude once to mint a Damocles-specific OAuth grant — sharing one credentials file across both tools would still share one server-side grant, so a separate sign-in is required for true isolation.
• Settings, plugins, skills, agents, slash commands, session history (~/.claude/projects/), and plans are still shared with the CLI: at activation Damocles dynamically mirrors every top-level entry of ~/.claude/ (except .credentials.json) into ~/.damocles/auth/ via OS-level junctions (Windows) / symlinks (macOS, Linux) for directories and atomic copy-plus-watch for files. Adding a plugin via claude plugin add propagates without restarting Damocles.

The bundled runtime provides everything the SDK needs to talk to Claude:

• Built-in tools — Bash, Read, Write, Edit, Grep, Glob, etc.
• Authentication — OAuth session management, API keys, cloud provider credentials
• Session persistence — Conversation history stored in ~/.claude/projects/
• Sandboxing — OS-level process isolation for safe command execution
• Permissions — Tool approval workflows and permission modes

Damocles calls the SDK; the SDK spawns the bundled binary, which handles everything above.

Option 1: Claude Subscription (Recommended)

If you have a Claude Pro, Max, Team, or Enterprise subscription, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Damocles: Sign In to Claude. A VS Code integrated terminal opens the bundled binary's OAuth flow — no global install and no separate terminal session required. The extension detects the completed login and refreshes the active session automatically.

Damocles requires its own sign-in even if you already have Claude Code installed globally. The two tools each maintain a separate OAuth grant on Anthropic's server (under ~/.damocles/auth/.credentials.json for Damocles and ~/.claude/.credentials.json for the CLI), so signing in or out of one tool never affects the other.

To clear the Damocles session (for example when handing off the machine or switching accounts), run Damocles: Sign Out from Claude from the Command Palette. Sign-out requires a confirmation prompt, revokes only the Damocles OAuth grant, and clears only ~/.damocles/auth/.credentials.json — the CLI's credentials are left untouched.

Option 2: API Key

export ANTHROPIC_API_KEY=your-api-key

Get your API key from the Anthropic Console.

Option 3: Cloud Providers

For enterprise environments using cloud-hosted Claude:

Once authenticated, the extension displays your account info (email, subscription type) in the chat panel header. If session startup fails because credentials are missing or expired, the chat panel surfaces a dismissable banner with a Sign In shortcut that runs the command above.

# Install dependencies
npm install

# Build extension and webview
npm run build

# Watch mode for development
npm run dev

# Type check
npm run typecheck

# Run tests
npm test

To create a distributable .vsix file:

npm run build && npm run package

This generates damocles-<version>.vsix which can be installed via:

• VS Code UI: Extensions → ... menu → "Install from VSIX..."
• Command line: code --install-extension damocles-<version>.vsix

• Extension Host (Node.js): Handles Claude Agent SDK integration
• Webview (Vue 3 + Tailwind): Chat interface
• postMessage Bridge: Communication between extension and webview