Damocles

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

Screenshots

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

Features

• Chat Interface: Integrated chat panel for conversing with the model — 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 the agent is using in real-time with expandable details. Each completed tool card shows a subtle duration badge (123ms / 1.2s / 1m 23s)
• 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, CodeSearch, 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 Agent tool calls showing agent type, model, tool calls, results, and real-time progress summaries. Click the agent type or template badge to open its .md template. 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- Streaming Responses: Watch responses as they're generated
• @ Mentions: Type @ to reference workspace files or agents (@agent-Explore, etc.) with fuzzy search autocomplete
• Custom Agents: Define custom agents in .pi/agents/*.md or .claude/agents/*.md (project) and ~/.claude/agents/*.md (user). They run as native nested agents via the Agent / GetSubagentResult / SteerSubagent tools, alongside the built-in general-purpose / Explore / Plan agents; a run_in_background: true frontmatter default makes a template always spawn in the background
• 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); a workspace default (damocles.ideContext.enabled) controls whether the chip starts on in new panels - Slash Commands: Type / for built-in commands (/clear, /compact, /rewind, /btw, etc.) and custom commands from .claude/commands/ and .codex/prompts/ - 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. Each row shows index, time, tools invoked during the response, and a kebab menu with Copy / Use as draft / Rewind to here. Type to fuzzy-match prompt text or tool names; 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. Names/tags persist as in-tree session markers; tags show 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 % reflects the current turn's occupancy (the latest assistant message's input + cache). "View Details" button opens the Context Usage Overlay — a full-screen view with SVG ring chart, stacked category bar, 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 5, Haiku 4.5), OpenAI Codex models (gpt-5.5 — recommended default, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex, gpt-5.2), and custom-provider models (StepFun Step 3.7 Flash, DeepSeek V4 Pro / V4 Flash) 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 natively alongside Anthropic models — two pi-owned auth paths (credentials in its Damocles-owned auth.json): ChatGPT/Codex OAuth and OPENAI_API_KEY. Codex wins when both are set; damocles.openai.preferApiKey inverts it. Per-panel selection with a workspace default; backend-aware cost display (Input | Cached Input | Output | Reasoning) with configurable per-model pricing - StepFun / DeepSeek Backends: StepFun (Step 3.7 Flash, step-plan flat-fee subscription) and DeepSeek (V4 Pro / V4 Flash, per-token metered) run natively as main-dropdown models. Each has a dedicated API-key panel in Settings; keys live in SecretStorage and reach pi via the native custom-provider path (no reload). Selecting an unauthed model emits a "Sign in to {provider}" toast. The StepFun key is shared with the Explore StepFun provider — one source of truth, kept in sync across both UIs. DeepSeek is dollar-budget-enforced like other metered providers; StepFun's flat subscription is exempt - Adaptive Thinking (per-panel): Model-aware thinking configuration driven by model-reported capabilities — adaptive models use configurable reasoning effort (Low/Medium/High/Max, plus xhigh and Ultracode for the flagship Anthropic models (Opus 4.8 and Sonnet 5)), legacy models use the classic toggle + token budget (1K-64K). Ultracode is the top reasoning-effort level (maximum thinking); selectable per-panel or as a default for new panels (listed after Max), and applies to the flagship Anthropic models Opus 4.8 and Sonnet 5 (not applied to OpenAI/Codex models). 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) - 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 per-panel setting that resets on session clear; a workspace default (damocles.dangerouslySkipPermissions) seeds it for new panels. - 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. - Hooks: Run your own command at key moments — before/after a tool, on prompt submit, on completion, or when the agent is waiting for approval — via a config-driven .damocles/hooks.json. The contract is Damocles' own: the child gets one JSON object on stdin (snake_case keys, a uniform tool schema) and replies with one JSON object on stdout ({"decision":"deny"} to block — a non-zero exit never blocks). A tool_call hook can block, force-allow, or rewrite a tool call; activation is by presence (no toggle), gated by workspace trust, and every block/force-allow is logged and surfaced in chat. Full guide: docs/hooks.md. - 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, the agent creates implementation plans for your approval before making changes. Plans are decomposed into vertical slices — each cutting end-to-end through every layer to deliver one small, independently testable behavior — rather than horizontal layers. 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. While planning, the agent writes and continuously maintains its plan as markdown at a deterministic per-session path (~/.damocles/plans/<slug>-<id8>.md) — the only native write permitted in plan mode (Bash/PowerShell and every other Edit/Write stay blocked). Enabled MCP tools remain fully available while planning, so the agent can still look things up (e.g. Context7 docs) — the per-server enable/disable toggle is the control. That file is the single source of truth: the approval overlay, the saved plan, and the implementation handoff all read the full plan from it (approval is blocked until the plan file is written), and the completed plan card's View plan button opens it. View the session plan anytime via the header button. Plan mode also deterministically funnels every turn through ExitPlanMode: if the agent stops w