Skip to content

About

Multiplatform AI agent runtime.

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

113 Commits

Folders and files

Repository files navigation

Troublemaker

An AI agent runtime with multi-platform adapters. Connects to Microsoft Teams, Slack, Zulip, Rocket.Chat, Mattermost, Telegram, Discord, Email, SMS/iMessage, website forms, web chat, MCP clients, and voice — runs tools, manages files, and maintains persistent memory across sessions.

Built on mom by Mario Zechner. Troublemaker extracts mom's agent core into a standalone runtime with multi-platform adapters. Mom does the thinking — troublemaker gets it to more places.

How It Works

When a message arrives from any platform, troublemaker hands it to the mom agent. Mom is self-managing: she installs her own tools, writes CLI tools ("skills"), configures credentials, and maintains her workspace autonomously.

One unified workspace spans every channel (Microsoft Teams, Slack, Zulip, Rocket.Chat, Mattermost, Discord, Telegram, email, phone):

  • Persistent memory — a single MEMORY.md loaded into every prompt
  • Full history — one log.jsonl archive across all channels, plus awareness/context.jsonl for the LLM window
  • Custom tools — one set of skills the agent writes and reuses across sessions
  • Scheduled events — one attention queue for reminders, cron prompts, and webhook triggers

The agent has full bash access (in a Docker sandbox or on host), reads/writes files, and creates whatever tools it needs. You provide a working directory — the agent does the rest.

Architecture

  INBOUND HTTP (webhooks, host relays)       ┌──────────────────────────────────┐
                                             │         Unified Gateway          │
  Slack Events API ────────────────────────► │  POST /slack/events              │
  Microsoft Teams Bot Connector ───────────► │  POST /teams/messages            │
  Mattermost host relay ───────────────────► │  POST /mattermost/inbound        │
  Rocket.Chat host relay ──────────────────► │  POST /rocketchat/inbound        │
  Zulip host relay ────────────────────────► │  POST /zulip/inbound             │
  Telegram webhook ────────────────────────► │  POST /telegram/webhook          │
  Discord Interactions ────────────────────► │  POST /discord/interactions      │
  Discord gateway relay ───────────────────► │  POST /discord/messages          │
  Email webhook ───────────────────────────► │  POST /email/inbound             │
  SMS / iMessage (Loop, Twilio, host) ─────► │  POST /phone-messaging/webhook   │
  Website form submissions ────────────────► │  POST /form/webhook              │
  Web chat UI ─────────────────────────────► │  POST /web/chat · /web/stop      │
  Generic input webhook (web) ─────────────► │  POST /input/webhook             │
  MCP clients (agent tools) ───────────────► │  POST /mcp                       │
  Host scheduler (delayed prompts) ────────► │  POST /scheduled-prompt/inbound  │
  Operator / fleet control ────────────────► │  POST /operator/{message,        │
                                             │        assign,configure}         │
                                             │  GET  /operator/{read,describe}  │
  Host tool bridge ────────────────────────► │  POST /host/tools/{bash,execute} │
                                             │                                  │
  WEBSOCKET UPGRADES                         │                                  │
  Terminal UI / remote shell ──────────────► │  WS   /terminal                  │
  Realtime voice ──────────────────────────► │  WS   /voice/realtime            │
                                             │                                  │
  STATUS                                     │  GET  /health · /status          │
                                             │  GET  /schedule                  │
                                             │  (single HTTP server, default    │
                                             │   port 3000: --port or           │
                                             │   MOM_HTTP_PORT)                 │
                                             └────────────────┬─────────────────┘
                                                              │
  OUTBOUND CONNECTIONS (no public ingress)                    ▼
  Slack Socket Mode ───────────────────────────────►  ┌──────────────────┐
  Mattermost WebSocket ────────────────────────────►  │   Agent core     │
  Telegram long polling ───────────────────────────►  │  (mom: tools,    │
  Discord Gateway WebSocket ───────────────────────►  │   memory, skills)│
                                                      └──────────────────┘
  INTERNAL / LOCAL                                             ▲
  Heartbeat (periodic self check-ins) ─────────────────────────┤
  Scheduled events (workspace event files) ────────────────────┤
  Voice bridges (WS :8765 voice, :8766 web voice) ─────────────┘

Every inbound HTTP adapter shares one server with path-based routing. The gateway starts first and registers routes, then each adapter starts on its own. If one adapter fails, the others keep working; its route returns 503 until it is ready. Webhook routes use their platform's own authentication, such as Slack signing secrets, Bot Connector JWTs, Discord signatures, or scoped bearer capabilities for host relays. /operator/* stays disabled unless MOM_OPERATOR_INBOUND_TOKEN is set, and /scheduled-prompt/inbound exists only when a host owns delayed schedules.

For always-on deployments (VPS, Docker) that have no public ingress, use Slack Socket Mode, Mattermost WebSocket, Telegram polling, or the Discord Gateway adapter. Each one opens an outbound connection to the platform. The heartbeat and scheduled events wake the same agent internally, so every channel shares one workspace, memory, and log.

Quick Start

# Clone and build
git clone https://github.com/tinyfatco/troublemaker.git
cd troublemaker
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm link --global

