Persistent Coordination and Memory Layer for AI Coding Agents.

"Simple like Git. Persistent like Notion. Collaborative like Figma. AI-Native like Cursor."

🖥️ Live Orchestration Dashboard	👤 Active Session Topology & Status
⚡ Concurrency Mutation Conflicts	🤝 Handoff Quality Scorecard & Coaching

• Butler in 3 Minutes
• Quickstart
• System Architecture
• The Killer Demo
• Core Terminology
• API & Tool Surface
  • Resources
  • Session Management
  • Task Management
  • Multi-Agent Coordination
  • Knowledge & Memory
  • Observability
• Developer CLI
• Butler Workflow Skill
• Zero-Intervention Automation
• Workflows, Best Practices & Troubleshooting
• Context Freshness & Staleness
• Multi-Agent Conflict Detection
• Schema Migration
• Multi-Agent Orchestration & LangGraph Integration
• Repository Anatomy
• Principles
• Related Projects

Butler is a lightweight, local-first background coordination engine that registers active AI agents (e.g. Claude Desktop, Cursor, custom IDE tools) and maintains a shared, event-sourced memory space directly inside your project repository.

Butler features native LangGraph integration, providing a built-in SQLite checkpointer to save/restore multi-agent conversation threads and coordinate workflow graphs directly in the project database.

Coding agents are fundamentally amnesiac. When Cursor reloads or a process exits, active context (TODOs, architectural constraints, session differences) is completely lost. When multiple agents run concurrently, they operate in silos, generating race conditions and divergent branches. Butler bridges this gap.

• AI Pair Programmers: Developers working interchangeably across multiple LLM clients (e.g., planning in Claude, implementing in Cursor).
• Multi-Agent Workspaces: Teams running concurrent background AI workers on the same repository.
• Local-First Advocates: Engineers seeking zero network leakages and absolute privacy.

The fastest way to install and configure Butler is via npx:

npx butler-mcp install   # Scans and auto-configures all active clients (Claude, Cursor, VS Code, Zed, Windsurf, etc.)
npx butler-mcp status    # Runs the visual status CLI
npx butler-mcp dashboard # Runs the web dashboard

git clone https://github.com/Teycir/Butler.git
cd Butler

Linux / macOS:

bash install/install.sh

Windows (PowerShell):

.\install\install.ps1

The installer will:

• Build Butler from source.
• Deploy the production bundle to ~/Mcp/butler-mcp/.
• Automatically scan the host machine for active coding clients.
• Inject the Butler MCP configuration into all detected clients (supporting Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Gemini CLI, Kiro CLI, and Kilo Code).
• JSONC / Comment Safe: Safely parses configurations with comments and trailing commas without overwriting custom settings.

Custom DB path: Pass --db-path to use a custom SQLite file location: bash install/install.sh --db-path /your/path/butler.db Or on Windows: .\install\install.ps1 -DbPath "C:\your\path\butler.db"

npm install
npm run build

Then add Butler to your AI client's MCP config manually:

{
  "mcpServers": {
    "butler": {
      "command": "node",
      "args": ["/absolute/path/to/Butler/dist/index.js"],
      "env": {
        "BUTLER_DB_PATH": "/absolute/path/to/butler.db"
      }
    }
  }
}

Config file locations:

• Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json
• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• VS Code / Cursor: mcp.json in your user settings directory
• Kiro CLI: ~/.config/kiro-cli/mcp.json
• Kilo Code: ~/.config/Antigravity/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json

Example: Kiro CLI configuration (~/.config/kiro-cli/mcp.json)

{
  "mcpServers": {
    "butler": {
      "command": "/home/user/.nvm/versions/node/v20.20.0/bin/node",
      "args": [
        "/home/user/Mcp/butler-mcp/dist/index.js"
      ],
      "env": {
        "BUTLER_DB_PATH": "/home/user/.butler/butler.db"
      }
    }
  }
}

Restart your AI clients and Butler is ready.

Coding agents today are incredibly powerful but fundamentally amnesiac. When your Cursor window reloads or Claude Desktop restarts, your active context, developer constraints, completed tasks, and architectural decisions are erased.

Even worse, when multiple agents work on the same codebase simultaneously, they operate in completely disjoint silos, causing race conditions, diverging implementations, and broken handoffs.

