Amr Gharbeia
7c84dbfacb
View-chat renders gate-trace-lines as colored dim lines below agent messages. Ctrl+G toggles collapse per message (stored in :collapsed-gates state field). Default: visible. /why shows last gate trace as system messages. Tab integration deferred (paren fragility in on-key cond default case). Ctrl+G is functionally equivalent for toggle UX. View: 29/29 TUI Main: 85/86
Passepartout — The Plain-Text AI Assistant That Never Gets More Expensive
- What is an AI Agent?
- 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 ten 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 is an AI Agent?
An AI agent is a program that can act on your behalf — reading files, running commands, sending messages — rather than just answering questions. Unlike a chatbot that only produces text, an agent has actuators that let it affect the world: a shell, a file editor, a message sender. See Software agent on Wikipedia.
Passepartout is a sovereign agent: it runs on your machine, operates on your plain-text files, and verifies every action through deterministic safety gates before execution.
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: ten 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, including a self-build safety boundary that prevents the agent from modifying its own core pipeline without human review. 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 (architectural aspiration)
Passepartout is designed with a downward cost curve — an architectural property, not yet measured empirically. Here is the thesis.
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. This rule-learning system is planned for v0.5.0.
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.
These mechanisms are implemented and working today. Token cost measurement and optimization are tracked in the v0.5.0 Roadmap. Until empirically verified, the cost claims in Design Decisions (2-3x fewer tokens for coding, 13-24x for knowledge management) should be read as architectural projections, not measured results.
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 ten 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 |
|---|---|---|---|
| 10-vector deterministic safety | Stable | v0.2.0 | Secrets, paths, self-build, shells, network, lisp, privacy, approval |
| 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 (trigram) | Stable | v0.4.0 | Trigram Jaccard — lexical overlap, 0 LLM tokens |
| TUI gate trace + focus map | Stable | v0.4.0 | Visual safety trace + what the agent is looking at |
| Emacs bridge | Stable | v0.4.0 | Native Emacs client over the wire protocol |
| Self-build safety boundary | Stable | v0.4.0 | Core files path-protected, HITL Flight Plan required |
| Expanded theme (25-color) | Stable | v0.4.0 | 4 named presets (dark/light/gruvbox/solarized), /theme command |
| Discord + Slack gateways | Stable | v0.4.0 | 4 platforms: Telegram, Signal, Discord, Slack |
| Native embedding inference | Beta | v0.4.x | CFFI llama.cpp binding, nomic-embed-text (768-dim) |
| Structured output (function-calling) | Stable | v0.4.2 | LLM tool use via native function-calling API, JSON→plist boundary |
| Shell sandbox (bwrap) | Stable | v0.4.3 | Bubblewrap namespace isolation, network/IPC lockdown |
| Shell severity classification | Stable | v0.4.3 | catastrophic→dangerous→moderate→harmless tier system |
| Token economics + cost tracking | Stable | v0.5.0 | Per-session cost counter, prompt caching, budget enforcement |
| Time awareness | Stable | v0.6.0 | Symbolic-time-memory + sensor-time skills, ISO timestamps in prompts |
| TUI readline/Ctrl bindings | Stable | v0.7.0 | Ctrl+U/W/A/E/L/D, Ctrl+X+E editor, Ctrl+C interrupt cascade |
| TUI Unicode width | Stable | v0.7.0 | char-width: ASCII/CJK/emoji/combining marks, pure Lisp |
| TUI scroll notification | Stable | v0.7.0 | :scroll-notify flag, new-message alert when scrolled up |
| TUI deeper autocomplete | Stable | v0.7.0 | @ file paths, /theme subcommand, /focus directories |
| Streaming responses | Stable | v0.7.2 | SSE streaming, live output in TUI, interrupt-and-redirect |
| TUI markdown rendering | Stable | v0.7.2 | Bold/italic/inline code styled via Croatoan attributes |
| Priority-queue signal processing | Planned | v0.7.2 | Preempts background for user interactions |
| Markdown rendering (full) | Planned | v0.7.2 | Code blocks, tables, blockquotes, hyperlinks |
| 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.