Umbrella

One CLI, skills for your AI editor, and an optional agent loop with memory, MCP tools, chat bridges, and chaos recovery.

Terminal — zsh
# Quick start (Node 18+) ➜ ~
View on GitHub npm package

What it is

Umbrella is an installer (Markdown skills into ~/.umbrella or ./.umbrella), a CLI named umbrella, and a Node daemon that plans, runs tools (including MCP), and writes to SQLite—with optional Telegram, Discord, and Slack chat bridges and a small HTTP dashboard.

  • Live Installer, daemon, SQLite, shell/read/write, mcp:… calls, chaos recovery, run log + scorecard UI, cron/interval schedules, optional voice transcribe hook.
  • IDE /umb:… in the daemon is simulated; run those flows in Claude / Cursor / Gemini with skills pointed at your .umbrella folder.

Install

Published package: @benjam16/umbrella (adjust scope if yours differs).

Global CLI

Terminal
# Install binary globally, then verify
➜ ~ npm install -g @benjam16/umbrella
➜ ~ umbrella --version

Without global install (npx)

Terminal
# Copy skills, then start the agent
➜ ~ npx @benjam16/umbrella@latest install
➜ ~ npx @benjam16/umbrella@latest agent start

From source

Terminal
# Clone, deps, build; local skills in ./.umbrella with --local
➜ ~ git clone <repo> && cd Umbrella
➜ Umbrella npm install && npm run build
➜ Umbrella node bin/install.js --claude --local
# Dev CLI (TypeScript via tsx; agent still uses dist/)
➜ Umbrella npm run dev -- --version
➜ Umbrella node dist/src/cli.js agent start

CLI

Command Effect
umbrella install Interactive install: copy modules and agent runtime into ~/.umbrella or ./.umbrella.
umbrella up Same as agent start. Optional --dry-run previews .env + config.json merge without starting the daemon.
umbrella agent start Heartbeat: planner → executor → verifier → memory summarize (MCP init, gateways, dashboard if configured).
umbrella agent status Whether ~/.umbrella/agent.pid points at a live process.
umbrella agent stop Sends SIGTERM to the daemon PID.
umbrella doctor Node, pid, SQLite, LLM env, Telegram / Discord / Slack / voice-STT hints, schedules, token budget.
umbrella config-path Prints resolved config.json path.
umbrella session reset Clears ~/.umbrella/session.json (new session on next heartbeat).
umbrella scaffold cli … Shipping template: TypeScript CLI + Vitest + publish workflow (see examples/SHIPPING.md).

IDE

Point Claude, Cursor, or Gemini CLI at ~/.umbrella/skills/ and ~/.umbrella/commands/. Each module’s SKILL.md describes /umb:… workflows: coding, lean, tools, memory, orchestrate, secure, observe, flow, agent-runtime.

The daemon does not use Cursor as an LLM backend; it calls Anthropic, OpenAI, or Google APIs—or any OpenAI-compatible endpoint via UMBRELLA_OPENAI_BASE_URL (e.g. Ollama) plus UMBRELLA_OLLAMA_MODEL / UMBRELLA_MODEL.

Agent heartbeat

  1. Picks a goal: foreground interrupt, scheduled (schedule.json → SQLite), core background, or idle if paused.
  2. Planner emits XML (<plan>) — LLM or fallback; tool hints include MCP names.
  3. Executor runs each <task> (optional per-slice subagent if configured).
  4. Verifier checks the last result (heuristics + optional shell hook).
  5. Learner + skill promotion pipeline; memory compaction optional.
  6. Optional digest to chat every UMBRELLA_DIGEST_HEARTBEATS cycles.

UMBRELLA_HEARTBEAT_MS defaults to 60000. UMBRELLA_SCHEDULE_NOTIFY=1 pings the last-used chat after a scheduled heartbeat finishes.

Memory

SQLite at ~/.umbrella/memory.db: execution results, chaos events, chat ingests, LLM audit references, etc.

Agent state in the same DB: core goal, foreground goal, background pause, last Telegram / Discord / Slack channel for digests. Table umbrella_schedules stores synced cron/interval jobs from ~/.umbrella/schedule.json.

Executor

Action Behavior
/umb:… Simulated in daemon; real runs happen in the IDE.
shell:… Shell (safeguards); failures can trigger chaos recovery if an LLM is configured.
read:path Up to ~2000 chars.
write:path|body Writes file.
mcp:{…} JSON line: server index + name + arguments when UMBRELLA_MCP_ENABLED=1 and servers are configured.
scaffold-cli:{…} npm CLI template under UMBRELLA_SHIPPING_ROOT when set.
git … / npm … / node … Shell with chaos wrapper where applicable.
Other text Optional one-line LLM router → tool, MCP, or shell.

Chaos & dashboard

Failed shell runs can invoke the Chaos Specialist (LLM + optional URL text preview via UMBRELLA_WEB_FETCH), retry with recovery; chaos_event rows in memory. Optional human approval: UMBRELLA_CHAOS_APPROVE=1 + POST /api/chaos-approve.

Set UMBRELLA_DASHBOARD_PORT (e.g. 4578) and open http://127.0.0.1:4578/ — HTML UI plus JSON routes such as /api/chaos-logs, /api/last-run, /api/run-log (scorecard), /api/version, /api/health, /api/schedules, /api/mcp-tools, /api/tools (built-in + MCP list).

UMB_X402_ENABLED=1 enables a payment-path stub for quota-style errors.

Chat gateways

All use the same task surface as the HTTP API; messages are handled by the shared command handler. Set only the bridges you need.