Butler bridges this gap by acting as a local, background Durable Project Memory Log:

               🤖 Agent A (Claude)        🤖 Agent B (Cursor)
                       \                      /
                        \                    /
                 [ Model Context Protocol stdio transport ]
                                    ↓
                       ===========================
                       │         BUTLER          │
                       │  Durable Shared Memory  │
                       ===========================
                       /      │           │      \
                     /        │           │        \
                    ▼         ▼           ▼         ▼
                🎯 TODOs   📜 Rules   💡 Decisions  📚 Wiki

To understand Butler in under two minutes, here are our core conceptual models:

• Project: The permanent codebase workspace. Lives forever, anchored by a local-first SQLite file (.butler/butler.db).
• Session: An ephemeral window of activity by a specific AI client (e.g. cursor-1, claude-desktop-2). Sessions send periodic heartbeats to prove presence.
• Event: An append-only, immutable transaction log entry representing a discrete state change (e.g. TODO_CREATED, RULE_ADDED, WIKI_UPDATED). Events are the ground truth.
• State: A materialized cache of the project's current status (active tasks, wiki pages, rules) constructed incrementally by playing events. State is the cache.
• Handoff: A structured, context-rich handoff payload generated when a session disconnects, capturing exact achievements and pending blockers.
• Memory: Highly searchable semantic guidelines, observations, and design logs indexed locally using light, zero-click Term Frequency-Inverse Document Frequency (TF-IDF) sparse relevance algorithms.

Butler is designed to be operationally invisible and incredibly fast. It operates on an event-sourced, materialized-view model backed by SQLite in Write-Ahead Log (WAL) mode.

graph TD
    subgraph AI_Clients["AI Clients"]
        C1[🤖 Claude Desktop]
        C2[🤖 Cursor Editor]
        C3[🤖 Kiro / Kilo / VSCode]
    end

    subgraph Dev_Tools["Developer Tools (local, no MCP)"]
        CLI[🖥️ cli/status.ts · cli/tui.ts<br/>npm run status · npm run tui]
        DASH[📊 cli/dashboard.ts<br/>npm run dashboard → :7888 SSE]
    end

    subgraph MCP_Layer["Transport Layer"]
        MCP[🔌 mcp/server.ts<br/>MCP stdio · JSON-RPC]
    end

    subgraph Tools["mcp/tools/"]
        T_SES[session.tools.ts<br/>register · heartbeat · disconnect]
        T_TODO[todo.tools.ts<br/>add · complete · update · delete · list]
        T_KNOW[knowledge.tools.ts<br/>wiki · rule · decision · handoff]
        T_MEM[memory.tools.ts<br/>store · search · delete · projectlist]
        T_COORD[coordination.tools.ts<br/>claim · unclaim · message · broadcast · synccontext]
        T_OBS[observability.tools.ts<br/>eventsexport · butlerping]
    end

    subgraph Resources["mcp/resources.ts · mcp/resources/"]
        R_CTX[context · todos · wiki<br/>sessions · memories · diff · orchestration]
    end

    subgraph Coordinator["src/coordinator/"]
        LIFE[lifecycle.ts<br/>session CRUD · heartbeat monitor<br/>stale/dead detection · ensureSession]
        HAND[handoff.ts<br/>generateStructuredHandoff<br/>computeHandoffQualityScore]
        DIFF[diff.ts<br/>getProjectDiff<br/>getContextStaleness]
        SES[session.ts<br/>SessionRecord · low-level read helpers]
    end

    subgraph Events["src/events/"]
        STORE[store.ts<br/>appendEvent · getEvents<br/>createSnapshot · getLatestSnapshot]
        MAT[materializer.ts<br/>materializeProject · in-memory ProjectState cache]
        PROJ[projections.ts<br/>projectEvent · per-event state transitions]
        TYPES[types.ts<br/>EventRecord · event type definitions]
    end

    subgraph Vector["src/vector/"]
        VEC[index.ts<br/>Pure-JS TF-IDF<br/>addMemory · searchMemories · deleteMemory]
        SIM[similarity.ts<br/>cosine similarity · token scoring]
    end

    subgraph DB_Layer["src/db/"]
        SCHEMA[schema.ts<br/>INIT_SCHEMA_SQL<br/>VERSIONED_MIGRATIONS v1–v8]
        DATABASE[database.ts<br/>initDatabase · getDb · closeDatabase]
    end

    subgraph Storage["SQLite WAL  .butler/butler.db"]
        T1[(projects)]
        T2[(sessions)]
        T3[(events)]
        T4[(sequences)]
        T5[(snapshots)]
        T6[(memories)]
        T7[(butler_migrations)]
        T8[(checkpoints)]
        T9[(writes)]
    end

    C1 & C2 & C3 -->|JSON-RPC stdio| MCP
    MCP --> T_SES & T_TODO & T_KNOW & T_MEM & T_COORD & T_OBS
    MCP --> R_CTX
    T_SES & T_TODO & T_KNOW & T_MEM & T_COORD --> LIFE
    T_SES --> HAND
    T_KNOW --> HAND
    R_CTX --> MAT & LIFE & DIFF & VEC
    LIFE --> STORE & HAND & DIFF
    LIFE --> SES
    HAND --> SES
    STORE --> DATABASE
    MAT --> STORE & PROJ & TYPES
    PROJ --> TYPES
    VEC --> SIM
    VEC --> DATABASE
    DATABASE --> SCHEMA
    DATABASE --> T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8 & T9
    CLI --> DATABASE
    DASH --> DATABASE