# Set platform tokens
export ANTHROPIC_API_KEY=sk-ant-...
export MOM_SLACK_APP_TOKEN=xapp-...    # Socket Mode
export MOM_SLACK_BOT_TOKEN=xoxb-...

# Run (auto-detects adapters from env vars)
troublemaker ./data

# Or specify adapters explicitly
troublemaker --adapter=slack:webhook,telegram:webhook --port=3002 ./data

Adapters

Adapter Mode Env Vars Required Use Case
slack / slack:socket Outbound WebSocket MOM_SLACK_APP_TOKEN, MOM_SLACK_BOT_TOKEN Always-on (VPS, Docker)
slack:webhook Inbound HTTP MOM_SLACK_BOT_TOKEN, MOM_SLACK_SIGNING_SECRET Webhook-based
teams:webhook Authenticated Bot Connector HTTP MOM_TEAMS_CLIENT_ID, client secret or managed identity Personal/group chats, channels, threads, ambient RSC messages, reactions, personal files, and inline images
mattermost / mattermost:socket Outbound WebSocket + REST MOM_MATTERMOST_URL, MOM_MATTERMOST_BOT_TOKEN Self-hosted or managed Mattermost
rocket-chat:webhook Host-managed HTTP + scoped REST proxy MOM_ROCKETCHAT_URL, MOM_ROCKETCHAT_BOT_TOKEN, MOM_ROCKETCHAT_INBOUND_TOKEN, MOM_ROCKETCHAT_ALLOWED_ROOMS TinyFat customer relationship rooms
zulip:webhook Host-managed HTTP + scoped REST proxy MOM_ZULIP_URL, MOM_ZULIP_BOT_TOKEN, MOM_ZULIP_INBOUND_TOKEN Subscribed channels, topics, ambient messages, and direct messages
telegram / telegram:polling Outbound polling MOM_TELEGRAM_BOT_TOKEN Always-on
telegram:webhook Inbound HTTP MOM_TELEGRAM_BOT_TOKEN, MOM_TELEGRAM_WEBHOOK_URL (unless MOM_SKIP_WEBHOOK_REGISTRATION=true), and MOM_TELEGRAM_WEBHOOK_SECRET or a strong MOM_TELEGRAM_INBOUND_TOKEN Webhook-based
discord / discord:gateway Outbound Gateway WebSocket + REST MOM_DISCORD_BOT_TOKEN, MOM_DISCORD_APPLICATION_ID Always-on; no public ingress or relay
discord:webhook Signed inbound Interactions HTTP Discord bot token, application ID, and public key Slash commands and compatible relay deployments
email:webhook Inbound HTTP MOM_EMAIL_TOOLS_TOKEN, MOM_EMAIL_INBOUND_TOKEN (≥32 bytes) Webhook-based
mattermost:webhook Host-managed HTTP + REST MOM_MATTERMOST_URL, MOM_MATTERMOST_BOT_TOKEN, MOM_MATTERMOST_INBOUND_TOKEN Hosted Mattermost behind a relay
phone-messaging:webhook Inbound HTTP + provider REST MOM_PHONE_MESSAGING=true or Loop/Twilio credentials, MOM_PHONE_INBOUND_TOKEN Two-way SMS and iMessage conversations
form:webhook Inbound HTTP MOM_FORM_INGRESS=true, MOM_FORM_INBOUND_TOKEN Website form submissions
web Inbound HTTP MOM_WEB_CHAT=true Browser chat UI and generic input webhook
mcp MCP Streamable HTTP MOM_MCP=true, MOM_MCP_AUTH_TOKEN (≥32 bytes) Expose agent tools to MCP clients; /mcp always checks the token in x-tools-token, even behind an authenticating proxy
voice WebSocket (port 8765) MOM_VOICE_ADAPTER=true, MOM_ELEVENLABS_API_KEY Voice sessions

Auto-detection: If no --adapter flag is given, troublemaker detects which adapters to start based on which env vars are set. Multiple adapters can run simultaneously.

CLI

troublemaker [options] <working-directory>

Options:
  --sandbox=host              Run tools on host (default)
  --sandbox=docker:<name>     Run tools in Docker container (recommended)
  --adapter=<name>[,<name>]   Platform adapters (default: auto-detect)
  --port=<number>             Gateway HTTP port (default: 3000, or MOM_HTTP_PORT)
  --host=<addr>               Gateway bind address (default: 127.0.0.1; loopback only
                              unless a Hostd container owns the boundary)
  --skills=<dir>              Extra skills directory (repeatable)
  --ui=<dir>                  Serve a static web UI from the gateway

  --download <channel-id>     Download Slack channel history and exit

The package installs three binaries: troublemaker (the runtime), crawdad (an alias for the same entry point), and troublemaker-tui (the terminal client below).

Terminal UI

The optional terminal UI connects to an already-running Troublemaker gateway, so the resident agent remains the sole owner of its context, tools, and active run. Install a short command for each agent, then invoke the agent by name:

troublemaker-tui install demo-agent \
  --url http://127.0.0.1:3002 \
  --name "Demo Agent"

demo-agent

The installer creates a profile in ~/.config/troublemaker/tui.json and a command symlink in ~/.local/bin. Keep the gateway loopback-only (or reach it through a local tunnel), and ensure ~/.local/bin is on your PATH.

