amr/passepartout
1
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

chore: add v0.2.1 changelog, fix README purpose, remove duplicate USER_MANUAL

Browse Source
This commit is contained in:
Amr Gharbeia
2026-05-03 07:35:23 -04:00
parent d35aea391e
commit b6923d5584
4 changed files with 102 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
README.org
View File

@@ -1,110 +1,66 @@
#+TITLE: Passepartout: Your Autonomous, Plain-Text Life Assistant
#+TITLE: Passepartout — Your Autonomous, Plain-Text Life Assistant
#+AUTHOR: Amr
#+FILETAGS: :passepartout:ai:assistant:
#+HTML: <div style="display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 1em;">
#+HTML: <img src="https://img.shields.io/github/v/tag/amrgharbeia/passepartout?label=version&style=flat-square">
#+HTML: <img src="https://img.shields.io/github/license/amrgharbeia/passepartout?style=flat-square">
#+HTML: <img src="https://img.shields.io/github/v/tag/amrgharbeia/opencortex?label=version&style=flat-square">
#+HTML: <img src="https://img.shields.io/github/license/amrgharbeia/opencortex?style=flat-square">
#+HTML: <img src="https://img.shields.io/badge/Lisp-Common%20Lisp-blue?style=flat-square">
#+HTML: <img src="https://img.shields.io/badge/docs-Org--mode-green?style=flat-square">
#+HTML: </div>
* Quick Install
Passepartout is an AI assistant that runs in your terminal, reads and writes your Org-mode files, executes tasks through a verified safety gate, and works fully offline with local LLMs. Everything it knows is a folder of plain text files that you own.
**One-line install:**
#+begin_src bash
curl -fsSL https://raw.githubusercontent.com/amrgharbeia/opencortex/main/passepartout | bash -s configure
#+end_src
Then run ~passepartout tui~ to start chatting.
* Meet Passepartout
Most AI assistants are just chatbots. You ask a question, they answer, they forget you exist. They trap your conversations in proprietary web apps and silo your data.
*Passepartout is different. It is an AI that lives inside your own text files.*
It runs locally on your machine. It reads your notes, organizes your life, executes tasks, and gardens your knowledge base—all while keeping your data in plain text files you own completely.
* Why Passepartout Exists
The current generation of AI agents have a fundamental flaw: they prioritize quick demos over long-term reliability and user sovereignty.
The biggest problem is data ownership. Most agents bury your memories in opaque databases. If you want to see your own data, you have to ask the AI to fetch it. If the app shuts down, your data is gone.
Passepartout solves this with total plain-text transparency. Your entire life is a folder of text files. Passepartout manages them the same way you do—with any text editor. No database to migrate, no schema to update, no lock-in.
* What Makes Passepartout Different
Most AI agents are Python applications that happened to call an LLM. Passepartout is different. It is built in pure Common Lisp—top to bottom, no wrapper, no translation layer.
The kernel is Lisp. The skills are Lisp. The memory system is Lisp. The TUI is Lisp. One language from the hardware to the agent's thoughts.
Python agents need a second language for configuration (YAML), a third for memory (JSON or SQLite), and a fourth for deployment (Docker). Passepartout needs SBCL. That's it.
This is not nostalgia for the 1980s. Lisp has two properties that matter for an autonomous agent.
First, code is data. In Lisp, the agent can read its own code the same way it reads a text file. It can parse its skills, understand their structure, and modify them at runtime. Python's AST is a foreign object—the agent can inspect it, but not treat it as something it owns.
Second, stability. The Common Lisp specification has been stable for decades. Your code does not break because a library changed its API. Dependencies do not rot. A Lisp program from 1995 still runs today.
Your data lives in Org-mode files. Not a database. Not JSON. Not a vector store. Just plain text that you can read in any editor, search with grep, and back up any way you want.
This matters because every other agent makes your data dependent on their app. Their database schema defines what you can store. Their migration scripts decide whether your data survives an upgrade. Passepartout has no schema. Your memory is a folder of text files. It survives app updates, platform switches, and decades of use.
The agent fixes itself. When it encounters an error, it can modify its own code, apply surgical fixes, and learn from the outcome to improve and grow. Skills hot-reload at runtime, so you can extend the system without restarting. And if something goes wrong during a complex operation, it snaps back to a known-good state.
* Three Problems Every Agent Ignores
Every other AI assistant has three fundamental flaws that Passepartout addresses.
The first is the data silo. Most agents bury your memories in opaque databases. If you want to see your own data, you have to ask the AI to fetch it. If the app shuts down, your data is gone. Passepartout stores everything in plain text files that you own. No migration needed, no schema to update, no lock-in.
The second is the hallucination problem. Most agents pipe AI-generated text directly into your terminal. If the model hallucinates, it can delete your files or break your system. Passepartout splits its brain into two parts. The creative brain (the LLM) suggests actions. The strict guard (deterministic logic) intercepts every proposal before it touches a file or runs a command. If the AI hallucinates, the guard blocks it.
The third is cloud dependency. Most assistants rely entirely on big tech APIs. When your internet drops, or the service goes down, your assistant dies. Worse, your private notes are constantly sent to third-party servers. Passepartout runs on your own hardware using free, open-source models. Your private data never leaves your laptop. Cloud models are optional—used only when you explicitly allow them for complex tasks.
Then ~passepartout tui~ to start chatting.
* Quick Start
You need SBCL (Steel Bank Common Lisp) installed.
You need SBCL (Common Lisp), git, and curl.
#+begin_src bash
# Clone the repository
git clone https://github.com/amrgharbeia/opencortex.git ~/projects/passepartout
# Run the Setup Wizard
cd ~/projects/passepartout
./passepartout configure
# Verify System Health
passepartout doctor
# Enter the Brain
passepartout tui
./passepartout configure # install deps, tangle, setup wizard
passepartout tui # launch the terminal interface
#+end_src
* The Onboarding Trifecta
See [[file:docs/USER_MANUAL.org][User Manual]] for the full guide.
`passepartout setup` guides you through configuring LLM providers. Tell it how to talk to Ollama, Groq, OpenRouter, or your own endpoint.
* Why Passepartout
`passepartout gateway link <platform> <token>` connects external chat gateways. Talk to your agent from Telegram while it works on your files.
** Your data stays yours.** No database, no vector store, no cloud silo. Your entire memory is a folder of Org files. You can read them with any text editor, search them with grep, and back them up however you like. If Passepartout stops existing, your data doesn't disappear.
`passepartout doctor` shows you what's working, what's broken, and what needs attention.
** The LLM can't do damage.** Every action the LLM proposes passes through a deterministic safety gate before it touches a file, runs a command, or sends a message. The LLM suggests; the gate decides. Hallucinations are blocked, not corrected after the fact.
** Runs on your hardware.** Works fully offline with Ollama and local models. Cloud providers (OpenRouter, OpenAI, Anthropic, Groq, Gemini, DeepSeek, NVIDIA NIM) are optional add-ons.
** Written in Common Lisp.** Code is data. The agent reads its own source the same way it reads a text file — it parses, modifies, and hot-reloads its skills without restarting. One language from the kernel to the TUI to the build system.
* Architecture
Passepartout has three layers.
The Harness is the kernel. It runs the [[file:harness/loop.org][metabolic loop]]—Perceive → Reason → Act—each signal moving through normalization, LLM reasoning, skill verification, and action execution. Depth limits prevent infinite loops. The [[file:harness/memory.org][memory system]] persists to plain-text Org-mode files with snapshot and rollback on errors.
The Skills are userland—thin harness, fat skills. Modular skills load at runtime. Diagnostics, Configuration, LLM Gateway, Shell Actuation, Emacs Editing, Self-Edit, Self-Fix, Credentials Vault, Tool Permissions, Protocol Validator, and more. Each is an independent Org-mode module. Add new skills without touching the kernel.
The Interface is what you use to talk to the agent. A native Lisp [[file:harness/tui-client.org][TUI]] with semantic highlighting and history. A [[file:harness/communication.org][TCP socket server]] for CLI interaction. External channels via the gateway—Telegram and beyond.
- [[file:org/core-loop.org][Metabolic Loop]] — Perceive → Reason → Act, the fundamental cognitive cycle
- [[file:org/security-dispatcher.org][Dispatcher]] — 9-vector safety gate: secret scanning, path protection, shell safety, lisp validation, network exfiltration, privacy filtering
- [[file:org/core-memory.org][Memory]] — Single-address-space object store with Merkle-tree integrity and snapshot rollback
- [[file:org/core-skills.org][Skill Engine]] — 20 hot-reloadable skills loaded at boot, each an independent Org file
- [[file:org/gateway-tui.org][TUI]] — Croatoan-based terminal interface connected via framed TCP protocol
- [[file:org/gateway-llm.org][LLM Routing]] — Cascade dispatch through multiple providers with tier-based model selection
* Project Documentation
Passepartout practices what it preaches—the documentation lives in the code.
The [[file:USER_MANUAL.org][User Manual]] covers setup, configuration, and commands. The [[file:docs/ROADMAP.org][Evolutionary Roadmap]] shows our plan for reaching state-of-the-art capabilities. The [[file:docs/CONTRIBUTING.org][Contributing]] guide teaches you how to add new skills.
| Document | What it answers |
|----------|----------------|
| [[file:docs/USER_MANUAL.org][User Manual]] | How do I use it? |
| [[file:docs/ROADMAP.org][Roadmap]] | Where is it going? |
| [[file:docs/DESIGN_DECISIONS.org][Design Decisions]] | Why is it built this way? |
| [[file:docs/CONTRIBUTING.org][Contributing]] | How do I add a skill? |
| [[file:TODO.org][TODO]] | What is being worked on? |
| [[file:docs/CHANGELOG.org][Changelog]] | What changed between versions? |
* License