Imagine this workflow:

1. Start in Cursor: You ask Cursor to plan a database migration. Cursor registers a session, creates 3 TODOs, and records a design decision (ADR-001).
2. Cursor Window Reloads / Crashes: The Cursor session terminates. Butler detects the disconnection, automatically materializes a structured handoff marker, and updates the event log.
3. Resume in Claude Desktop: You open Claude Desktop. Claude registers its session.
4. Instant Rehydration: Claude reads the butler://projects/{id}/context resource. It instantly receives:
   • The structured handoff summarizing Cursor's accomplishments.
   • The exact pending TODO list.
   • The active project rules and architectural constraints. Claude immediately resumes work with zero lost context.

git clone https://github.com/Teycir/Butler.git
cd Butler

Linux / macOS:

bash install/install.sh

Windows (PowerShell):

.\install\install.ps1

The installer builds Butler, deploys the release to ~/Mcp/butler-mcp/, and auto-configures detected clients (including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Gemini CLI, Kiro CLI, and Kilo Code) safely. Restart your AI clients and Butler is ready.

Custom DB path: Pass --db-path to specify a custom database location: bash install/install.sh --db-path /your/path/butler.db Or on Windows: .\install\install.ps1 -DbPath "C:\your\path\butler.db"

Open your AI client (Claude Desktop, Cursor, etc.) and ask:

"Can you call the butlerping tool?"

Expected response:

{
  "status": "ok",
  "db_path": "/home/user/.butler/butler.db",
  "db_size_kb": 142,
  "schema_version": 8,
  "project_count": 3,
  "uptime_seconds": 3621
}

Drop a .butler/project.json in your repo root to set a default project for all tool calls:

{ "project_id": "my-project" }

Butler walks up the directory tree to find this file automatically. Once set, every tool call in that workspace resolves project_id without you passing it explicitly.

npm test

Butler ships with a local command line interface (CLI) to configure, manage, and monitor your multi-agent workspaces — no MCP server connection required to run diagnostics or status checks.

Deploys the Butler production bundle to ~/Mcp/butler-mcp and automatically injects the Butler MCP server configuration into your local AI client configuration files. If no clients are explicitly registered, it scans your system to auto-detect and register active clients. It supports comments (JSONC) and trailing commas safely.

$ butler install
🔨 Building from source...
🚀 Syncing to /home/user/Mcp/butler-mcp...

🔧 Injecting Butler into registered AI clients...
  ✅ /home/user/.config/Claude/claude_desktop_config.json
  ✅ /home/user/.config/Cursor/User/mcp.json
  ✅ /home/user/.config/zed/settings.json
  ...

🎉 Done! Restart your AI clients to activate Butler.

──────────────────────────────────────────────────────────────────
📋  SYSTEM PROMPT SNIPPET — paste this into your AI client once:
──────────────────────────────────────────────────────────────────