Channel Setup
Telegram TELEGRAM_BOT_TOKEN — /umb … commands; digests and schedule notify use the last chat that messaged the bot.
Discord DISCORD_BOT_TOKEN + Message Content Intent — !umb … in servers/DMs.
Slack Socket Mode: SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_SIGNING_SECRET (all three) — !umb … same as Discord.

HTTP API

When the dashboard port is set, mutating routes expect Authorization: Bearer <UMBRELLA_INBOUND_SECRET> (set the secret in your env). Examples below use 4578; change the port to match yours.

Terminal
# Foreground goal (next heartbeat)
➜ ~ curl -sS -X POST http://127.0.0.1:4578/api/goal \
  -H "Authorization: Bearer $UMBRELLA_INBOUND_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"goal":"Fix flaky test in worker"}'

# Unified tool list (no auth)
➜ ~ curl -sS http://127.0.0.1:4578/api/tools

# Voice: set UMBRELLA_VOICE_STT to your STT binary first
➜ ~ curl -sS -X POST http://127.0.0.1:4578/api/voice-transcribe \
  -H "Authorization: Bearer $UMBRELLA_INBOUND_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"audioBase64":"<base64>","setForegroundGoal":true}'

See docs/VOICE.md for raw audio upload and limits (6 MiB max).

Environment

Dotenv load order for the daemon: UMBRELLA_DOTENV (if set), ~/.umbrella/.env, optional secrets helper, then config.json — existing non-empty shell env wins.

Variable Purpose
ANTHROPIC_API_KEY Claude
OPENAI_API_KEY OpenAI / Codex-style
UMBRELLA_OPENAI_BASE_URL OpenAI-compatible API (e.g. Ollama /v1)
UMBRELLA_OLLAMA_MODEL / UMBRELLA_MODEL Model id for the active provider
GEMINI_API_KEY / GOOGLE_API_KEY Google AI
UMBRELLA_LLM_PROVIDER anthropic | openai | google | …
UMBRELLA_MCP_ENABLED 1 to connect MCP servers from env / file
UMBRELLA_MCP_SERVERS JSON array: stdio command and/or HTTP url (+ headers)
UMBRELLA_MCP_SERVERS_FILE Path to JSON file (merged with env list)
UMBRELLA_INBOUND_SECRET Bearer token for dashboard POST routes
UMBRELLA_DASHBOARD_PORT Local dashboard + JSON API (e.g. 4578)
TELEGRAM_BOT_TOKEN Telegram bot
DISCORD_BOT_TOKEN Discord bot (!umb)
SLACK_BOT_TOKEN + SLACK_APP_TOKEN + SLACK_SIGNING_SECRET Slack Socket Mode (!umb)
UMBRELLA_VOICE_STT Executable: argv[1]=audio file, stdout=transcript
UMBRELLA_VOICE_STT_TIMEOUT_MS STT subprocess timeout (default 120000)
UMBRELLA_HEARTBEAT_MS Daemon loop interval (default 60000)
UMBRELLA_DIGEST_HEARTBEATS Post digest to chat every N heartbeats
UMBRELLA_SCHEDULE_NOTIFY 1 — ping chat after scheduled heartbeat
UMBRELLA_WEB_FETCH Allow Chaos specialist URL text preview (allowlist)
UMBRELLA_SHIPPING_ROOT Root for scaffold-cli: agent actions
UMBRELLA_SUBAGENT_PER_SLICE 1 + LLM — expand each plan slice via subagent
UMBRELLA_PLANNER_TOOL_HINTS_MAX_CHARS Cap orchestrator MCP/tool block in the planner prompt
UMB_X402_ENABLED Payment stub for quota-style errors
UMBRELLA_VERIFY_COMMAND Shell during verify (exit 0 + heuristic pass)
UMBRELLA_STUCK_THRESHOLD Failures before escalation goal (default 3)
UMBRELLA_LLM_AUDIT Set 0 to disable llm-audit.log
UMBRELLA_TOKEN_BUDGET_DAILY Approximate daily LLM token budget (UTC)
UMBRELLA_MEMORY_LLM_COMPACT Optional memory compaction via LLM
UMBRELLA_SECRETS_HELPER Executable printing JSON env map for empty keys only
UMBRELLA_MAX_TASK_TOKENS / slice / milestone Orchestrator budget hints (env or JSON)

What’s built in now

  • PID + service UX: umbrella up / agent start|stop|status, ~/.umbrella/agent.pid, single-instance guard, umbrella doctor, session reset, config-path.
  • GSD-style orchestration: planner emits <milestone> → <slice> → <task>; optional per-slice subagent expansion (UMBRELLA_SUBAGENT_PER_SLICE=1 + LLM); tool hints include MCP server indices.
  • Stuck-loop guard: similar failures in a row raise an escalation goal (UMBRELLA_STUCK_THRESHOLD).
  • Verifier hook: UMBRELLA_VERIFY_COMMAND (e.g. npm test) — exit 0 and text heuristic.
  • Run log + tests: JSONL heartbeats with plan/execution previews; npm test checks deterministic plan XML expansion.

Remaining limits (next upgrades)

  • Subagent depth: optional slice expansion exists, but not full nested worker farms or isolated sandboxes by default.
  • Chaos / LLM shell risk: model-driven recovery; tighten shell-policy, containers, or human approval for production.
  • Verifier: no second “judge” LLM or structured rubric yet.
  • Bundled STT/TTS: voice path is external binary + HTTP; no in-process speech yet.