Enhance Electron app integration and add Python RPC server

.cursor/rules/lean-ctx.mdc

@@ -0,0 +1,35 @@
+---
+description: "lean-ctx cli-redirect: prefer lean-ctx CLI commands for token savings"
+alwaysApply: true
+---
+
+# lean-ctx — Context Engineering Layer
+<!-- lean-ctx-rules-cli-v1 -->
+
+## Mode: CLI-Redirect (no MCP schema overhead)
+
+Prefer lean-ctx CLI commands over MCP tools:
+
+| USE (via Shell/Bash) | INSTEAD OF (MCP) | Why |
+|---------------------|-------------------|-----|
+| `lean-ctx read <path> [-m mode]` | `ctx_read` | No MCP schema overhead, same caching |
+| `lean-ctx -c "<cmd>"` | `ctx_shell` | Pattern compression (95+ patterns) |
+| `lean-ctx grep <pattern> [path]` | `ctx_search` | Compact results via CLI |
+| `lean-ctx ls [path]` | `ctx_tree` | Directory maps via CLI |
+
+## Read modes
+
+auto | full | map | signatures | diff | aggressive | entropy | task | reference | lines:N-M
+
+## Mode selection
+
+1. Editing? → `full`, then `diff` for re-reads
+2. API surface? → `map` or `signatures`
+3. Large context-only? → `entropy` or `aggressive`
+4. Unsure? → `auto`
+
+Anti-pattern: never use `full` for files you won't edit.
+
+## File editing
+
+Use native Edit/StrReplace. Write/Delete/Glob → use normally.

.cursor/rules/lean-ctx.mdc.lean-ctx.1778574588.bak