On startup: call projectlist, then sessionregister (project_id from .butler/project.json or ask the user, session_id = "<client>-<4 random chars>", client_type = your tool name). Heartbeat every 15 seconds. Before exit: call handoffcreate with a summary of what you did, then sessiondisconnect.

🧪 Verifying setup...
Open any registered client and ask: 'Can you call the butlerping tool?'
Expected response: status: ok, schema_version: 8

Interactively initializes a new project configuration inside your local workspace. This creates .butler/project.json and adds it to your .gitignore so your agents can automatically identify the correct project database namespace.

$ butler init
🌐 Butler — Project Setup

? Project ID [default: my-project]: my-project
? Project name (optional): My Project Workspace
? Default client [default: Claude Desktop]: Claude Desktop

✅ Created .butler/project.json
✅ Added .butler/ to .gitignore
✅ Ready! Open your AI client and start coding.

Reads the global SQLite database (~/.butler/butler.db) directly and outputs a comprehensive diagnostic summary of the workspace's projects, sessions, active/completed tasks, and recent handoffs.

$ butler status
🤵  Butler Status   15/06/2026 20:08:12
    Database: /home/user/.butler/butler.db
    Projects: 4

╔═══════════════════════════════════╗
║  🌐 Butler — Butler               ║
║  🔴 INACTIVE  |  0 live sessions  ║
╚═══════════════════════════════════╝

SESSIONS
  No active sessions
  ⚫  1 dead session(s) hidden

TODOS (0 open, 0 completed)
  No open TODOs

🤝  RECENT HANDOFFS (last 3)
  [system]  claude-r4x  (127h ago)
          "Session claude-r4x lost connection (missed heartbeat). Auto-generated c…"
  [system]  claude-r4x  (127h ago)
          "Session claude-r4x lost connection (missed heartbeat). Auto-generated c…"

HANDOFF QUALITY SCORE  █████░░░░░  49% (last: claude-r4x)

Event log: 19 events | last: 127h ago
Snapshot:  no snapshot yet

Supports --project <id>, --db <path>, --json, and --help flags.

Launches a live split-screen Terminal User Interface (TUI) that refreshes every 2 seconds, displaying real-time agent presence, broadcast events, active tasks, version conflicts, and handoff quality metrics.

┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 🤵 BUTLER ORCHESTRATOR │ Project: api-hunter                                     ● 20:13:57 │
│ DB: ~/.butler/butler.db (128 KB)                │ Schema: v8 │ Projects: 4 │ Status: 🟢 HEALTHY  │
├────────────────────────────────────────────────┬─────────────────────────────────────────────────┤
│ 👤 Topology Sessions (2)                       │ 🎯 Shared Task Space (3 open)                    │
│   ● cursor-main-1    cursor       12s ago      │   Progress: [██████░░░░░░░░░░] 37% (6/16 done)   │
│   ○ claude-desk-2    claude       45s ago      │   ■ HGH [#1] Implement JWT signat… │ 🔒 cursor-m… │
│                                                │   ■ MED [#2] Add OAuth tests       │ unclaimed    │
│ 📢 Broadcast Stream (2)                        │   ■ LOW [#3] Verify README typos   │ unclaimed    │
│   10s ago [cursor-m]: refactored auth.ts       │                                                  │
│   45s ago [claude-d]: pulling main branch      │ ⚡ Mutation Conflicts (1)                         │
│                                                │   ⚠️  Task #1 │ concurrent_update │ 8s ago    │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 🤝 RECENT WORKSPACE HANDOFFS                                                                      │
│   [agent] cursor-main-1 (10m ago) - "Refactored JWT signature checking and fixed algorithm bypass."│
│   [system] claude-desk-2 (25m ago) - "Session claude-desk-2 disconnected gracefully."            │
│   Quality Rating: [███████████░░░░] 73% (latest: cursor-main-1) │ Words: 24 │ Struct: ✓ │ Verbs: ✓│
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Events: 142 │ Last Event: TODO_COMPLETED (12s ago)        [Q] Quit │ [R] Refresh │ Auto-Refresh: 2s  │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘

Interactive controls: Press q to quit, r to force a manual refresh.

Starts a local read-only web dashboard with SSE (Server-Sent Events) live pushing every 5 seconds to show active sessions, TODOs, conflict lists, and event trails.

$ butler dashboard
🌐 Serving Butler dashboard at http://localhost:7888

Supports --port <n>, --host <addr>, and --db <path> flags.

Outputs structured database size and schema metrics as JSON. Perfect for piping to jq or integrating into external status monitoring tools.

{
  "status": "ok",
  "db_path": "/home/user/.butler/butler.db",
  "db_size_kb": 128,
  "schema_version": 8,
  "project_count": 4
}

Runs environmental diagnostics to ensure Node.js compatibility, built output validity, database state, and client MCP configurations are set up correctly.

$ butler doctor
🩺 Butler Doctor Diagnostics

✅ Node.js v20.20.0 — OK
✅ Butler build — OK (dist/index.js exists)
✅ Database — OK (/home/user/.butler/butler.db, schema v8)
✅ Claude Desktop config — OK (butler entry found)
⚠️  Cursor config — NOT FOUND (missing file)
✅ Kiro CLI config — OK (butler entry found)
✅ VS Code config — OK (butler entry found)
✅ Kilo Code config — OK (butler entry found)

Fix: Run `butler install` to repair configuration files.

Butler includes a portable skill package that teaches AI agents how to use Butler's coordination features effectively. The skill is available in skills/butler-workflow/.

For Kiro CLI / Kilo Code / Claude Code:

cp -r skills/butler-workflow ~/.kiro/skills/
# or
cp -r skills/butler-workflow ~/.agents/skills/

For other agents: Copy the skill to your agent's skill directory and it will be auto-loaded on startup.

The butler-workflow skill provides comprehensive patterns for:

• Session Lifecycle: Register → heartbeat → handoff → disconnect
• TODO Workflow: Create → claim → work → complete with conflict prevention
• Memory Management: Store decisions, search context, clean up stale data
• Multi-Agent Coordination: Messages, broadcasts, conflict detection
• Best Practices: When to register, how to handoff, what to persist

Once installed, agents automatically learn Butler patterns. The skill teaches agents to:

1. Register sessions at startup with unique session IDs
2. Send heartbeats every 15-30 seconds during active work
3. Claim TODOs before starting to prevent conflicts
4. Store important decisions with appropriate importance scores
5. Create quality handoffs when switching contexts
6. Coordinate with other active sessions via messages

See skills/butler-workflow/SKILL.md for full documentation and examples.

Butler is designed to run completely in the background. All you need to do is install the MCP server and copy the skill package to your agent folder. Butler handles the rest automatically.

When you open any directory to work:

1. Butler automatically configures the project by creating .butler/project.json (derived from the directory name).
2. The agent automatically joins and heartbeats in the background.
3. The agent automatically records context and leaves a handoff on exit.

You do not need to run any initialization commands or setup scripts. It just works.

To make onboarding effortless, Butler automatically handles project configuration:

• Automatic Setup: If a connecting agent runs inside a workspace that does not contain a .butler/project.json file, Butler will automatically:
  1. Create the .butler/ directory.
  2. Normalize the current working directory's folder name to generate a clean, kebab-case project_id (e.g. some-cool-project).
  3. Write a default project.json containing that ID.
• Manual Override: You can change or override the default ID at any time by editing the "project_id" field in .butler/project.json.
• Result: Zero configuration or manual creation steps are required when opening new directories.

Deploy the butler-workflow skill package to your agent's skill directory:

# For Agy / Claude Code / Antigravity
cp -r skills/butler-workflow ~/.agents/skills/

# For OpenCode
cp -r skills/butler-workflow ~/.config/opencode/skill/

# For Kiro CLI / Kilo Code
cp -r skills/butler-workflow ~/.kiro/skills/

• Result: Connecting agents load this skill on startup and execute the session lifecycle autonomously:
  • Registers the session on startup.
  • Starts a silent background timer emitting heartbeats every 15s.
  • Automatically fetches context and reads tasks.
  • Generates a structured handoff and disconnects gracefully on exit.

If using standard LLM clients (Claude Desktop, Cursor, VS Code, ChatGPT) without a skill loader, append this directive to your agent's global System Prompt instructions:

On startup, call projectlist or check .butler/project.json to find the active project. Call sessionregister (generate a unique session_id). Fetch butler://projects/{id}/context to catch up. Send heartbeats every 15 seconds. Before exit, run handoffcreate and call sessiondisconnect.

If an agent crashes or the terminal is closed abruptly, Butler automatically self-heals:

• The background lifecycle monitor sweeps active heartbeats every 15 seconds.
• If a session misses heartbeats for 60 seconds, it is marked stale.
• After 5 minutes, it is marked dead, its task claims/locks are automatically released for other sessions, and an ungraceful continuity handoff is synthesized to record what was left behind.

Every /context read opens with a freshness badge:

• 🟢 — at least one session is alive and actively heartbeating
• 🔴 — no live sessions; context was last updated some time ago

The raw JSON payload (second content block on /context) also includes a staleness object:

{
  "last_live_heartbeat": 1716900000,
  "has_live_session": false,
  "events_since_last_read": 12,
  "context_age_seconds": 720
}

Agents reconnecting after a gap can use last_event_id + the /diff resource to fetch only what changed, rather than re-reading the full context.

When two sessions complete or update the same TODO within a 10-second window, Butler appends a TODO_CONFLICT event alongside the mutation. These conflicts surface in the /context resource under ⚡ Recent Coordination Conflicts, letting all agents see where parallel writes collided and coordinate resolution.

Butler uses a versioned migration runner backed by a butler_migrations tracking table. Each migration:

• Runs inside a transaction — failure rolls back cleanly
• Is idempotent — applied exactly once, never re-run
• Records version number, description, and applied_at timestamp

The VERSIONED_MIGRATIONS array in schema.ts is the single source of truth. Pre-existing databases are automatically brought up to date on startup.

Butler features first-class integration with LangGraph to support complex, multi-step agent orchestration workflows (such as Planning ➔ Implementing ➔ Verifying ➔ Committing).

Butler provides a custom LangGraph checkpointer (getLangGraphCheckpointer()) that utilizes your existing better-sqlite3 database to save and restore agent checkpoint states and conversation threads. This avoids the need to maintain a separate SQLite checkpointer file for LangGraph.

To fetch the checkpointer instance:

import { getLangGraphCheckpointer } from './dist/langgraph/checkpointer.js';
const checkpointer = getLangGraphCheckpointer();

The checkpointer stores thread state in the checkpoints and writes tables, automatically managed under the same WAL-journaled database as the event log.

Butler includes a built-in multi-agent state graph definition (OrchestratorState / buildOrchestratorGraph) to coordinate actions between different developer agents (e.g. Antigravity/Agy planning, Kiro CLI implementing, OpenCode verifying). The orchestrator uses LangGraph interrupts to pause execution until tasks are completed and marked complete in the Butler event log.

Butler/
├── src/
│   ├── db/            # SQLite connection pool, WAL mode, versioned schema migrations (v1–v8)
│   ├── events/        # Event store (append-only log), materializer, projections, type definitions
│   ├── coordinator/   # Heartbeat registry, session lifecycle, handoff quality scoring, session helpers
│   ├── vector/        # Pure-JS TF-IDF sparse memory indexer + cosine similarity
│   ├── langgraph/     # LangGraph checkpointer, orchestrator graph, builder utilities
│   ├── lib/           # Shared formatting utilities
│   ├── mcp/
│   │   ├── server.ts                    # MCP stdio transport, routing, auto-registration
│   │   ├── resources.ts                 # context, todos, wiki, sessions, memories, diff, checkpoints
│   │   ├── resources/                   # Resource handler modules (context.ts, diff.ts)
│   │   └── tools/
│   │       ├── session.tools.ts         # sessionregister, sessionheartbeat, sessiondisconnect
│   │       ├── todo.tools.ts            # todoadd, todocomplete, todoupdate, tododelete, todolist
│   │       ├── knowledge.tools.ts       # wikiupdate, ruleadd, ruleremove, decisionrecord, handoffcreate
│   │       ├── memory.tools.ts          # memorystore, memorysearch, memorydelete, projectlist
│   │       ├── coordination.tools.ts    # todoclaim, todounclaim, messagesend, broadcast, synccontext
│   │       ├── coordination/            # Coordination sub-handlers (sync.ts)
│   │       └── observability.tools.ts   # eventsexport, butlerping
│   ├── cli/
│   │   ├── main.ts        # CLI entry point and command router
│   │   ├── status.ts      # `npm run status` — terminal project summary
│   │   ├── tui.ts         # `npm run tui` — live split-screen terminal UI
│   │   ├── tuiRenderer.ts # TUI rendering logic
│   │   ├── tuiTheme.ts    # TUI color and styling constants
│   │   ├── dashboard.ts   # `npm run dashboard` — local SSE web dashboard
│   │   ├── dashboardServer.ts    # SSE server and HTTP handler
│   │   ├── dashboardHandlers.ts  # Dashboard data handlers
│   │   └── dashboardRenderer.ts  # Dashboard HTML rendering
│   ├── constants.ts       # Shared constants (TTLs, limits, timing values)
│   ├── project-config.ts  # .butler/project.json discovery (walks up directory tree)
│   ├── validation.ts
│   └── index.ts           # Application entry point
├── tests/
│   └── integration.test.ts
├── skills/            # Portable agent skill packages
│   └── butler-workflow/   # Butler coordination patterns for AI agents
├── docs/              # Workflows, best practices, troubleshooting, architecture, concepts, changelog, recovery guides
├── install/           # install.sh / install.ps1 — build + multi-client auto-config
├── package.json
└── tsconfig.json

• Events are Truth, State is Cache: We reconstruct project models deterministically by replaying event logs.
• 0-Clicks Portability: Vector indexers run on pure JavaScript TF-IDF token matching, eliminating the need for Python packages, heavy vector databases, or paid API keys.
• Invisible Ergonomics: The user never manages memory. The system simply remembers.
• Active Contribution, Not Passive Reading: Butler's server instructions coach every agent to write decisions, TODOs, rules, and handoffs — not just consume them. The shared brain only works if everyone feeds it.

Support Development

If this project helps your work, support ongoing maintenance and new features.

ETH Donation Wallet
0x11282eE5726B3370c8B480e321b3B2aA13686582

Scan the QR code or copy the wallet address above.

Explore more privacy-first and security tools:

• Timeseal - Time-locked encryption vault with Dead Man's Switch. AES-256 split-key crypto, ephemeral seals.
• Sanctum - Zero-trust encrypted vault with cryptographic plausible deniability. XChaCha20-Poly1305, Argon2id.
• GhostChat - True P2P encrypted chat via WebRTC. No servers, no storage, self-destructing messages.
• xmrproof - Monero payment verification, 100% client-side.
• GhostReceipt - Anonymous receipt generation with zero-knowledge proofs.

• BurpAPISecuritySuite - Burp Suite extension for API security testing. 15 attack types, 108+ payloads, BOLA/IDOR detection.
• Mcpwn - Automated security scanner for Model Context Protocol servers. Detects RCE, path traversal, prompt injection.
• DiffCatcher - Git repo discovery, diff capture, code element extraction.
• HoneypotScan - Honeypot detection service for security research.
• CheckAPI - LLM API key validator for multiple providers. Privacy-first, client-side validation.
• SeekYou - Host intelligence aggregator — unified OSINT across 15 sources for IPs, domains, and ASNs.

• burp-mcp-server - MCP server for Burp Suite Professional. Vulnerability scanning via AI assistants.
• nuclei-mcp - MCP server for Nuclei. Multi-target scanning, severity filtering.
• nmap-mcp - MCP server for Nmap. Stealth recon, vuln/NSE scanning.
• frida-mcp - MCP server for Frida. Dynamic instrumentation, SSL pinning bypass.

• 🔒 Privacy-First Development - P2P applications, encrypted communication, zero-knowledge systems
• 🚀 Web Application Development - Full-stack development with Next.js, React, TypeScript
• 🔧 Edge Computing Solutions - Cloudflare Workers, Pages, D1, KV, Durable Objects
• 🛡️ Security Tool Development - Burp extensions, penetration testing tools, automation frameworks
• 🤖 AI Integration - LLM-powered applications, intelligent automation, custom AI solutions
• 🔍 OSINT & Threat Intelligence - Custom reconnaissance tools, threat feed aggregation, IOC correlation

Get in Touch: teycirbensoltane.tn | Available for freelance projects and consulting

MIT License

Copyright (c) 2026 Teycir Ben Soltane

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Teycir Ben Soltane
Email: [email protected]
GitHub: @Teycir