Your AI can change. Your work doesn't.
简体中文 · English
A local-first Tauri + Rust desktop app that turns an MCP-capable web AI — Claude.ai, or any MCP host — into a real coding agent on your machine. When your local agent (like Claude Code) hits its usage limit, crashes, or you just want to switch, Lexsus captures your real project state and hands the work off — so the web AI can read your files, write files, and run terminal commands, and you never re-explain the project.
- Key Features
- How It Works
- Tools at a Glance
- Quick Start
- Usage
- Security Model
- Status & Roadmap
- Troubleshooting
- Repository Layout
- Documentation & Learning Paths
- Contributing
- Community & Support
- License
| Feature | What it means for you | |
|---|---|---|
| 🔌 | Native MCP connector, not scraping | Your web AI talks to Lexsus through its own tool channel — a desktop-local MCP server on loopback (default http://127.0.0.1:45147/mcp, port configurable in the dashboard). Native tool UI, native results, no browser extension, no DOM watching, no composer injection. |
| 🔀 | Handoff, not copy-paste | One click packages the real state of your project — objective, decisions, failed attempts, constraints, changed files — into a prompt any web AI can continue from. Facts, not chat. |
| 🛠️ | Real coding-agent tools | 58 tools executed locally by the Rust core, not simulated in the browser — file reading (chunked) and editing, file management, shell commands (foreground + background), search, full git workflow, project memory, web fetch/search, code intelligence, and agent-loop primitives. See Tools at a Glance. |
| 👁️ | Live activity trace | Every read, write, and command the web AI performs shows up in real time, cross-checked against the filesystem watcher — nothing is claimed without evidence. |
| 🛡️ | Approval gates + session grants | Writes, commands, and destructive calls pause for your Allow / Deny. Tick "don't ask again" to grant a class of edits for the session; the kill switch revokes every grant and pauses the bridge. Every command streams live into the app's single read-only terminal so you see exactly what runs. |
| 🚦 | Read-only first | The connector exposes read tools only until you flip "Allow writes & commands" — live, from the desktop, no rebuild and no reconnect. |
| 🧠 | Structured project memory | Sessions are archived to embedded SQLite and distilled into objective, decisions, failed attempts, constraints, changed files, and heuristic progress. |
| 🔒 | Local-first by design | The connector binds to loopback only, embedded SQLite, and a minimal Tauri surface instead of Electron. Nothing leaves the machine unless you deliberately expose it. |
One connector, four layers — from raw capture to a delivered handoff:
- Capture — the app records real file, git, and terminal activity into a lossless Session Archive (Layer 1).
- Structure — the archive is distilled into facts, not chat: objective, decisions, failed attempts, constraints, changed files (Layer 2).
- Compress — an optional Python/FastAPI service summarizes the state into a handoff-sized snapshot for a fresh context window (Layer 3).
- Deliver — the Handoff Engine formats it for your chosen web AI, and the native MCP connector gives that AI real tools against the local project (Layer 4).
Full detail in docs/architecture.md.
The connector exposes 58 tools (source of truth: SPECS in src-tauri/src/bridge.rs), grouped by capability:
- Reading:
read_file(chunked, numbered lines),read_many_files,list_directory,notebook_read,read_media - Editing:
write_file,edit_file,multi_edit,apply_patch,delete_file,move_file,copy_file,create_directory,notebook_edit - Commands:
run_command,run_command_background,command_output,kill_command - Search:
grep(regex + glob filters),glob(path patterns) - Git:
git_status,git_diff,git_log,git_add,git_unstage,git_commit,git_branches,git_checkout,git_create_branch,git_show,git_commit_diff— powered bygit2, no external git process, committable from the app - Memory:
todo_write,todo_read,set_objective,remember_decision,remember_constraint,remember_attempt,get_facts,list_sessions,request_handoff,get_handoff - Web:
web_fetch(SSRF-guarded),web_search - Code intelligence:
lsp_diagnostics,lsp_definition,lsp_references,lsp_symbols - Agent loop:
delegate_task,ask_user,propose_plan,monitor,notify,report_findings - Isolation & delivery:
enter_worktree,exit_worktree,publish_artifact - Meta:
list_tools,describe_tool— the AI discovers the surface itself, so a chat can be primed without a handoff
Results are capped at 140,000 characters with explicit truncation markers. The full wire protocol is specified in docs/protocol-v2.md, and the phased build-out with invariants in docs/tool-roadmap.md.
Prerequisites: Node.js 20+, Rust (stable), pnpm. Python 3.12 is only needed for the optional compression service.
git clone https://github.com/abdulwasea89/lexsus.git
cd lexsus
pnpm install
pnpm tauri devWhen the app starts, the connector binds loopback (default http://127.0.0.1:45147/mcp) — the status bar shows connector · ro (read-only) and the Dashboard shows the exact endpoint, bound port, uptime and bound workspace. From there you can Start / Stop / Restart the connector, change its port, and manage the public tunnel.
Connect a web AI:
-
Claude.ai — Customize → Connectors → Add custom connector, and give it the endpoint. Claude.ai connects from Anthropic's cloud, so expose the loopback server with the dashboard's Public tunnel card (Start on
cloudflared,ngrok, or a custom command). The app scrapes the public URL, auto-allowlists the host and restarts the connector — no manual tunnel, no env var, no relaunch. Custom connectors still cannot send a header, so the tunnel must inject the bearer header at its edge. -
A local MCP host (Claude Code, Claude Desktop, the MCP Inspector) — point it straight at the loopback endpoint and pass the token as a header. No tunnel needed:
claude mcp add --transport http lexsus http://127.0.0.1:45147/mcp \ --header "Authorization: Bearer <token>"Reveal the token in Web-AI connector → Connector authentication; that panel also rotates it.
The connector starts read-only. Flip Allow writes & commands in the Web-AI connector view when you want the write and command tools exposed — every one of them still asks for your approval on the desktop.
| Env var | Purpose |
|---|---|
LEXSUS_MCP_ALLOW_WRITE=1 |
Seed the connector with writes & commands exposed on launch (still approval-gated). |
LEXSUS_MCP_ALLOWED_HOSTS=your-tunnel.example.com |
Additive headless/CI override on top of the dashboard's editable allowlist. Comma-separated; never removes loopback. |
LEXSUS_MCP_AUTH_TOKEN=<hex> |
Pin the bearer token instead of using the keyring or file. Reported as the env backend in the UI. |
LEXSUS_MCP_SIGNATURE_TTL_SECS=300 |
How far a signed request's timestamp may be from now. |
Optional — the LLM context-compression service (Layer 3):
docker compose up -d # or run it directly:
pip install -r compression-service/requirements.txt
uvicorn main:app --port 8000 --app-dir compression-serviceOpen a project in the desktop app and connect your web AI. The live activity trace shows every action it takes; each approved run_command streams into the single read-only terminal and lands in the git panel where you can commit from the app.
Hit your local agent's limit? Build a handoff from the app — or let the web AI pull it itself with the get_handoff tool. It packages the extracted facts — objective, decisions, failed attempts, constraints, changed files — so the AI inherits why, not just what, and won't retry dead ends.
Note
The connector is pull-based: MCP has no way to push a message into a chat, so the handoff is surfaced in-app (copy to clipboard) and also retrievable by the AI via get_handoff.
The AI calls Lexsus tools through its own native tool channel. Underneath, that is an MCP tools/call:
Large files come back one chunk at a time as numbered lines, with a footer naming the exact call that returns the next chunk — the AI pages through what it needs instead of being handed a whole file it can't absorb. run_command output streams back chunk-by-chunk, and the write/run tools block on your Allow / Deny on the desktop before touching disk or shell.
- Loopback-only: the MCP server binds
127.0.0.1on a configurable port (default45147, seesrc-tauri/src/mcp.rs). Remote hosts are rejected unless explicitly allowlisted from the dashboard (or, additively, viaLEXSUS_MCP_ALLOWED_HOSTS). - Authenticated on every request, loopback included: a bearer token (
Authorization: Bearer …) is required with no bypass, so allowlisting a tunnel host does not hand the URL alone the read surface. The token is generated from the OS CSPRNG and kept in the OS keyring, falling back to a0600file where there is none; the UI shows which store is live, reveals the token on request, and rotates it without a restart. - Signed responses: every response carries
X-Lexsus-Signature, an HMAC the caller can check to detect a tunnel or proxy that altered it. A request signature is verified strictly when presented but never required — no MCP client can compute one. This detects tampering; it is not confidentiality past TLS termination. - Read-only first: write/command tools stay hidden until you opt in, live, from the desktop.
- Every mutation is gated: writes, commands, and destructive calls (
delete_file,move_file,git_checkout, …) pause for approval, showing the resolved absolute path. - Session grants + kill switch: "don't ask again" grants a class of edits for the session only; the kill switch revokes all grants and pauses the bridge.
- Local-first storage: session archive and project memory live in embedded SQLite. No cloud dependency; the optional tunnel for Claude.ai is short-lived and explicit.
Note
Status: early-stage MVP — the core bridge works end-to-end (archive, facts, handoff, tool relay, live terminal). The compression service (/compress) is still a stub; a 5–10 developer validation comes before scaling features.
What's next: hardening the approval/audit surface, completing compression (Layer 3), and expanding the tool surface per docs/tool-roadmap.md. Adding a tool? Read the invariants there first: a new tool is registered once in SPECS (src-tauri/src/bridge.rs) with a matching JSON Schema, and the read-only/write gate must keep hiding it until writes are allowed.
| Symptom | Likely cause / fix |
|---|---|
| Web AI can't reach the endpoint | Confirm the connector is running in the dashboard (and note its bound port); local hosts need no tunnel, Claude.ai cloud needs the HTTPS tunnel started from the dashboard. |
401 unauthorized from the AI |
Every request needs Authorization: Bearer <token>. Reveal the token in Web-AI connector → Connector authentication; rotate it if it leaked — the old one stops working at once. |
| Tunnel host rejected | Start the tunnel from the dashboard so its host is auto-allowlisted, or edit the allowlist there and press Apply hosts. The allowlist is additive to loopback. |
| Write tools not visible to the AI | Flip Allow writes & commands in the Web-AI connector view (or launch with LEXSUS_MCP_ALLOW_WRITE=1). |
| Approval card never resolves | Check the desktop app is focused — approvals block the tool call until you Allow/Deny. |
/compress returns stub data |
Expected: the compression service is still a stub (see Status above). |
├── src/ # React + TypeScript frontend (Tauri shell)
├── src-tauri/ # Rust core — git2, portable-pty, notify, rusqlite, native MCP server
│ ├── .cargo/config.toml # build-output footprint control (see the file header)
│ └── src/
│ ├── mcp.rs # the connector: rmcp Streamable HTTP on loopback
│ └── bridge/ # tool engine
│ ├── mod.rs # Tool enum, results, approval policy, execute()
│ ├── specs.rs # the SPECS registry — single source of truth
│ └── schema.rs # parse_tool_call + the tools/list JSON Schemas
├── compression-service/ # Optional Python FastAPI context compression (Layer 3)
├── docs/ # Architecture, connector protocol, tech stack, UI design, tool roadmap
├── requirements/ # Product requirements, MVP scope, trade-offs
├── ongoing/ # Active work logs and runbooks
└── public/ # Static web assets
Reading the docs in this order takes you from "what is this" to "how the wire works":
| # | Doc | Covers |
|---|---|---|
| 1 | docs/architecture.md | The connector and the four layers |
| 2 | docs/tech-stack.md | Tauri + Rust systems stack, security rationale |
| 3 | docs/protocol-v2.md | Connector protocol, tool schemas, approvals, error codes, sequence diagrams |
| 4 | docs/ui-design.md | The dashboard: connector, tunnel, OAuth clients, tool surface, activity |
| 5 | docs/tool-roadmap.md | The tool surface, phase by phase: built vs planned, and the invariants |
| 6 | docs/connector-native-proof-runbook.md | Exposing the connector and proving natively with Claude.ai |
| 7 | requirements/product-requirements.md | Product & MVP scope, success criteria |
| 8 | ongoing/facts-and-archive.md | Completed work: session archive (F2) + fact extraction (F3) |
Contributions are welcome — the CI already enforces quality on every PR (frontend lint/typecheck/build, cargo fmt/clippy, compression-service health).
- Fork the repo and create a branch (
git checkout -b feat/your-idea). - Make your change — keep it focused, add a test where reasonable.
- Open a pull request — CI runs automatically and must pass.
Check the issues for easy entry points. Note: there's no CONTRIBUTING.md yet — if you'd like to drive its conventions, start a discussion.
- 💬 Ask questions and propose features in GitHub Discussions.
- 🐛 Report bugs via issues.
- ⭐ Enjoy the project? Star the repo — it's the fastest way to help the bridge reach more developers.
Released under the MIT License. Built with Tauri, React, the Rust ecosystem (git2, portable-pty, rusqlite, notify, rmcp), and FastAPI.
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "read_file", "arguments": { "path": "src/App.tsx", "offset": 401 }, }, }