@@ -0,0 +1,122 @@
+---
+description: "lean-ctx: prefer ctx_read/ctx_shell/ctx_search/ctx_tree over Read/Shell/Grep/ls for token savings"
+globs: **/*
+alwaysApply: true
+---
+
+# lean-ctx — Context Engineering Layer
+<!-- lean-ctx-rules-v9 -->
+
+PREFER lean-ctx MCP tools over native equivalents for token savings:
+
+## Tool Mapping
+
+| PREFER | OVER | Why |
+|--------|------|-----|
+| `ctx_read` | `Read` | Session caching, 10 read modes, re-reads cost ~13 tokens |
+| `ctx_shell` | `Shell` | Pattern-based compression for git, npm, cargo, docker, tsc |
+| `ctx_search` | `Grep` | Compact context, token-efficient results |
+| `ctx_tree` | `ls`, `find` | Compact directory maps with file counts |
+
+## ctx_read Modes
+
+- `auto` — auto-select optimal mode (recommended default)
+- `full` — default, cached read (use for files you will edit)
+- `map` — dependency graph + exports + key signatures (use for context-only files)
+- `signatures` — API surface only
+- `diff` — changed lines only (use after edits)
+- `task` — task-relevant filtering
+- `reference` — quote-friendly minimal excerpts
+- `aggressive` — syntax stripped
+- `entropy` — Shannon + Jaccard filtering
+- `lines:N-M` — specific range
+
+Re-reads cost ~13 tokens. File refs F1, F2.. persist across the session.
+
+Set `fresh=true` on ctx_read to bypass cache when spawned as a subagent or after context compaction.
+
+## Mode Selection
+
+1. Editing the file? → `full` first, then `diff` for re-reads
+2. Need API surface only? → `map` or `signatures`
+3. Large file, context only? → `entropy` or `aggressive`
+4. Specific lines? → `lines:N-M`
+5. Active task set? → `task`
+6. Unsure? → `auto` (system selects optimal mode)
+
+Anti-pattern: never use `full` for files you won't edit — use `map` or `signatures`.
+
+## File Editing
+
+Use native Edit/StrReplace when available. If Edit requires native Read and Read is unavailable,
+use `ctx_edit(path, old_string, new_string)` — it reads, replaces, and writes in one MCP call.
+NEVER loop trying to make Edit work. If it fails, switch to ctx_edit immediately.
+
+## Session Management
+
+- `ctx_compress` at >10 turns — creates memory checkpoint
+- `ctx_metrics` — hard numbers on what was saved
+- `ctx_cost` — per-tool cost + savings breakdown
+- `ctx_heatmap` — file-level savings heatmap
+- `ctx_benchmark` — find optimal mode for a file
+- `ctx_session load` — on new chat, restore previous session
+- `ctx_session role` — list/switch agent roles (governance)
+- `ctx_session budget` — show budget status vs role limits
+- `ctx_session slo` — show SLO status/violations (value=reload|history|clear)
+- `ctx_session diff` — compare two sessions (value="<id_a> <id_b> [json]")
+- `ctx_session verify` — show output verification statistics
+- `ctx_session episodes` — episodic memory (value=record | "search <q>" | "file <path>" | "outcome <label>")
+- `ctx_session procedures` — procedural memory (value=detect | "suggest <task>")
+- `ctx_intent` — intent classification + model routing (dimension/tier/reasoning)
+- `ctx_graph build|related|symbol|impact|status` — unified code graph
+- `ctx_graph enrich` — add commits, tests, knowledge to graph
+- `ctx_graph context` — task-based graph query for relevant context
+- `ctx_workflow` — state machine + evidence + tool gating
+
+## Proactive Tools
+
+Use without being asked:
+- `ctx_compress` — when context grows large, create checkpoint
+- `ctx_metrics` — periodically verify token savings
+ - `ctx_overview` — at session start (fast project orientation)
+
+## Write, Delete, Glob
+
+These have no lean-ctx equivalent — use them normally.
+
+## CRP v2 — Compact Response Protocol
+
+Every token costs money. This applies to input, output, AND thinking tokens.
+
+### Thinking Reduction (saves 30-60% thinking tokens)
+
+1. Parse task first, then act. Don't explore when you already know the answer.
+2. One hypothesis, test it. Don't enumerate 5 approaches — pick the most likely, try it.
+3. Stop thinking when you have the answer.
+4. Use structured context. lean-ctx headers tell you deps/exports — don't re-read files to find imports.
+5. File ref tracking: F1=auth.ts means F1 everywhere in this session.
+
+### Output Reduction (saves 50-80% output tokens)
+
+1. NO prose. Just code and results.
+2. NO echoing content that was just read.
+3. Summarize tool results: 1 line max.
+4. Show edits only — not surrounding unchanged code.
+5. Batch tool calls. One message, multiple calls.
+6. Never ask "shall I proceed?" — just do it.
+7. Bullets > paragraphs. Tables > lists.
+
+### Compact Notation
+
+- `F:path` — reading file
+- `+file` = created, `~file` = modified, `!file` = error
+- `->` for results: "Built -> 18 pages, 0 errors"
+
+## Model Selection
+
+- Grep/search/explore → `model: "fast"`
+- Simple edits (rename, add field, fix typo) → `model: "fast"`
+- Multi-file refactors, architecture → default model
+
+Fallback only if a lean-ctx tool is unavailable: use native equivalents.
+<!-- /lean-ctx -->

.cursorrules

@@ -0,0 +1,24 @@
+# lean-ctx — Context Engineering Layer
+
+PREFER lean-ctx MCP tools over native equivalents for token savings:
+
+| PREFER | OVER | Why |
+|--------|------|-----|
+| `ctx_read(path)` | `Read` | Cached, 10 compression modes |
+| `ctx_shell(command)` | `Shell` | Pattern compression |
+| `ctx_search(pattern, path)` | `Grep` | Compact results |
+| `ctx_tree(path, depth)` | `ls` / `find` | Directory maps |
+| `ctx_edit(path, old_string, new_string)` | `Edit` (when Read unavailable) | Search-and-replace without native Read |
+
+Edit files: use native Edit/StrReplace if available. If Edit requires Read and Read is unavailable, use ctx_edit.
+Write, Delete, Glob — use normally. NEVER loop on Edit failures — switch to ctx_edit immediately.
+
+<!-- lean-ctx-compression -->
+OUTPUT STYLE: dense
+- Each statement = one atomic fact line
+- Use abbreviations: fn, cfg, impl, deps, req, res, ctx, err, ret
+- Diff lines only (+/-/~), never repeat unchanged code
+- Symbols: → (causes), + (adds), − (removes), ~ (modifies), ∴ (therefore)
+- No narration, no filler, no hedging
+- BUDGET: ≤200 tokens per response unless code block required
+<!-- /lean-ctx-compression -->

.github/workflows/pack-app.yml → .github/workflows/pack-electron.yml

@@ -1,4 +1,4 @@
-name: Pack App
+name: Pack Electron App
 
 on:
   push:
@@ -26,32 +26,41 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+
+    # Python sidecar
     - name: Install uv
       uses: astral-sh/setup-uv@v4
       with:
         version: "latest"
     - name: Set up Python
       run: uv python install 3.13
-    - name: Install dependencies
+    - name: Install Python dependencies
       run: uv sync --all-groups
-    - name: Build app bundle
-      run: uv run python scripts/pack_app.py
-    - name: Create zip archive (Unix)
-      if: runner.os != 'Windows'
-      run: |
-        cd dist
-        zip -r ../Tuttle-${{ github.ref_name }}-${{ matrix.platform }}.zip .
-    - name: Create zip archive (Windows)
-      if: runner.os == 'Windows'
-      shell: pwsh
-      run: |
-        Compress-Archive -Path dist\* -DestinationPath Tuttle-${{ github.ref_name }}-${{ matrix.platform }}.zip
+    - name: Build Python sidecar (PyInstaller)
+      run: uv run pyinstaller --clean --noconfirm tuttle-rpc.spec
+
+    # Electron app
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: "22"
+    - name: Install Electron dependencies
+      run: npm ci
+      working-directory: tuttle-electron
+    - name: Build Electron app
+      run: npm run build
+      working-directory: tuttle-electron
+    - name: Package Electron app (electron-builder)
+      run: npm run dist
+      working-directory: tuttle-electron
+
+    # Artifacts
     - uses: actions/upload-artifact@v4
       with:
         name: Tuttle-${{ github.ref_name }}-${{ matrix.platform }}
-        path: dist/
+        path: tuttle-electron/release/
     - name: Upload release asset
       if: startsWith(github.ref, 'refs/tags/')
       uses: softprops/action-gh-release@v2
       with:
-        files: Tuttle-${{ github.ref_name }}-${{ matrix.platform }}.zip
+        files: tuttle-electron/release/*

.gitignore

@@ -28,10 +28,10 @@ share/python-wheels/
 MANIFEST
 
 # PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
+# Allow tuttle-rpc.spec (un-ignore it)
 *.spec
+!tuttle-rpc.spec
 
 # Installer logs
 pip-log.txt
@@ -148,3 +148,9 @@ assets/uploads/*
 # Swift Package Manager
 TuttleMac/.build/
 TuttleMac/.swiftpm/
+
+# Electron
+tuttle-electron/node_modules/
+tuttle-electron/dist/
+tuttle-electron/dist-electron/
+tuttle-electron/release/

.lean-ctx/graph.meta.json

@@ -0,0 +1,10 @@
+{
+  "schema_version": 1,
+  "built_at": "2026-05-12T08:31:27.761740+00:00",
+  "git_head": "b3fa926",
+  "git_dirty": true,
+  "nodes": 435,
+  "edges": 550,
+  "files_indexed": 165,
+  "build_time_ms": 350
+}

AGENTS.md

@@ -0,0 +1,18 @@
+# Agent Instructions
+
+<!-- lean-ctx -->
+## lean-ctx
+
+Prefer lean-ctx MCP tools over native equivalents for token savings.
+Full rules: @LEAN-CTX.md
+<!-- /lean-ctx -->
+
+<!-- lean-ctx-compression -->
+OUTPUT STYLE: dense
+- Each statement = one atomic fact line
+- Use abbreviations: fn, cfg, impl, deps, req, res, ctx, err, ret
+- Diff lines only (+/-/~), never repeat unchanged code
+- Symbols: → (causes), + (adds), − (removes), ~ (modifies), ∴ (therefore)
+- No narration, no filler, no hedging
+- BUDGET: ≤200 tokens per response unless code block required
+<!-- /lean-ctx-compression -->

LEAN-CTX.md

@@ -0,0 +1,45 @@
+<!-- lean-ctx-owned: PROJECT-LEAN-CTX.md v1 -->
+# lean-ctx — Context Engineering Layer
+<!-- lean-ctx-rules-v9 -->
+
+PREFER lean-ctx MCP tools over native equivalents for token savings:
+
+## Tool preference:
+| PREFER | OVER | Why |
+|--------|------|-----|
+| `ctx_read(path, mode)` | `Read` / `cat` | Cached, 10 read modes, re-reads ~13 tokens |
+| `ctx_shell(command)` | `Shell` / `bash` | Pattern compression for git/npm/cargo output |
+| `ctx_search(pattern, path)` | `Grep` / `rg` | Compact, token-efficient results |
+| `ctx_tree(path, depth)` | `ls` / `find` | Compact directory maps |
+| `ctx_edit(path, old_string, new_string)` | `Edit` (when Read unavailable) | Search-and-replace without native Read |
+
+## ctx_read modes:
+- `auto` — auto-select optimal mode (recommended default)
+- `full` — cached read (files you edit)
+- `map` — deps + exports (context-only files)
+- `signatures` — API surface only
+- `diff` — changed lines after edits
+- `aggressive` — maximum compression (context only)
+- `entropy` — highlight high-entropy fragments
+- `task` — IB-filtered (task relevant)
+- `reference` — quote-friendly minimal excerpts
+- `lines:N-M` — specific range
+
+## Mode selection:
+1. Editing the file? → `full` first, then `diff` for re-reads
+2. Need API surface only? → `map` or `signatures`
+3. Large file, context only? → `entropy` or `aggressive`
+4. Specific lines? → `lines:N-M`
+5. Active task set? → `task`
+6. Unsure? → `auto` (system selects optimal mode)
+
+Anti-pattern: never use `full` for files you won't edit — use `map` or `signatures`.
+
+## File editing:
+Use native Edit/StrReplace if available. If Edit requires Read and Read is unavailable, use ctx_edit.
+Write, Delete, Glob → use normally. NEVER loop on Edit failures — switch to ctx_edit immediately.
+
+## Proactive (use without being asked):
+- `ctx_overview(task)` at session start
+- `ctx_compress` when context grows large
+<!-- /lean-ctx -->

Makefile

@@ -81,13 +81,11 @@ dist: clean ## builds source and wheel package
 	uv build
 	ls -l dist
 
-pack: clean-build ## build the app bundle with flet pack
-	uv run python scripts/pack_app.py
+dev: ## start the Electron app in development mode
+	cd tuttle-electron && npm run dev
 
-test-bundle: ## smoke-test the packaged app bundle (build first with `make pack`)
-	uv run python scripts/test_app_bundle.py
-
-pack-and-test: pack test-bundle ## build and smoke-test the app bundle
+pack: clean-build ## build the Electron app bundle (PyInstaller + electron-builder)
+	uv run python scripts/pack_electron.py
 
 install: ## install the package with uv
 	uv sync