|
| 1 | +# RFC: Socratic Shell VSCode Extension for Centralized Installation and Configuration |
| 2 | + |
| 3 | +> **Tracking Issue**: [#16 - Implement unified Socratic Shell installation and MCP server](https://github.com/socratic-shell/socratic-shell/issues/16) |
| 4 | +
|
| 5 | +## Problem Statement |
| 6 | + |
| 7 | +Socratic Shell currently exists as a collection of separate tools and documentation patterns that require manual setup and configuration. Users must: |
| 8 | +- Manually install and configure multiple MCP servers (hippo, dialectic) |
| 9 | +- Set up context injection for their AI tools |
| 10 | +- Configure hooks and integrations |
| 11 | +- Understand complex multi-tool interactions |
| 12 | + |
| 13 | +This creates a high barrier to entry and limits adoption. |
| 14 | + |
| 15 | +## Goals |
| 16 | + |
| 17 | +Transform Socratic Shell from a collection of tools into a cohesive collaborative AI environment that "just works out of the box" through: |
| 18 | + |
| 19 | +1. **Single Installation Point**: VSCode extension as the primary distribution mechanism |
| 20 | +2. **Unified MCP Interface**: One MCP server that orchestrates all Socratic Shell capabilities |
| 21 | +3. **Guided Setup**: UI-driven configuration that adapts to user's AI tool (Claude Code, Q CLI) |
| 22 | +4. **Complete Integration**: Automatic context injection, hook setup, and lifecycle management |
| 23 | + |
| 24 | +## High-Level Architecture |
| 25 | + |
| 26 | +### Components |
| 27 | + |
| 28 | +**VSCode Extension (Control Plane)** |
| 29 | +- Installation orchestration and UI guidance |
| 30 | +- Lifecycle management of background services |
| 31 | +- Platform detection and binary selection |
| 32 | +- Configuration management |
| 33 | + |
| 34 | +**Socratic Shell MCP Server (Rust Binary)** |
| 35 | +- Unified MCP interface for AI tools |
| 36 | +- Request routing to backend services |
| 37 | +- Process management for backend MCP servers |
| 38 | +- Hook execution (conversation-start, per-prompt) |
| 39 | + |
| 40 | +**Backend MCP Servers** |
| 41 | +- `hippo-standalone` (Python executable) - memory operations |
| 42 | +- `dialectic-server` (TypeScript bundle) - code review and file operations |
| 43 | +- Future components as separate MCP servers |
| 44 | + |
| 45 | +### Distribution Strategy |
| 46 | + |
| 47 | +**Multi-Binary Bundling** |
| 48 | +``` |
| 49 | +socratic-shell-extension/ |
| 50 | +├── binaries/ |
| 51 | +│ ├── windows-x64/ |
| 52 | +│ ├── darwin-x64/ |
| 53 | +│ ├── darwin-arm64/ |
| 54 | +│ └── linux-x64/ |
| 55 | +├── dialectic/ (TypeScript bundle) |
| 56 | +└── extension.js |
| 57 | +``` |
| 58 | + |
| 59 | +**Installation Flow** |
| 60 | +1. User installs VSCode extension from marketplace |
| 61 | +2. Extension detects platform and AI tool configuration |
| 62 | +3. UI guides user through setup choices |
| 63 | +4. Extension configures MCP connections and hooks |
| 64 | +5. Background services start automatically |
| 65 | + |
| 66 | +## Key Design Decisions |
| 67 | + |
| 68 | +### Why VSCode Extension as Primary Distribution? |
| 69 | +- Single install point with cross-platform support |
| 70 | +- Built-in UI capabilities for guided setup |
| 71 | +- Natural integration with dialectic (already VSCode-focused) |
| 72 | +- Handles binary distribution and lifecycle management |
| 73 | + |
| 74 | +### Why Rust for Main MCP Server? |
| 75 | +- Single static binary (easy bundling) |
| 76 | +- Minimal resource overhead for orchestration |
| 77 | +- Excellent process management and IPC capabilities |
| 78 | +- Good cross-platform support |
| 79 | + |
| 80 | +### Why Multi-Binary vs Universal Binary? |
| 81 | +- Proven Rust cross-compilation toolchain |
| 82 | +- Avoids experimental dependencies (cosmopolitan) |
| 83 | +- Predictable behavior across platforms |
| 84 | +- Standard CI/CD pipeline support |
| 85 | + |
| 86 | +### Why Bundle All Binaries Initially? |
| 87 | +- Simplest installation experience ("just works offline") |
| 88 | +- Eliminates network dependency failures |
| 89 | +- Can optimize with lazy download later if size becomes issue |
| 90 | + |
| 91 | +## Implementation Phases |
| 92 | + |
| 93 | +### Phase 1: Core Infrastructure |
| 94 | +- Rust MCP server with basic routing |
| 95 | +- VSCode extension with platform detection |
| 96 | +- Multi-platform build pipeline |
| 97 | +- Basic backend server integration (hippo, dialectic) |
| 98 | + |
| 99 | +### Phase 2: Installation Experience |
| 100 | +- Guided setup UI in VSCode extension |
| 101 | +- AI tool detection and configuration |
| 102 | +- Context injection mechanisms |
| 103 | +- Hook system integration |
| 104 | + |
| 105 | +### Phase 3: Enhanced Features |
| 106 | +- Canned prompts/tools for common operations |
| 107 | +- Project-specific setup automation |
| 108 | +- Advanced lifecycle management |
| 109 | +- Performance optimizations |
| 110 | + |
| 111 | +## Open Questions |
| 112 | + |
| 113 | +1. **Hook Integration Points**: Where exactly do we plug into Claude Code vs Q CLI lifecycle events? |
| 114 | +2. **Context Injection Mechanics**: How do we reliably inject prompts into different AI tool contexts? |
| 115 | +3. **Backend Server Lifecycle**: Start/stop on demand vs keep-alive strategies? |
| 116 | +4. **Configuration Management**: How do we handle updates and version compatibility? |
| 117 | +5. **Error Handling**: How do we provide good diagnostics when components fail? |
| 118 | + |
| 119 | +## Success Criteria |
| 120 | + |
| 121 | +- New user can install and use Socratic Shell in under 5 minutes |
| 122 | +- Single VSCode extension provides complete Socratic Shell experience |
| 123 | +- Works reliably across Windows, macOS, and Linux |
| 124 | +- Extensible architecture supports future Socratic Shell components |
| 125 | +- Maintains performance characteristics of individual tools |
| 126 | + |
| 127 | +## Related RFCs |
| 128 | + |
| 129 | +- [MCP Server Implementation Details](./mcp-server.md) |
| 130 | +- [Hook System Design](./hooks.md) |
| 131 | +- [Repository Coordination and Multi-Language Bundling](./repo-coordination.md) |
0 commit comments