When uv is installed, agent commands open the Textual client, which has expandable tool calls, in-place steering and slash-command autocomplete. Run demo-agent --classic, or set TROUBLEMAKER_TUI=classic, to use the TypeScript client described below. Without uv, the classic client opens automatically.

In the classic client, compact presentation is the default: the UI uses Pi's terminal styling, labels messages by source, follows the resident's live awareness stream, and shows only agent-supplied tool labels. Add --presentation pi for progressive assistant text plus bounded Pi-style tool detail, or --presentation pi-thinking to also paint signature-free local model reasoning as soon as each cumulative snapshot arrives. Every tool call appears as soon as its live call block arrives, updates in place while running, then settles into one summary line. A brief human-readable label is strongly encouraged, but omission or blank text falls back to the tool name and never blocks execution. Calls remain collapsed until you press Ctrl+T, release it, type a call number, and pause briefly; expanded invocation, output, and result details use the same bounded redaction projection as portable clients. A final call without a matching result stays visibly unknown or cancelled rather than turning green. Compact and ordinary Pi clients never receive thinking; Pi-thinking is an explicit authenticated local-terminal projection, and durable history remains compact. The UI supports /help, /reload, /status, /clear, /stop, and /quit. Input remains available during active turns so follow-ups can soft-steer the same terminal run, and automatic context compaction is labeled explicitly instead of appearing as continued thinking.

Busy DMs and explicit @mentions use the same non-interrupting contract across adapters: the message soft-steers an accepting model at its next safe boundary, or queues as a fresh canonical turn. Ordinary user input never aborts an active tool or run; stop remains the explicit cancellation control.

When working output is fixed to a dedicated Slack channel, the existing rolling window still owns one compact top-level batch. Each surfaced tool gets exactly one reply under that batch root; the reply is edited from running invocation to bounded redacted result or error. Parallel and long-running tools retain their original batch/reply identity, while the first tool after a configured rollover opens the next batch. Separately authorized channel updates remain outside the batch thread.

Environment Variables