39
TODO.org
View File

@@ -223,10 +223,41 @@ The Dispatcher's role has evolved beyond security guard. It is the seed of the d
- Implement lazy-loading: edits mark nodes as =:vector :pending=
- Background worker thread batches pending nodes and updates Merkle tree silently
** TODO 6. Slash Commands (TUI ergonomics)
*** TODO M-x style command palette
*** TODO /- prefix for command mode
*** TODO Commands defined in Org-mode
** TODO 6. TUI Experience (Daily Driver Quality)
Architectural note: The TUI is a standalone Croatoan app in ~org/gateway-tui.org~.
None of these changes require daemon modifications — the protocol between TUI and
daemon (port 9105, framed plists) is stable. A tmux session provides a virtual
terminal for REPL-based TUI testing: ~tmux send-keys~ / ~tmux capture-pane~.
*** TODO P0: Chat scrollback (Page Up/Down)
Track rendered history beyond the window height; Page Up/Down scrolls through it. ~2h.
*** TODO P0: Input history (up/down arrows)
Maintain a ring buffer of sent messages; up arrow recalls previous, down advances. ~1h.
*** TODO P1: Status bar (bottom line)
Shows daemon connection status, active LLM model, current time. Separator line
between input area and status. ~3h.
*** TODO P1: Message rendering
Timestamps (HH:MM), styled prefixes (⬆ sent vs ⬇ received in different colors),
line wrapping for long messages. ~2h.
*** TODO P2: Command palette (/help redesign)
/help shows a scrollable popup overlay with categories: chat, system, skills, debug.
Absorbs the old /-prefix command mode item. ~4h.
*** TODO P2: Multi-line input (Shift+Enter for newline)
Detect Shift+Enter vs plain Enter; expand input window for long messages. ~3h.
*** TODO P3: Background activity indicator
Spinner or dots when the agent is processing; reads from daemon heartbeats. ~2h.
*** TODO P4: Tab completion for / commands
Tab after / completes command name. ~3h.
*** TODO P4: Configurable theme
Color scheme variables in the TUI package; basic /theme command. ~4h.
* PHASE: LONG-HORIZON PLANNING + GIT WORKFLOWS (v0.4.0)
:PROPERTIES:

