beadle-dev

beadle

A programmable agent daemon controlled by email, secured by GPG.

Beadle is an autonomous agent that receives instructions via email and executes them as multi-stage pipelines. Commands are programs, the daemon is the shell, pipelines are pipes, and GPG signatures are sudo. By design, the owner controls what beadle can do by signing command definitions, and the trust gate controls who can trigger it. The trust gate is enforced today; command-signature enforcement is defined but not yet wired (see below).

How it works. You send an email. Beadle verifies your identity (PGP signature or Proton E2E encryption), checks your permissions, decomposes your instruction into a pipeline of commands, and executes them — mixing AI reasoning with fast CLI tools. You get the result back as an email reply. The daemon runs on your machine. No cloud service, no API keys shared with third parties.

Example. You email "summarize this" from your PGP-verified account:

1. Beadle verifies your identity and x (execute) permission
2. The planner maps "summarize" to a pipeline: [summarize, notify, reply]
3. Stage 0: Claude reads your email and produces a structured summary (45s)
4. Stage 1: biff wall broadcasts "New summary: Deploy plan" to the team (10ms)
5. Stage 2: Claude formats the summary and emails it back to you (45s)

The summary flows through the pipeline as JSON. Stage 1 is a side-effect (passthrough) — it reads the data but doesn't modify it. Stage 2 receives the full summary, not stage 1's "ok" output.

Two types of commands:

• Claude commands spawn an AI session for reasoning tasks: summarization, analysis, code generation. 45-60 seconds per stage.
• CLI commands exec binaries directly for deterministic operations: notifications, status checks, data transforms. Milliseconds per stage.

Both types are defined as YAML files with a signature field for owner GPG-signing. Command-signature verification is currently a stub and is not yet enforced; today the daemon gates execution on transport trust — a PGP-verified sender matched to a permitted contact — not on the command definitions themselves. Signature enforcement is the planned next step.

beadle-email

The shipping component is beadle-email — an MCP server that gives Claude Code a real email address with cryptographic trust at every layer.

• Claude emails you. Session summaries, build reports, deploy notifications — anything Claude produces can be mailed to you or your team. No webhook plumbing, no Slack integration. Just email.
• You email Claude. Send instructions, ask questions, or forward context from your phone. Beadle's four-level PGP trust model and per-contact permissions (rwx) control exactly what Claude can read, reply to, and act on — nothing is implicit.

Platforms: macOS, Linux

Quick Start

curl -fsSL https://raw.githubusercontent.com/punt-labs/beadle/407fc12/install.sh | sh

Downloads the beadle-email binary, verifies its SHA256 checksum, and attempts to install the Claude Code plugin (MCP tools + slash commands + hooks). If plugin installation fails, the script falls back to registering the standalone MCP server (no slash commands or hooks). Runs doctor to check your setup. Restart Claude Code after install. If you previously registered beadle-email as a standalone MCP server via claude mcp add, remove it first with claude mcp remove beadle-email to avoid duplicate registrations.

Plugin install provides MCP tools, slash commands (/inbox, /mail, /send, /contacts), and hooks (two-channel display, automatic session setup). Standalone MCP provides only MCP tools --- no slash commands or hooks.

curl -fsSL https://raw.githubusercontent.com/punt-labs/beadle/407fc12/install.sh -o install.sh
cat install.sh
sh install.sh

mkdir -p ~/.local/bin
curl -fsSL https://github.com/punt-labs/beadle/releases/latest/download/beadle-email-darwin-arm64 -o ~/.local/bin/beadle-email
chmod +x ~/.local/bin/beadle-email