🛠️ Murtaugh

Your Slack-native AI agent and developer toolkit — chat, automations, jobs, and link previews, in a single Go binary.

Murtaugh turns Slack into a first-class developer surface. It is a single, self-contained binary that connects to your workspace over Socket Mode and adds:

• 💬 AI chat — DM the bot or @mention it; a built-in native LLM agent (or any ACP-compatible agent) streams its reply back into the thread.
• 🔘 Workflow rules — react to Block Kit button clicks and form submissions with templated replies, shell commands, or agent delegation.
• 🔗 Link unfurling — replace bare URLs with rich Block Kit previews.
• ⏰ Jobs — run shell commands or agents on demand or on a cron/interval.
• 🔍 Gateway Debug Mode — every interaction is recorded as a structured, queryable event so you (or an agent) can ask "why did that misbehave?".
• 🧰 CLI + MCP server — every capability is a terminal command and an MCP tool exposed to other AI clients.

---

Quick start

macOS — the installer downloads the right binary, seeds your config, and optionally installs the background daemon:

curl -fsSL https://github.com/miere/murtaugh/releases/latest/download/install_macos.sh | bash

From source (requires Go 1.26+):

git clone https://github.com/miere/murtaugh.git
cd murtaugh
go build -o murtaugh ./cmd/murtaugh

Then create a Slack app, fill in your config, and start the gateway:

murtaugh slack gateway

👉 Full walkthrough: Getting started.

---

Documentation

Guide	What it covers
🚀 Getting started	Install, create the Slack app, write the config, first run.
⚙️ Configuration	config.yaml (oauth + database), the .env secrets, and the murtaugh cfg admin CLI for everything else.
🤖 Agent chat	Native vs ACP agents, tools, routing, streaming, interrupts, approval.
💬 Slack	Messaging, asking the user, Block Kit, workflow rules, and link unfurling.
⏰ Jobs	Define, run, and schedule shell-command and agent jobs.
🔍 Gateway Debug Mode	Query the structured event journal to debug and audit Murtaugh.
🧰 CLI & MCP server	Call any tool from the terminal or expose them over MCP.
🛟 Operations	Run the daemon, restart it, read its logs, and troubleshoot.
🏗️ Architecture	Internal design, package layout, and data flow.

---

How it fits together

                       ┌──────────────────────────────┐
   Slack workspace ◄──►│   murtaugh slack gateway      │
   (Socket Mode)       │   the long-lived daemon       │
                       │                               │
   • slash commands    │   • chat   → agent (native /  │──► LLM provider
   • @mentions / DMs    │             ACP), streamed    │    or ACP process
   • button clicks     │   • workflow rules            │
   • shared links      │   • link unfurls              │──► journal (SQLite)
                       │   • job scheduler             │
                       └──────────────────────────────┘
                          ▲                        ▲
                          │                        │
                 murtaugh <tool>            murtaugh mcp
                 (CLI, one-shot)         (MCP server, stdio)

Every capability is registered as a tool with one definition, surfaced three ways: as a Slack interaction, a CLI command, and an MCP tool. See ARCHITECTURE.md for the details.

---

Contributing

1. Fork the repository and create a feature branch.
2. Run go build ./..., go vet ./..., and go test ./... before opening a PR.
3. Follow the conventions in ARCHITECTURE.md.

History is kept linear — rebase your branch, don't merge main into it.