docs(specs): add idea for Claude CLI IDE bridge#368
Open
Luis85 wants to merge 2 commits into
Open
Conversation
Stage-1 spec entry layering the reverse-engineered Claude Code IDE integration protocol (WebSocket MCP server discovered via ~/.claude/ide/<port>.lock) onto the IDEA-TSP-001 terminal sidepanel, giving the embedded interactive session the same ambient vault awareness the VS Code and JetBrains plugins provide. https://claude.ai/code/session_01TR8tn5a6d5utftgtGz4nij
Incorporates PM, architecture, and security review findings plus three
deep-research passes on the IDE protocol, Obsidian APIs, and WebSocket
library choice.
Substantive changes to idea.md:
- Tighten problem statement; demote solution detail (env var names,
file modes, debounce values, HTTP status codes) into research
questions and constraints.
- Add the non-technical persona explicitly as a non-goal user, with
rationale (desktop + CLI-installed only).
- Rewrite success criteria as observable behaviour ("Claude responds
correctly to questions that depend on knowing which note is active")
rather than implementation values.
- Resolve the in-scope / out-of-scope contradiction around stubbed
tools (stubs are in scope; real integration is out).
- Split the proposed port surface per ADR-008: server lifecycle is
one narrow port; diff confirmation modal is a second narrow port
mirroring ConfirmModalPort; tool dispatch is application-layer
(one use case per protocol verb), not a domain port.
- Add same-UID threat boundary, Origin header rejection, stale
lockfile sweep, multi-window safety, vault-scoped path validation,
and process.env mutation scope to constraints and research
questions.
- Add the openDiff accept-path question (reuse propose/commit
envelope per ADR-0032 vs. direct VaultPort.writeFile).
- Add the REQ-CCS-009 integration question (event-bus subscription
preferred over direct handler modification).
- Promote IDEA-TSP-001 to a hard frontmatter dependency with a
spawn-env hook precondition.
workflow-state.md updated with revised hand-off note and open
clarifications reflecting the answered and remaining questions
across the two review and three research passes.
https://claude.ai/code/session_01TR8tn5a6d5utftgtGz4nij
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
specs/claude-cli-ide-bridge/proposing an Option-4A integration: an Obsidian-side WebSocket MCP server that implements the reverse-engineered Claude Code IDE protocol so the embeddedclaudeinteractive session (IDEA-TSP-001) gains ambient vault awareness — the same surface VS Code and JetBrains plugins expose.idea.md(problem, users, success criteria, constraints, open research questions, preliminary scope) andworkflow-state.md(canonical ADR-005 schema, areaCIB).Why this exists
The existing
claude-cli-chat-sidebar(headless single-turn via the Agent SDK) andterminal-sidepanel(transparent PTY passthrough) both leave Claude blind to vault state. The reverse-engineered IDE protocol (lock file in~/.claude/ide/<port>.lock, env varsCLAUDE_CODE_SSE_PORT/ENABLE_IDE_INTEGRATION, JSON-RPC 2.0 overws://127.0.0.1:N, auth viax-claude-code-ide-authorizationheader) gives a clean way to add that awareness without modifying the CLI or the chat path. The user can keep typing into a literalclaudeTUI and Claude can callgetCurrentSelection,getOpenEditors,openFile,openDiff, etc., against Obsidian's workspace.Open research items captured in the idea
wsvs. hand-roll the WebSocket upgrade handshake.openDiffmodal UX and accept-path persistence.checkDocumentDirty/saveDocument.Spec-first gate
This PR contains only the idea artifact. Per
CLAUDE.mdandCONSTITUTION.md§3, no implementation branch may be opened until requirements are accepted.Test plan
idea.mdagainst the IDEA-CIB-001 problem statementhttps://claude.ai/code/session_01TR8tn5a6d5utftgtGz4nij
Generated by Claude Code