feat: add bridge script for Claude Code → LM Studio execution (v3.12.1)
Bridge script enables local execution of Claude Code plans via LM Studio: - Python CLI with 5 components (DoobidooReader, LMStudioClient, Validator, StepExecutor, PlanExecutor) - JSON Schema for plan validation (bridge-plan-schema.json) - Cost optimization: Plan with Opus (~$0.50-2), execute free locally (80-90% savings) - 4 validation types: json, syntax_check, contains_keys, non_empty - CLI: --health, --list, --plan ID, -v verbose mode Documentation: - New section "Local Execution Bridge" in ultimate-guide.md §11.2 - scripts/README.md with full usage documentation - machine-readable/reference.yaml entries for discoverability Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
2ace737018
commit
96da6ebd7e
10 changed files with 1223 additions and 10 deletions
265
examples/scripts/README.md
Normal file
265
examples/scripts/README.md
Normal file
|
|
@ -0,0 +1,265 @@
|
|||
# Scripts
|
||||
|
||||
Utility scripts for Claude Code power users.
|
||||
|
||||
## Overview
|
||||
|
||||
| Script | Description |
|
||||
|--------|-------------|
|
||||
| `audit-scan.sh` | Security and quality audit of Claude Code setup |
|
||||
| `check-claude.sh/.ps1` | Health check for Claude Code installation |
|
||||
| `clean-reinstall-claude.sh/.ps1` | Clean reinstall of Claude Code |
|
||||
| `fresh-context-loop.sh` | Run Claude Code in fresh context loops |
|
||||
| `session-search.sh` | Search across Claude Code session histories |
|
||||
| `session-stats.sh` | Statistics about Claude Code sessions |
|
||||
| `bridge.py` | Bridge: Claude Code → doobidoo → LM Studio |
|
||||
|
||||
---
|
||||
|
||||
## Bridge Script (Claude Code → LM Studio)
|
||||
|
||||
**Purpose**: Execute Claude Code plans locally via LM Studio for cost savings.
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
┌──────────────┐ store_memory ┌─────────────────┐
|
||||
│ Claude Code │ ─────────────────────►│ doobidoo │
|
||||
│ (Opus) │ tag: "plan" │ SQLite + Vec │
|
||||
│ PLANNER │ status: "pending" │ ~/.mcp-memory- │
|
||||
└──────────────┘ │ service/ │
|
||||
└────────┬────────┘
|
||||
│
|
||||
│ Direct SQLite read
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ bridge.py │
|
||||
│ │
|
||||
│ • PlanReader │
|
||||
│ • StepExecutor │
|
||||
│ • Validator │
|
||||
└────────┬────────┘
|
||||
│
|
||||
│ HTTP POST
|
||||
│ /v1/chat/completions
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ LM Studio │
|
||||
│ localhost:1234 │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### Requirements
|
||||
|
||||
```bash
|
||||
pip install httpx
|
||||
```
|
||||
|
||||
- **doobidoo MCP server** with SQLite backend (`~/.mcp-memory-service/`)
|
||||
- **LM Studio** running on `localhost:1234` with a loaded model
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
# Check LM Studio is running
|
||||
python bridge.py --health
|
||||
|
||||
# List pending plans
|
||||
python bridge.py --list
|
||||
|
||||
# Execute all pending plans
|
||||
python bridge.py
|
||||
|
||||
# Execute specific plan
|
||||
python bridge.py --plan plan_auth_refactor
|
||||
|
||||
# Verbose mode
|
||||
python bridge.py -v
|
||||
```
|
||||
|
||||
### Workflow
|
||||
|
||||
#### 1. Claude Code creates the plan
|
||||
|
||||
In Claude Code (Opus), store a plan via doobidoo:
|
||||
|
||||
```
|
||||
store_memory("""
|
||||
{
|
||||
"$schema": "bridge-plan-v1",
|
||||
"id": "plan_auth_refactor",
|
||||
"status": "pending",
|
||||
"context": {
|
||||
"project": "/path/to/project",
|
||||
"objective": "Refactor authentication to use JWT",
|
||||
"files_context": {
|
||||
"src/auth.py": "LOAD",
|
||||
"src/config.py": "REFERENCE"
|
||||
}
|
||||
},
|
||||
"steps": [
|
||||
{
|
||||
"id": 1,
|
||||
"type": "analysis",
|
||||
"description": "Analyze current auth implementation",
|
||||
"prompt": "Analyze the authentication code and identify migration points for JWT.",
|
||||
"validation": {"type": "non_empty"}
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"type": "code_generation",
|
||||
"description": "Generate JWT middleware",
|
||||
"prompt": "Generate a JWT authentication middleware based on the analysis.",
|
||||
"depends_on": [1],
|
||||
"validation": {"type": "syntax_check"},
|
||||
"file_output": "src/jwt_auth.py"
|
||||
}
|
||||
]
|
||||
}
|
||||
""", tags=["plan"])
|
||||
```
|
||||
|
||||
#### 2. Execute via bridge
|
||||
|
||||
```bash
|
||||
python bridge.py
|
||||
# Reads plan from doobidoo SQLite
|
||||
# Executes each step via LM Studio
|
||||
# Stores results back in doobidoo
|
||||
```
|
||||
|
||||
#### 3. Retrieve results in Claude Code
|
||||
|
||||
```
|
||||
search_by_tag(["result", "plan_auth_refactor"])
|
||||
# Returns all execution results
|
||||
```
|
||||
|
||||
### Plan Schema
|
||||
|
||||
See `bridge-plan-schema.json` for the complete JSON Schema.
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `$schema` | Yes | Must be `"bridge-plan-v1"` |
|
||||
| `id` | Yes | Unique plan ID (e.g., `plan_auth_refactor`) |
|
||||
| `status` | Yes | `pending`, `in_progress`, `completed`, `failed` |
|
||||
| `context.objective` | Yes | High-level goal description |
|
||||
| `context.project` | No | Absolute path to project root |
|
||||
| `context.files_context` | No | Files to inject (`LOAD`) or reference |
|
||||
| `steps` | Yes | Array of execution steps |
|
||||
|
||||
### Step Types
|
||||
|
||||
| Type | Use Case |
|
||||
|------|----------|
|
||||
| `analysis` | Analyze code, identify patterns, plan changes |
|
||||
| `code_generation` | Generate new code from scratch |
|
||||
| `code_modification` | Modify existing code |
|
||||
| `decision` | Make architectural or design decisions |
|
||||
|
||||
### Validation Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `non_empty` | Output is not empty (default) |
|
||||
| `json` | Valid JSON output |
|
||||
| `syntax_check` | Valid Python syntax |
|
||||
| `contains_keys` | JSON contains specific keys |
|
||||
|
||||
### Failure Handling
|
||||
|
||||
| on_failure | Behavior |
|
||||
|------------|----------|
|
||||
| `retry_with_context` | Retry with error feedback (default) |
|
||||
| `skip` | Skip step, continue execution |
|
||||
| `halt` | Stop entire plan |
|
||||
|
||||
### Cost Savings
|
||||
|
||||
- **Planning** (Opus): ~$0.50-2.00 per complex plan
|
||||
- **Execution** (LM Studio): Free (local)
|
||||
- **ROI**: 80-90% cost reduction on implementation tasks
|
||||
|
||||
### Limitations
|
||||
|
||||
| Limitation | Mitigation |
|
||||
|------------|------------|
|
||||
| Local model quality varies | Strict validation + retries |
|
||||
| No MCP tools in LM Studio | Inject file content in context |
|
||||
| Limited context window | Truncate old results |
|
||||
| No streaming | 120s timeout per step |
|
||||
|
||||
---
|
||||
|
||||
## Audit Scan
|
||||
|
||||
Security and quality audit of your Claude Code configuration.
|
||||
|
||||
```bash
|
||||
./audit-scan.sh
|
||||
```
|
||||
|
||||
Checks:
|
||||
- Sensitive data in CLAUDE.md files
|
||||
- Permission configurations
|
||||
- MCP server security
|
||||
- Hook script safety
|
||||
|
||||
---
|
||||
|
||||
## Health Check
|
||||
|
||||
Quick verification of Claude Code installation.
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
./check-claude.sh
|
||||
|
||||
# Windows
|
||||
./check-claude.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Clean Reinstall
|
||||
|
||||
Complete reinstall preserving configurations.
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
./clean-reinstall-claude.sh
|
||||
|
||||
# Windows
|
||||
./clean-reinstall-claude.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fresh Context Loop
|
||||
|
||||
Run Claude Code with fresh context for long-running tasks.
|
||||
|
||||
```bash
|
||||
./fresh-context-loop.sh --iterations 5 --project /path/to/project
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Search
|
||||
|
||||
Search across all Claude Code session histories.
|
||||
|
||||
```bash
|
||||
./session-search.sh "authentication"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Stats
|
||||
|
||||
Get statistics about your Claude Code usage.
|
||||
|
||||
```bash
|
||||
./session-stats.sh
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue