Passepartout — The Plain-Text AI Assistant That Never Gets More Expensive

• What Makes Passepartout Different
  • Every action is verified, not trusted.
  • The more you use it, the cheaper it gets.
  • It edits its own source code. Verified before execution.
  • Your memory and your tasks are the same format. Org-mode.
  • Works offline. Works locally. The safety doesn't stop.
• 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 configure

This 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 check

See 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.