Variable Required For Description
ANTHROPIC_API_KEY Anthropic API models Anthropic API key; not used by the Claude CLI backend
MOM_MODEL_PROVIDER model selection Provider for the active model; overrides settings.json (for example anthropic, claude-cli, codex-cli)
MOM_MODEL_ID model selection Model ID for that provider (for example opus, default)
MOM_CLAUDE_CLI_PATH claude-cli models Claude executable path (default: claude)
MOM_CLAUDE_CLI_PERMISSION_MODE claude-cli host tools Optional explicit Claude permission mode
MOM_CLAUDE_CLI_TIMEOUT_MS claude-cli models Hard turn timeout (default 30 min)
MOM_CLAUDE_CLI_IDLE_TIMEOUT_MS claude-cli models Timeout with no CLI output (default 5 min)
MOM_CLAUDE_CLI_MAX_OUTPUT_CHARS / _LINES claude-cli models Output caps per turn (default 8 MiB / 20,000 lines)
MOM_CLAUDE_CLI_RESEED_CHARS claude-cli models Transcript budget used to reseed a fresh CLI session (default 120,000)
MOM_CLAUDE_CLI_AUTH_CACHE_MS claude-cli models How long a successful auth check is cached (default 30 s, max 5 min)
MOM_CODEX_CLI_PATH codex-cli models Codex executable path (default: codex)
MOM_CODEX_CLI_TIMEOUT_MS, _IDLE_TIMEOUT_MS, _MAX_OUTPUT_CHARS, _MAX_OUTPUT_LINES, _RESEED_CHARS, _AUTH_CACHE_MS codex-cli models Same meanings and defaults as the Claude CLI vars above
MOM_COMPACTION_TIMEOUT_MS compaction Context compaction timeout (default 6 min; clamped to 30 s–30 min)
MOM_COMPACTION_SOUND compaction (macOS) Sound cue when compaction runs: unset/true uses Purr, a file path uses that sound, off disables
MOM_COMPACTION_SOUND_PLAYER / _VOLUME compaction (macOS) Player binary (default /usr/bin/afplay) and volume (default 0.12)
MOM_VOICE_ADAPTER auto-detection Set to true to start the voice adapter (WebSocket on port 8765)
MOM_OPENAI_API_KEY realtime voice OpenAI key for /voice/realtime when no cloud broker is configured (OPENAI_API_KEY also accepted)
MOM_DEEPGRAM_API_KEY console transcription Deepgram key; or MOM_DEEPGRAM_API_KEY_FILE, or MOM_DEEPGRAM_API_KEY_PLIST_FILE + _PLIST_KEY
MOM_ELEVENLABS_API_KEY web voice, speak ElevenLabs key; also enables the web voice bridge on port 8766. Voice sessions can read MOM_ELEVENLABS_API_KEY_FILE (default ~/.config/sag/elevenlabs-api-key)
MOM_ELEVENLABS_VOICE_ID / _MODEL_ID web voice, speak ElevenLabs voice and model; MOM_ELEVENLABS_VOICE_ID_FILE defaults to ~/.config/sag/voice-id
MOM_SLACK_APP_TOKEN slack:socket Slack app-level token (xapp-...)
MOM_SLACK_BOT_TOKEN slack:* Slack bot token (xoxb-...)
MOM_SLACK_SIGNING_SECRET slack:webhook HMAC signing secret for webhook verification
MOM_SLACK_INBOUND_TOKEN slack:webhook Scoped bearer capability when a trusted host proxy verifies Slack instead
MOM_SLACK_ALLOWED_DM_USERS slack:* Optional comma-separated Slack user IDs allowed to invoke the agent by DM
MOM_TEAMS_CLIENT_ID teams:webhook Microsoft Entra application and bot ID
MOM_TEAMS_CLIENT_SECRET teams:webhook Bot client credential; omit when using managed identity
MOM_TEAMS_MANAGED_IDENTITY_CLIENT_ID teams:webhook Managed identity client ID, or system
MOM_TEAMS_TENANT_ID teams:webhook Required tenant for Bot Connector authentication and all activity/outbound scope
MOM_TEAMS_CLOUD teams:webhook Optional Public, USGov, USGovDoD, or China cloud
MOM_TEAMS_SERVICE_URL teams:webhook Optional Bot Connector service URL override
MOM_TEAMS_ALLOWED_TENANTS teams:webhook Optional comma-separated tenant allowlist
MOM_TEAMS_ALLOWED_TEAMS teams:webhook Optional comma-separated team allowlist
MOM_TEAMS_ALLOWED_CONVERSATIONS teams:webhook Optional comma-separated durable conversation allowlist
MOM_TEAMS_ALLOWED_DM_USERS teams:webhook Optional comma-separated durable Teams or Entra user IDs allowed in personal/group chats
MOM_TEAMS_CHANNEL_MESSAGES_DIRECT teams:webhook When true, every allowed channel post directly wakes the agent; otherwise unmentioned traffic is ambient
MOM_MATTERMOST_URL mattermost:* Mattermost base URL, for example https://mattermost.example.com
MOM_MATTERMOST_BOT_TOKEN mattermost:* Mattermost bot personal access token
MOM_MATTERMOST_ALLOWED_DM_USERS mattermost:* Optional comma-separated user IDs or usernames allowed to invoke the agent by DM
MOM_MATTERMOST_ALLOWED_CHANNELS mattermost:* Optional comma-separated channel IDs; inbound, outbound, files, and thread reads fail closed outside them
MOM_MATTERMOST_CHANNEL_MESSAGES_DIRECT mattermost:* When true, every non-self post in an allowed channel directly wakes the agent
MOM_MATTERMOST_INBOUND_TOKEN mattermost:webhook Required scoped bearer capability for host-delivered events (minimum 32 bytes)
MOM_ROCKETCHAT_URL rocket-chat:webhook Host-owned, context-scoped Rocket.Chat REST proxy URL
MOM_ROCKETCHAT_BOT_TOKEN rocket-chat:webhook Per-context host capability, never the native Rocket.Chat token
MOM_ROCKETCHAT_INBOUND_TOKEN rocket-chat:webhook Per-context bearer token for host-delivered room events
MOM_ROCKETCHAT_ALLOWED_ROOMS rocket-chat:webhook Required comma-separated room allowlist; all reads and writes fail closed outside it
MOM_ROCKETCHAT_AGENT_NAME rocket-chat:webhook Human-facing agent name used in the local transcript
MOM_ZULIP_URL zulip:webhook Host-owned, context-scoped Zulip REST proxy URL
MOM_ZULIP_BOT_TOKEN zulip:webhook Per-context host capability, never the native Zulip API key
MOM_ZULIP_INBOUND_TOKEN zulip:webhook Per-context bearer token for host-delivered channel and direct-message events
MOM_ZULIP_ALLOWED_CHANNELS zulip:webhook Optional numeric stream allowlist; when omitted, the adapter follows the bot's live subscriptions
MOM_ZULIP_ALLOWED_DM_USERS zulip:webhook Optional comma-separated Zulip user IDs allowed to invoke the agent by direct message
MOM_ZULIP_CHANNEL_MESSAGES_DIRECT zulip:webhook When true, every non-self channel message directly wakes the agent; otherwise unmentioned traffic is ambient
MOM_ZULIP_AGENT_NAME zulip:webhook Human-facing agent name used in the local transcript
MOM_TELEGRAM_BOT_TOKEN telegram:* Telegram bot token from @BotFather
MOM_TELEGRAM_WEBHOOK_URL telegram:webhook Public URL for webhook registration
MOM_TELEGRAM_WEBHOOK_SECRET telegram:webhook Secret token for request verification
MOM_TELEGRAM_INBOUND_TOKEN telegram:webhook Scoped bearer capability when a trusted host proxy verifies Telegram instead
MOM_SKIP_WEBHOOK_REGISTRATION telegram:webhook Skip Telegram webhook registration (for external management)
MOM_TELEGRAM_TAKEOVER telegram:polling When true, delete any registered webhook at startup so polling can take over
MOM_DISCORD_BOT_TOKEN discord:* Discord bot token; never put it in source or logs
MOM_DISCORD_APPLICATION_ID discord:* Discord application snowflake
MOM_DISCORD_PUBLIC_KEY discord:webhook Ed25519 public key for signed Interactions
MOM_DISCORD_INBOUND_TOKEN discord:webhook relay Scoped bearer capability for /discord/messages; relay ingress is disabled when omitted
MOM_DISCORD_GATEWAY auto-detection Set to true to explicitly auto-select discord:gateway
MOM_DISCORD_GATEWAY_INTENTS discord:gateway Optional decimal intent bitfield (default 37377)
MOM_DISCORD_GATEWAY_AMBIENT_MESSAGES discord:gateway Set to true to observe non-mention guild messages (default false)
MOM_DISCORD_GATEWAY_SHARD_ID discord:gateway Optional zero-based shard handled by this process; set with shard count
MOM_DISCORD_GATEWAY_SHARD_COUNT discord:gateway Optional total shard count; set with shard ID
MOM_DISCORD_ALLOWED_GUILDS discord:* Optional comma-separated guild snowflakes
MOM_DISCORD_ALLOWED_CHANNELS discord:* Optional comma-separated guild-channel snowflakes; not applied to DMs
MOM_DISCORD_ALLOWED_USERS discord:* Optional comma-separated user snowflakes for all inbound messages
MOM_DISCORD_ALLOWED_DM_USERS discord:* Optional comma-separated user snowflakes for DMs
MOM_EMAIL_TOOLS_TOKEN email:webhook Token for email send API
MOM_EMAIL_SEND_URL email:webhook Email send endpoint (default: https://tinyfat.com/api/email/send)
MOM_EMAIL_INBOUND_TOKEN email:webhook Required scoped bearer capability for inbound email delivery (minimum 32 bytes)
MOM_EMAIL_TOOLS_ONLY email:webhook When true, disable generic email replies; the agent must use gmail_draft then gmail_send
MOM_EMAIL_LOG_MODE email:webhook Tool work log on email replies: none (default), inline, or attachment
MOM_PHONE_INBOUND_TOKEN phone:webhook Required scoped bearer capability for inbound phone delivery (minimum 32 bytes)
MOM_PHONE_MESSAGING auto-detection Set to true to start phone-messaging:webhook; also auto-selected by Loop or Twilio credentials
MOM_PHONE_DEFAULT_PROVIDER phone:webhook Preferred provider when several are configured (loop, twilio, or managed)
MOM_PHONE_PREFERRED_TRANSPORT phone:webhook auto (default), imessage, sms, mms, rcs, or whatsapp
MOM_PHONE_HOST_MANAGED phone:webhook When true, send through the host's scoped endpoint instead of a provider; requires the two vars below and TROUBLEMAKER_CONTEXT_ID
MOM_PHONE_SEND_URL phone:webhook (host-managed) Host-owned phone send endpoint
MOM_PHONE_SEND_TOKEN phone:webhook (host-managed) Scoped send capability (falls back to FAT_TOOLS_TOKEN)
MOM_LOOPMESSAGE_API_KEY phone:webhook (Loop) Loop iMessage API key (LOOPMESSAGE_API_KEY also accepted)
MOM_LOOPMESSAGE_SENDER_ID phone:webhook (Loop) Loop sender ID
MOM_LOOPMESSAGE_BASE_URL phone:webhook (Loop) Optional Loop API base URL override
MOM_TWILIO_ACCOUNT_SID phone:webhook (Twilio) Twilio account SID (TWILIO_ACCOUNT_SID also accepted)
MOM_TWILIO_AUTH_TOKEN phone:webhook (Twilio) Twilio auth token
MOM_TWILIO_PHONE_NUMBER phone:webhook (Twilio) Sending number; or use a messaging service SID
MOM_TWILIO_MESSAGING_SERVICE_SID phone:webhook (Twilio) Twilio messaging service SID
MOM_FORM_INBOUND_TOKEN form:webhook Required scoped bearer capability for inbound form delivery (minimum 32 bytes)
MOM_FORM_INGRESS auto-detection Set to true to start form:webhook
MOM_WEB_CHAT auto-detection Set to true to start the web adapter (/web/chat, /web/stop, /input/webhook)
MOM_WEB_INPUT_TOKEN web Bearer capability for web chat input (minimum 32 bytes; required inside a Hostd container)
MOM_WEBHOOK_INPUT_TOKEN web Bearer capability for /input/webhook (minimum 32 bytes); MOM_WEBHOOK_INPUT_TOKEN_FILE reads it from a protected file
MOM_WEBHOOK_INPUT_ALLOW_UNAUTHENTICATED web Set to true to accept unauthenticated /input/webhook posts (local only; refused inside Hostd)
MOM_MCP auto-detection Set to true to start the mcp adapter
MOM_MCP_AUTH_TOKEN mcp Required capability for /mcp (minimum 32 bytes)
MOM_SCHEDULED_PROMPT_INBOUND_TOKEN scheduled prompts Bearer capability for /scheduled-prompt/inbound (minimum 32 bytes); must be set together with MOM_HOSTD_SCHEDULE_OWNER=host and TROUBLEMAKER_CONTEXT_ID
MOM_HOSTD_SCHEDULE_OWNER scheduled prompts Set to host when Hostd owns delayed schedules; local delayed events then defer to the host
MOM_SITE_DEPLOY_TOKEN site deploy tool Capability used by the site_deploy tool
MOM_OPERATOR_INBOUND_TOKEN operator routes Enables /operator/* with a scoped bearer capability (minimum 32 bytes); routes are disabled when omitted
MOM_HTTP_PORT — Gateway port override (same as --port)

Discord Gateway

Gateway mode receives DMs, bot mentions, and replies to known bot messages over an outbound Discord API v10 WebSocket. Ordinary guild messages are discarded unless ambient intake is explicitly enabled. Enable the Message Content privileged intent for the Discord application, then run:

export MOM_DISCORD_BOT_TOKEN='<bot-token>'
export MOM_DISCORD_APPLICATION_ID='<application-snowflake>'
troublemaker --adapter=discord ./data

Allowlist variables are scope-aware and conjunctive within their scope. MOM_DISCORD_ALLOWED_USERS applies to every inbound message; guild and channel lists apply only to guild messages, while MOM_DISCORD_ALLOWED_DM_USERS applies only to DMs. Every applicable list that is set must match. An unset list adds no restriction, while a set-but-empty list denies that scope; for example, MOM_DISCORD_ALLOWED_DM_USERS='' denies all DMs before metadata, activity tracking, or workspace logging. A DM never needs its dynamic channel ID in MOM_DISCORD_ALLOWED_CHANNELS.

Gateway mode is never selected from credentials alone. Use the explicit CLI mode above, or set MOM_DISCORD_GATEWAY=true for environment auto-detection. When a public key is present and Gateway opt-in is absent, existing signed discord:webhook auto-detection is preserved. Large bots run one configured shard per process with both MOM_DISCORD_GATEWAY_SHARD_ID and MOM_DISCORD_GATEWAY_SHARD_COUNT.

Live model catalogs

Troublemaker restores Pi's cached provider catalogs at startup without network access. A long-running resident refreshes the authenticated openai-codex catalog in a bounded background pass, and explicit /model list or /model <name> requests await the same coalesced refresh. Successful public model metadata becomes discoverable immediately without changing the active model; selection still requires the existing explicit command or setting and takes effect on the next turn. PI_OFFLINE disables catalog network work while retaining Pi's already-restored cache.

Claude Code CLI Models

An existing Claude Code login can provide subscription-backed inference through claude -p. Troublemaker never performs this login itself. After the resident service user runs claude auth login, /model exposes claude-cli/{haiku,sonnet,opus,fable} and honors that user's Claude JSON settings. See docs/claude-cli-backend.md for the session, permission, delivery, and security contract.

Codex CLI Models

An existing Codex CLI login works the same way. After the service user runs codex login, select /model codex-cli/default (the CLI's built-in default model) or /model codex-cli/<model-id>. For a service, set MOM_MODEL_PROVIDER=codex-cli and MOM_MODEL_ID=default. Codex owns the inference loop and its native compaction, and Troublemaker exposes its live tools to Codex through an authenticated per-turn MCP bridge. See docs/codex-cli-backend.md.

Speech (speak tool)

The speak tool reads settings.json → speak, and any MOM_SPEAK_* env var overrides it:

Variable Description
MOM_SPEAK_ENABLED false disables the tool
MOM_SPEAK_BACKEND macos-say (say), command, http, elevenlabs, sag, noop, or disabled
MOM_SPEAK_VOICE, MOM_SPEAK_RATE, MOM_SPEAK_MAX_CHARS Voice, rate, and per-call text cap
MOM_SPEAK_COMMAND Command for the command backend
MOM_SPEAK_URL, MOM_SPEAK_TOKEN, MOM_SPEAK_TOKEN_HEADER, MOM_SPEAK_TOKEN_PREFIX Endpoint and auth for the http backend
MOM_SPEAK_ELEVENLABS_API_KEY, _VOICE_ID, _MODEL_ID, _OUTPUT_FORMAT elevenlabs backend (falls back to MOM_ELEVENLABS_*)
MOM_SPEAK_PLAYER_COMMAND Audio player for elevenlabs output
MOM_SPEAK_SAG_COMMAND, MOM_SPEAK_SAG_MODEL_ID, MOM_SPEAK_SAG_SHELL sag backend

Data Directory

The working directory is one unified workspace shared by every channel. Memory and history are not split per channel.

./data/
├── MEMORY.md              # Persistent memory (all channels)
├── memory/                # Daily notes (YYYY-MM-DD.md)
├── SOUL.md, IDENTITY.md,  # Workspace persona files, seeded from src/templates/
│   USER.md, AGENTS.md
├── HEARTBEAT.md           # Heartbeat checklist read on periodic wakes
├── BRIEF.md               # Current operator-assigned brief (if any)
├── goal.json              # Active persistent goal and its lifecycle state
├── settings.json          # Model, compaction, retry, and runtime preferences
├── log.jsonl              # Unified activity log across all channels
├── awareness/
│   ├── context.jsonl      # LLM context window
│   └── scratch/           # Agent working directory
├── attention/
│   ├── queue/             # Scheduled prompts that wake the agent
│   └── history/           # Fired/expired prompts with metadata
├── calendar/events/       # Calendar items shown in workspace clients
├── display/projects/      # Canvas/display projects shown in workspace clients
├── skills/                # CLI tools the agent creates (each has SKILL.md)
└── attachments/           # Files shared by users

Memory

The agent persists context in workspace files:

  • MEMORY.md: curated long-term memory, loaded into the system prompt on every turn.
  • memory/YYYY-MM-DD.md: raw daily notes the agent writes and periodically distills into MEMORY.md.

The agent updates these on its own as it learns. You can also edit them directly.

Skills

The agent can write custom CLI tools (skills) for your specific workflows. Each skill has a SKILL.md with frontmatter describing its name and purpose, plus any scripts or programs needed.

Skills live in the workspace skills/ directory, plus any extra directories passed with --skills. The agent sees all available skills in its prompt and reads the full SKILL.md when it decides to use one.

See pi-skills for example skills.

Events

The agent can schedule events that wake it up:

Type Trigger Use Case
Immediate On file creation Webhooks, external signals
One-shot At a specific time, once Reminders, scheduled tasks
Periodic Cron schedule Daily summaries, inbox checks

Event files go in data/attention/queue/; fired and expired events move to data/attention/history/. External systems can also write events there to wake the agent without going through a platform. A legacy data/events/ directory is still watched if it exists. When a host owns delayed schedules, it delivers them through POST /scheduled-prompt/inbound instead.

Runtime Features

Every channel feeds one resident agent with one workspace, so these features behave the same on Slack, Teams, email, the terminal, or voice.

Persistent goals

set_goal stores an explicit objective in goal.json. While a goal is active, the runtime keeps going with automatic continuation turns: ending one turn does not end the goal. The agent closes it with complete_goal once the work is achieved and verified, with abandon_goal when the user cancels or redirects, or with block_goal when the same blocker has repeated for at least three consecutive goal turns and only user input or an outside change can unblock it. A terminal run error also blocks continuation, so a failing goal cannot loop forever.

Heartbeat

A periodic heartbeat wake gives the agent a private moment to review context, read its HEARTBEAT.md checklist, and decide whether to act. The cadence comes from settings.json → spontaneity and is written as a periodic event in attention/queue/. The agent can reach out on a real channel with send_message or record a deliberate quiet with yield_no_action. That tool also ends ambient, duplicate, or agent-authored turns that need no reply.

Operator control

/operator/* is a headless control channel for whoever runs the fleet. It needs MOM_OPERATOR_INBOUND_TOKEN.

Route Effect
GET /operator/read Recent awareness backlog
GET /operator/describe Settings snapshot and HEARTBEAT.md
POST /operator/message Principal instruction; triggers a run
POST /operator/assign Writes BRIEF.md and starts work on it
POST /operator/configure Edits allowlisted settings: spontaneity, verbosity, model, thinking level, heartbeat checklist

Operator entries reach the agent tagged operator:control. The channel has no outbound path, so the agent replies on a real channel. The agent can change many of the same settings itself with self_configure when a user asks.

Attention queue and calendar

Scheduled prompts live in attention/queue/. Immediate and one-shot prompts move to attention/history/ once they fire; periodic (cron) prompts stay in the queue and reschedule after each fire. Calendar items in calendar/events/ and display projects in display/projects/ appear in workspace clients. The runtime seeds a README.md authoring guide in calendar/ and display/. See docs/events.md.

Context handoff and compaction

When context grows long, the runtime either compacts it natively or rotates it through handoff_context. The agent writes a bounded continuity summary, and a fresh context resumes from a completion receipt without redoing finished work. Rotations are journaled and replayed safely after a restart. See docs/context-handoff.md and docs/handoff-compaction.md.

Voice

  • /voice/realtime: a WebSocket for realtime speech sessions.
  • Voice adapter (port 8765) and web voice bridge (port 8766): browser mic → STT → agent → TTS.
  • speak tool: local or hosted text-to-speech (see Speech).

Natural follow-ups

Follow-up mode keeps one agent-global sequence of idle checkpoints after the latest eligible completed canonical wake. A later completed wake replaces the prior sequence, regardless of which durable conversation caused it. Each checkpoint is an internal headless wake with no inherited channel, conversation, or reply target: the agent reviews open loops across its channels, sends at most one concise follow-up to an explicitly chosen target with send_message, or stays quiet with yield_no_action. Ordinary assistant text and working output are discarded, and generated checkpoints never schedule another sequence.

Follow-ups are opt-in for every workspace, including newly seeded ones. The default preset enables checkpoints at 1, 3, 5, and 10 minutes and can be selected directly in settings.json:

{
  "followUps": "default"
}

Custom checkpoints use whole minutes:

{
  "followUps": {
    "enabled": true,
    "preset": "custom",
    "intervalsMinutes": [2, 6, 10]
  }
}

The agent can make the same durable changes with self_configure settings follow_ups, follow_ups.enabled, follow_ups.preset, and follow_ups.intervals_minutes. Setting follow_ups.cancel to true cancels current sequences without disabling the configured preset. /status reports pending sequences, scheduled and claimed wake counts, and the next wake time. Pending wake files and generation claims survive restart; overdue unclaimed wakes are rearmed after downtime of any length, while stale, claimed, and duplicate generations fail closed.

Security

The agent has full bash access in its execution environment. Use Docker sandbox mode to isolate it.

Docker mode (recommended): Commands run inside an isolated container. Only the mounted data directory is accessible from your host.

Host mode: Commands run directly on your machine with your user permissions. Only use in disposable environments.

The agent can be susceptible to prompt injection — treat it like a junior developer with terminal access. Use dedicated bot accounts with minimal permissions, scope credentials tightly, and never provide production secrets.

Deployment

Docker (recommended)

docker run -d --name sandbox -v $(pwd)/data:/workspace alpine:latest tail -f /dev/null

troublemaker --sandbox=docker:sandbox ./data

Docker Compose (VPS)

The repo ships a Dockerfile and a docker-compose.yml. The image builds Troublemaker from source on node:22-bookworm and adds Chromium plus Puppeteer browser tools:

# create agent.env with your model key and adapter tokens (see the compose file header)
docker compose up -d

The compose service mounts /data/agent as /data and runs --adapter=telegram:polling --sandbox=host --port=3002. Edit command: for other adapters. Uncomment ports: only when a webhook adapter needs inbound HTTP behind a trusted proxy.

VPS / Bare Metal

troublemaker --sandbox=host ./data

Development

corepack enable
pnpm install --frozen-lockfile
pnpm dev        # Watch mode
pnpm build      # Production build
pnpm typecheck  # tsc --noEmit

pnpm test runs every test file under test/, hostd/test/, and ui/test/ in parallel and lists all failures at the end (nonzero exit if any failed). Pass substrings to select files (pnpm test slack voice), --exclude <substring> to skip, -j <n> for concurrency, --list to print the files, or --help for all options.

The focused pnpm test:<area> scripts still work; see package.json for the full list. Run pnpm test:security-boundaries before changing any gateway, webhook, MCP, operator, or host-tool ingress. Run the adapter suite (test:slack-*, test:teams-*, test:discord-*, test:email-*, and so on) for any adapter you touch.

Code Structure

  • src/main.ts — Thin bin shim; imports the Node host entry point
  • src/host/node/cli.ts — Real entry point: CLI args, adapter auto-detection and creation, gateway route registration, startup
  • src/host/node/ — Node host services: adapter route table (adapter-route-identity.ts), terminal upgrade, Deepgram/ElevenLabs voice sessions, owner push, device grants
  • src/gateway.ts — Unified HTTP server: path-based routing, readiness gating, loopback-only bind, file/awareness/session APIs
  • src/agent.ts — Agent runner: createRunner wires the Pi Agent/AgentSession and implements run, steer, abort, compact, clear
  • src/runner/ — Runner building blocks: per-run state and output queue (run-state.ts), session event handling and tool progress (session-events.ts), provider stream boundary (stream-fn.ts), handoff tool/extension and private checkpoints (handoff.ts, private-checkpoint.ts), compaction tracking (compaction.ts), context transitions, live presentation, user-turn assembly, outcome delivery, skills loading, and context-file archiving
  • src/adapters/ — Platform adapters, one or more files per platform
    • types.ts — PlatformAdapter interface
    • slack-*.ts — Socket Mode, webhook, reactions, native/batched tool progress
    • teams-*.ts — Bot Connector webhook, targets, formatting
    • discord-*.ts — Gateway WebSocket and Interactions webhook
    • telegram-*.ts — Polling and webhook
    • mattermost-socket.ts, rocket-chat-webhook.ts, zulip-webhook.ts — Team chat
    • email-webhook.ts, email/ — Email
    • phone-messaging-webhook.ts, phone-messaging/ — SMS/iMessage providers (Loop, Twilio, host-managed)
    • form-webhook.ts, web.ts, mcp.ts — Website forms, web chat, MCP Streamable HTTP
    • voice*.ts, web-voice.ts, realtime-voice.ts — Voice adapters and bridges
    • operator.ts, heartbeat.ts, scheduled-prompt-webhook.ts — Fleet control, periodic wakes, host-owned delayed prompts
  • src/tools/ — Agent tools: bash, read, write, edit, attach, send_message, react_to_message, list_channels, read_thread, self_configure, goals (set_goal, complete_goal, block_goal, abandon_goal), yield_no_action, handoff_context, speak, imagegen, search_tools, Gmail, domains, and site deploy
  • src/core/ — Prompt assembly, routing, runtime contract, tool definitions, input budget
  • src/streaming/ — Live turn snapshots, working output, steering and tool-delivery projections
  • src/console/ — Portable-client console service: conversation projection, voice sessions, transcription, owner review
  • src/tui/ — troublemaker-tui terminal client
  • src/modes/ — Edge and host execution modes
  • src/mcp-client/ — Bridge for external MCP servers' tools
  • src/cua-driver/ — Computer-use bridge (@trycua/cua-driver)
  • src/storage/, src/store.ts — Workspace, awareness, events, settings and channel persistence
  • src/context.ts — Runtime settings (compaction, retry, model preferences); the runner is the sole writer of context.jsonl
  • src/sandbox.ts — Docker/host sandbox execution
  • src/events.ts — Scheduled events watcher
  • src/templates/ — Bootstrap workspace files (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, BOOTSTRAP.md)

Acknowledgments

Troublemaker is built on mom by Mario Zechner. The agent core — tool execution, context management, memory, skills, compaction — is mom's work. Troublemaker adds multi-platform adapters and a unified gateway.

License

MIT

About

Multiplatform AI agent runtime.

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages