Amr Gharbeia
a0f7bd7671
Gate trace: cognitive-verify accumulates (:gate name :result status) for each deterministic gate. Trace prepended to action plist via list*. TUI on-daemon-msg extracts :gate-trace and stores on message object. add-msg accepts &key gate-trace for future rendering (collapsible Tab). Rule counter: TUI actuator enriches response payload with :rule-count =(hash-table-count *hitl-pending*). TUI status bar shows 'Rules:N'. Focus map: TUI actuator adds :foveal-id from signal context. TUI stores in state and renders second status line '[Focus: id]'. Status bar: now two lines — line 1 (connection, mode, msgs, scroll, rules, thinking spinner), line 2 (focus map, timestamp). Test: 112/0 across 14 suites (reason 15/0 including gate-trace assertions)
Passepartout — The Plain-Text AI Assistant That Never Gets More Expensive
- What Makes Passepartout Different
- How It Works
- Current Capabilities
- Quick Start
- Project Documentation
- License
Passepartout is an AI assistant that runs in your terminal. It reads and writes your Org-mode files, executes tasks through a verified safety gate, and works fully offline with local LLMs. Every action the LLM proposes is checked by nine deterministic safety gates before it touches a file, runs a command, or sends a message. The LLM suggests. The gate decides. Everything it knows is a folder of plain text files that you own.
Install:
curl -fsSL https://raw.githubusercontent.com/amrgharbeia/passepartout/main/passepartout | bash -s configureThis installs dependencies (SBCL, Quicklisp), tangles the Org source files, and runs the setup wizard for LLM providers. Requires curl and sudo access for package installation.
What Makes Passepartout Different
Every action is verified, not trusted.
Most AI agents add safety checks as an afterthought — prompt-based guardrails that consume LLM tokens and can be evaded with clever phrasing. Passepartout inverts this: nine deterministic safety gates run in pure Lisp between the LLM's proposal and execution. Secret scanning checks for API key leaks. Path protection blocks reads and writes to sensitive files. Shell safety detects destructive commands and injection vectors. Network exfiltration detection flags unauthorized outbound connections. Lisp syntax validation catches malformed code before it writes to disk.
Every gate costs 0 LLM tokens. Every gate is a Common Lisp function, not a prompt. Every gate runs for every action, unconditionally.
If a gate blocks a proposal, the rejection feedback goes back to the LLM so it can self-correct and try again. If the deterministic Dispatcher is uncertain, it creates a Flight Plan — a human-readable Org buffer you review and approve. The human decides. The Dispatcher learns from your decision and writes a rule for next time.
The more you use it, the cheaper it gets.
Passepartout has a downward cost curve. This runs counter to every other AI agent.
Here is why. When you use Passepartout, the Dispatcher observes every blocked action and every human-approved exception. Each decision becomes a deterministic rule. A file write you approved once becomes an allowed path pattern. A shell command you denied becomes a permanent block. Each hardened rule means one fewer LLM call next time.
Meanwhile, the foveal-peripheral context model prunes your memex — your personal knowledge base, a term coined by Vannevar Bush in 1945 for a mechanised private library — to the relevant Org subtrees before sending anything to the LLM. The agent does not load your entire knowledge base, or even the entire file like agents that use Markdown do — it loads precisely the headlines that matter. Less context in, fewer tokens out.
Other agents grow more expensive over time (context histories accumulate, safety instructions grow). Passepartout's cost curve bends down.
It edits its own source code. Verified before execution.
Passepartout can read its own Org-mode source files, propose changes, and hot-reload skills into the running image without restarting. The skill engine loads every skill into a jailed Common Lisp package, validates its syntax, tests its trigger function in isolation, and only then promotes it to the live registry.
Core pipeline files — the Perceive-Reason-Act loop, the Merkle-tree memory, the Dispatcher gate stack — are path-protected. The agent could modify its own brain stem, but it cannot do this without human review. Skills and system modules expand freely. The core stays small, protected, and auditable.
No other AI agent can modify its own reasoning engine and reload the change while it is running. This is not a planned feature. It works today.
Your memory and your tasks are the same format. Org-mode.
Passepartout makes a bet that most systems consider too expensive: humans and machines should share the same file format. That format is Org-mode.
Your notes, your calendar, your project plans, the agent's memory, and the agent's own source code are all the same thing: Org files in ~/memex/. =headline trees. Property drawers for metadata. Source blocks for code. TODO keywords for task state. Tags for categorization.
When you write a TODO in Emacs, the agent sees it immediately as a native data structure and acts on it. When the agent creates a note, you can open it in any text editor and read it. There is no import/export step, no hidden database (except maybe for indexing), no format conversion. If Passepartout stops existing tomorrow, your data survives in plain text, readable in 2040.
Works offline. Works locally. The safety doesn't stop.
You can run Passepartout entirely on your hardware with a local LLM via Ollama or some other inference engine. No internet connection required. But unlike most local AI tools, offline mode does not mean safety-last. The nine deterministic safety gates are pure Common Lisp — they run identically whether you are online or off. The Merkle-tree memory with snapshot rollback is in-process, 0 milliseconds, 0 network calls. Semantic retrieval runs on in-image vectors, 0 LLM tokens per query.
Cloud providers (OpenRouter, OpenAI, Anthropic, Groq, Gemini, DeepSeek, NVIDIA NIM…) are optional add-ons. When you use them, the model-tier router automatically selects the cheapest provider that matches your task's complexity. Privacy-tagged content stays local even when cloud providers are configured.
How It Works
Every signal — a chat message, a heartbeat tick, a file change notification — moves through three stages:
Signal → Perceive → Reason → Act
normalize LLM proposes dispatch approved action
gates verify tool output feeds back
Perceive normalizes raw input from any gateway (TUI, CLI, Telegram, Signal) into a uniform signal plist. Buffer updates from Emacs ingest Org AST nodes into memory. Heartbeat ticks trigger background maintenance. HITL commands intercept before the LLM is invoked.
Reason calls the LLM to generate a proposal, then runs the proposal through every registered deterministic gate — sorted by priority, highest first. If a gate rejects (shell command blocked, path protected, secret exposed), the rejection trace feeds back to the LLM for self-correction, up to three retries. If a gate requests human approval, the action becomes a Flight Plan awaiting your decision. If all gates pass, the action proceeds to Act.
Act dispatches the approved action to the correct actuator: shell commands go to the shell actuator (with timeout and output limiting), tool invocations go to the cognitive tool registry, system commands trigger internal harness operations, and chat responses route to the TUI or messaging gateway. Each stage can feed back into Perceive — a tool output becomes the next perception.
This pipeline is not a single-threaded bottleneck. The priority-queued signal processor (v0.5.0 roadmap) preempts background maintenance for user interactions. The Merkle-tree memory supports concurrent reads and writes through versioned snapshots — multiple signals can process simultaneously without corrupting shared state.
Deep detail: Architecture for the full code map and pipeline flow, Design Decisions for the rationale behind every architectural choice.
Current Capabilities
Features marked Stable ship in the current release. Features marked Planned are scheduled in the Roadmap.
| Capability | Status | Since | Notes |
|---|---|---|---|
| 9-vector deterministic safety | Stable | v0.2.0 | Secrets, paths, shells, network, lisp, privacy |
| Foveal-peripheral context model | Stable | v0.2.0 | Sends relevant subtrees, not all files |
| Merkle-tree memory + snapshots | Stable | v0.2.0 | Integrity hashing, copy-on-write rollback |
| Self-editing + hot-reload | Stable | v0.2.0 | Agent reads, modifies, reloads its own code |
| 8 provider cascade | Stable | v0.1.0 | OpenRouter, OpenAI, Anthropic, Groq, Gemini, DeepSeek, NVIDIA, local |
| Terminal UI (Croatoan) | Stable | v0.2.0 | Scrollback, history, themes, commands, tab completion |
| Skill engine (20+ skills) | Stable | v0.1.0 | Jailed loading, topological sort, hot-reload |
| Human-in-the-Loop approval | Stable | v0.3.0 | Flight Plan workflow for blocked actions |
| Model-tier routing | Stable | v0.3.0 | Sends simple tasks to cheaper models |
| Event orchestrator (hooks + cron) | Stable | v0.3.0 | Org-based hook and cron dispatch |
| Context manager (project scoping) | Stable | v0.3.0 | Push/pop focus, persist across restart |
| Semantic retrieval (embeddings) | Stable | v0.3.0 | In-image vector lookup, 0 LLM tokens |
| TUI gate trace + focus map | Planned | v0.4.0 | Visual safety trace + what the agent is looking at |
| Emacs bridge | Planned | v0.4.0 | Native Emacs client over the wire protocol |
| Self-build safety boundary | Planned | v0.4.0 | Core files path-protected, Flight Plan required |
| Discord + Slack gateways | Planned | v0.4.0 | Messaging alongside Telegram and Signal |
| Token economics + cost tracking | Planned | v0.5.0 | Per-session cost counter, prompt caching, budget enforcement |
| Priority-queue signal processing | Planned | v0.6.0 | Preempts background for user interactions |
| MVCC memory concurrency | Planned | v0.6.1 | Concurrent reads/writes on Merkle tree |
| Structured output enforcement | Planned | v0.6.2 | Plist validation with retry and feedback |
| Streaming responses | Planned | v0.6.3 | Live output in TUI, interrupt-and-redirect |
| MCP-native tool ecosystem | Planned | v0.7.0 | 50+ tools from the MCP ecosystem |
| Voice gateway | Planned | v0.7.3 | Speech-to-text + text-to-speech via Whisper / ElevenLabs |
| Task planning (tree DAG) | Planned | v0.8.0 | Org headline task trees, branch pruning |
| Skill creator | Planned | v0.8.0 | LLM drafts skills from natural language, verified before load |
| Computer use / vision | Planned | v0.9.0 | Screenshot capture, UI interaction |
| SWE-bench evaluation harness | Planned | v0.9.0 | Automated benchmark scoring with Org trajectory audit |
| Consensus loop (multi-provider) | Planned | v0.10.0 | Parallel inference, disagreement detection |
| GTD integration | Planned | v0.10.0 | Full capture-clarify-organize-reflect-engage |
| Deep Emacs integration | Planned | v0.10.0 | Org-agenda, clock time, refile, archive |
Quick Start
After installation, the passepartout command is available from anywhere.
passepartout tui # launch the terminal interface
passepartout daemon # start the background daemon (for TUI/CLI/gateways)
passepartout doctor # run system health checkSee User Manual for the full guide.
Project Documentation
| Document | Answers |
|---|---|
| User Manual | How do I use it? |
| Architecture | How does it work inside? |
| Design Decisions | Why was it built this way? |
| Roadmap | Where is it going? When? |
| Contributing | How do I contribute? |
License
Passepartout is released under the AGPLv3 license. See CLA.org for the Contributor License Agreement.