Boucle is a self-hosted chief-of-staff loop. It turns captures into tickets, runs recurring agent work, and keeps project and meeting context in a local Markdown brain.
The workflow is capture → tickets → loops → brain. SQLite stores tickets, conversations, schedules, and cost records. Markdown files remain the source of truth for project and meeting context.
| Capability | Implementation | Local state |
|---|---|---|
| Chat and tools | Selected OpenAI-compatible HTTP provider with a local tool relay | Conversations and messages in SQLite |
| Embeddings | Selected provider embedding endpoint with lexical fallback | Model-scoped vectors in SQLite |
| Transcription | Selected provider audio transcription endpoint | Audio is sent for transcription, then the text enters capture |
| Agent loops | Vibe, Codex, or Claude CLI with Boucle's MCP tools | Schedules, runner overrides, transcripts, and reported costs |
| Brain | Markdown project and meeting notes with hybrid search | Files under BOUCLE_BRAIN_DIR |
BOUCLE_PROVIDER |
Services | Chat and tools | Embeddings | Transcription |
|---|---|---|---|---|
mistral or unset |
Mistral | Yes | Yes | Yes |
openai |
OpenAI, Ollama, OpenRouter, vLLM, and compatible gateways | Yes | When the endpoint exists | When the endpoint exists |
Mistral is the default provider. Vibe is the default loop runner. Provider and runner selection are independent.
| Runner | Binary | Session cost |
|---|---|---|
vibe |
vibe |
Reported by Vibe |
codex |
codex |
n/a when the Codex session does not expose cost |
claude |
claude |
Reported by Claude's JSON result |
Use Node 23.6 or later (24 LTS recommended) and pnpm. The bundled demo needs one Mistral API key.
git clone https://github.com/lorisalx/boucle.git
cd boucle
cp .env.example .env
chmod 600 .envSet the key in .env:
MISTRAL_API_KEY=replace_with_your_keyInstall, build, and start Boucle:
pnpm install
pnpm --dir web install
pnpm --dir web build
node src/server.tsOpen http://localhost:4419.
Boucle is extensible without forking. An extension is a plain TypeScript module — a directory
with an index.ts that default-exports a manifest — loaded with dynamic import() at startup:
no build step, no bundler. It can add agent tools, HTTP routes, web pages, runners, providers,
and event handlers. Drop one in $BOUCLE_EXTENSIONS_DIR (default
$XDG_DATA_HOME/boucle/extensions) and restart; boucle ext list shows what loaded. Extensions
run in-process with full privileges, so only install ones you trust. See
Extensions and the bundled extensions/hello-world/ template.