61
USER_MANUAL.org
View File

@@ -1,61 +0,0 @@
#+TITLE: Passepartout User Manual
#+AUTHOR: Agent
#+STARTUP: content
#+FILETAGS: :docs:manual:
* Introduction
Welcome to the Passepartout User Manual. This guide provides the operational knowledge required to manage your sovereign Lisp Machine and its neural skills.
* System Architecture
Passepartout follows a "Purified Kernel" model. The core harness handles essential I/O, while all high-level logic resides in sovereign skills.
** XDG Directory Standard
To ensure POSIX compliance, Passepartout stores its files in standard Linux locations:
| Type | Path | Purpose |
| :--- | :--- | :--- |
| **Config** | `~/.config/passepartout/` | User settings, `.env` secrets, and provider registry. |
| **Data** | `~/.local/share/passepartout/` | Tangled Lisp artifacts and the compiled engine. |
| **State** | `~/.local/state/passepartout/` | Brain snapshots, logs, and Merkle-memory. |
| **Bin** | `~/.local/bin/passepartout` | The global CLI shim. |
* Command Reference
** `passepartout setup`
The interactive configuration wizard. Use this to:
- Define your identity and the Agent's name.
- Register LLM providers (Ollama, Groq, Anthropic, etc.).
- The wizard automatically splits sensitive tokens into `~/.config/passepartout/.env`.
** `passepartout gateway link <platform> <token>`
Connects Passepartout to external communication gateways.
- **Example:** `passepartout gateway link telegram <my_bot_token>`
- **Example:** `passepartout gateway unlink telegram` to disable
- **Example:** `passepartout gateway list` to see status
** `passepartout doctor`
Your primary diagnostic tool. Run this if the system feels sluggish or fails to boot. It verifies:
- External dependencies (sbcl, git, socat).
- XDG directory existence and permissions.
- LLM connectivity.
** `passepartout tui`
Launches the native Lisp Terminal User Interface.
- **Highlighting:** Semantic color-coding for Lisp and Org syntax.
- **Scrolling:** Use `PgUp`/`PgDn` to navigate history.
- **Exit:** Type `/exit` or `Ctrl+C` to close.
* Configuration Strategy
Passepartout uses a **Hybrid Storage** model for maximum security and flexibility.
** 1. Secrets (`.env`)
Found in `~/.config/passepartout/.env`. This file stores raw API tokens. It is never automatically read by the Lisp structural parser to prevent accidental leakage into logs.
** 2. Metadata (`providers.lisp`)
Found in `~/.config/passepartout/providers.lisp`. This stores non-sensitive configuration like model names, base URLs, and user preferences as native Lisp S-expressions.
* Troubleshooting
If `passepartout doctor` reports a `FAIL`:
1. Check that your `PATH` includes `/usr/bin` and `/usr/local/bin`.
2. Ensure `sbcl` is installed.
3. If LLM connectivity fails, verify your API key in `~/.config/passepartout/.env`.

35
docs/CHANGELOG.org
View File

@@ -1,6 +1,41 @@
#+TITLE: Changelog
#+STARTUP: content
* v0.2.1 — Rename, Safety, and Deployment (2026-05-02)
This release renames the project to Passepartout, adds content-level safety gates, professionalizes deployment, and documents every function with full explanatory prose.
** Project Rename
- **Passepartout:** Project renamed from OpenCortex to Passepartout. All files, packages, functions, and environment variables updated.
- **Org/lisp split:** Source of truth lives in ~org/~, tangled to ~lisp/~. Core files committed, skills generated at configure time.
- **31 org files:** Every file renamed to ~category-subject.org~ convention. Harness and skills unified under one directory.
** Safety
- **Secret Exposure Gate:** Content scanning for API keys, PEM blocks, PGP keys, credentials, and tokens in all outgoing text.
- **Path Protection:** File reads blocked for ~.env~, SSH keys, PEM/PGP, cloud configs, and credential stores.
- **Shell Safety:** Destructive commands (~rm -rf /~, ~dd~, ~mkfs~, ~shred~) and injection patterns (backtick, ~$()~) blocked with timeout and output limits.
- **Lisp Validation Gate:** Writes to ~.lisp~ and ~.org~ files validated for syntax errors before they reach disk.
- **REPL Verification Lint:** Warns if defuns are written without REPL prototyping.
** Deployment
- **Multi-distro:** Automatic detection of Debian vs Fedora, correct package names and managers.
- **systemd service:** User-level auto-start on boot via ~passepartout install service~.
- **Backup/Restore:** ~passepartout backup~ and ~passepartout restore~ commands.
- **Docker:** Updated to ~debian:trixie-slim~, fixed build context.
- **CI/CD:** GitHub Actions workflows for lint, test, and release. Gitea deploy workflow fixed.
** Engineering Process
- **REPL-first Lifecycle:** Two-track workflow: Org-first for prose and tests, REPL-first for implementation. Every function prototyped in the REPL before reaching Org.
- **Verification Loop:** Bouncer rejects bad lisp; rejection trace feeds back to LLM for self-correction.
- **System-prompt-augment:** Skills can inject domain-specific mandates into the LLM prompt via ~:system-prompt-augment~.
** Documentation
- **Literate Prose Restored:** Every Org file now has an Architectural Intent overview and explanatory prose before each function block, following the style established in the v0.1.0 era.
- **AGENTS.md:** Thinned to a routing layer — the skill org files are authoritative.
** Contributors
- **gitignore:** ~skills/*.lisp~ and ~tests/*.lisp~ as generated artifacts (source of truth is ~.org~).
- **DeepSeek and NVIDIA NIM:** Added as LLM providers (OpenAI-compatible). Use ~DEEPSEEK_API_KEY~ and ~NVIDIA_API_KEY~ env vars.
* v0.2.0 - Interactive Refinement (2026-04-29)
This release focuses on professionalizing the environment and enhancing the agent's structural capabilities.