loop

Loop

A Discord bot powered by Claude that runs AI agents in Docker containers.

Architecture

                   Discord
                     │
              @mention / reply / !loop / DM
                     ▼
                    Bot
                     │
                     ▼
               Orchestrator ◀──────────────── Scheduler (poll loop)
                     │                              │
            build AgentRequest              due task? execute it
            (messages + session +           (cron / interval / once)
             channel dir_path)                      │
                     │                              │
                     ▼                              ▼
               DockerRunner ◄───────────────────────┘
                     │
          ┌──────────┴──────────┐
          │  create container   │
          │  mount dir_path or  │
          │  ~/.loop/<ch>/work  │
          │  (path-preserving)  │
          └──────────┬──────────┘
                     ▼
              Container (Docker)
          ┌─────────────────────┐
          │ claude --print      │
          │   workDir (project) │
          │   mcpDir  (logs)    │
          │   MCP: loop
          └─────────┬───────────┘
                    │
         MCP tool calls (schedule, list, cancel…)
                    ▼
              API Server ◀──▶ SQLite

• Orchestrator coordinates message handling, channel registration, session management, and scheduled tasks
• DockerRunner mounts the channel's dir_path (falling back to ~/.loop/<channelID>/work) at its original path inside the container, then runs claude --print
• Scheduler polls for due tasks (cron, interval, once) and executes them via DockerRunner
• MCP Server (inside the container) gives Claude tools to schedule/manage tasks — calls loop back through the API server
• API Server exposes REST endpoints for task and channel management
• SQLite stores channels, messages, scheduled tasks, and run logs

Prerequisites

• macOS (recommended) or Linux
• Docker Desktop (macOS) or Docker Engine (Linux)
• A Discord bot token and application ID (create one)
• An Anthropic API key or Claude Code OAuth token (for agent containers)

Note: loop daemon:start/stop/status use launchd (macOS-only). On Linux, use loop serve directly.

Getting Started

Step 1: Install

# Homebrew
brew install radutopala/tap/loop

# Or from source
go install github.com/radutopala/loop/cmd/loop@latest

Step 2: Create a Discord bot

1. Go to https://discord.com/developers/applications and create a new application

2. Under Bot, copy the Bot Token

3. Under Bot → Privileged Gateway Intents, enable Message Content Intent

4. Copy the Application ID from the General Information page

5. Invite the bot to your server (replace YOUR_APP_ID):

   https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot%20applications.commands&permissions=68624
   

   This grants: View Channels, Send Messages, Read Message History, Manage Channels (for auto-creating project channels).

Step 3: Initialize global config

loop onboard:global

This creates:

• ~/.loop/config.json — main configuration file
• ~/.loop/container/Dockerfile — agent container image definition
• ~/.loop/container/entrypoint.sh — container entrypoint script

Step 4: Add your credentials

Edit ~/.loop/config.json and fill in the required fields:

{
  // Required
  "discord_token": "your-bot-token-from-step-2",
  "discord_app_id": "your-app-id-from-step-2",

  // Optional — enables auto-creation of Discord channels via `loop mcp --dir`
  "discord_guild_id": "your-discord-guild-id"
}

The config file uses HJSON (comments and trailing commas are allowed). See config.global.example.json for all available options and their defaults.

Step 5: Start Loop

# Run directly (auto-builds the agent Docker image on first run)
loop serve

# Or run as a background daemon (macOS only)
loop daemon:start
loop daemon:status   # check status
loop daemon:stop     # stop

Step 6: Set up a project (optional)

To use Loop with a specific project directory:

cd /path/to/your/project
loop onboard:local
# optionally: loop onboard:local --api-url http://custom:9999

This does three things:

1. Writes .mcp.json — registers the Loop MCP server so Claude Code can schedule tasks from your IDE
2. Creates .loop/config.json — project-specific overrides (mounts, MCP servers, model)
3. Registers a Discord channel for this directory (requires loop serve to be running)

Configuration Reference

Global Config (~/.loop/config.json)

Container Mounts

The mounts array mounts host directories into all agent containers. Format: "host_path:container_path[:ro]"

"mounts": [
  "~/.claude:~/.claude",                      // Claude sessions (writable)
  "~/.gitconfig:~/.gitconfig:ro",             // Git identity (read-only)
  "~/.ssh:~/.ssh:ro",                         // SSH keys (read-only)
  "~/.aws:~/.aws",                            // AWS credentials (writable)
  "/var/run/docker.sock:/var/run/docker.sock"  // Docker access
]

• Paths starting with ~/ are expanded to the user's home directory
• Non-existent paths are silently skipped
• The Docker socket's GID is auto-detected and added to the container process
• Project directories (workDir) and MCP logs (mcpDir) are always mounted automatically at their actual paths

Per-Project Config ({project}/.loop/config.json)

Project config overrides specific global settings. Only these fields are allowed:

Relative paths in project mounts (e.g., ./data) are resolved relative to the project directory.

{
  "mounts": [
    "./data:/app/data",              // Relative to project dir
    "~/.claude:~/.claude",           // Home expansion works
    "/absolute/path:/app/external"   // Absolute paths too
  ],
  "mcp": {
    "servers": {
      "project-db": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres"],
        "env": {"DATABASE_URL": "postgresql://localhost/projectdb"}
      }
    }
  }
}

Container Image

The agent Docker image is auto-built on first loop serve / loop daemon:start if it doesn't exist. The Dockerfile and entrypoint are embedded in the binary and written to ~/.loop/container/ during loop onboard:global.

To customize: edit ~/.loop/container/Dockerfile, then docker rmi loop-agent:latest and restart.

For development: make docker-build builds from container/Dockerfile in the repo.

CLI Commands

MCP Server Options

loop mcp --channel-id <id> --api-url <url>   # Attach to existing channel
loop mcp --dir <path> --api-url <url>        # Auto-create channel for directory

Using with Claude Code

loop mcp is the same MCP server used in both contexts:

• On the host — registered in your local Claude Code so you can schedule tasks from your IDE
• Inside containers — automatically injected into every agent container so scheduled tasks can themselves schedule follow-up tasks

When using --dir, Loop automatically registers a channel (and creates a Discord channel in the configured guild) for that directory. The project directory is then mounted at its original path inside agent containers.

To register it in your local Claude Code, run loop onboard:local in your project directory. This writes a .mcp.json file that Claude Code auto-discovers:

cd /path/to/your/project
loop onboard:local
# optionally: loop onboard:local --api-url http://custom:9999

Discord Commands

The bot also responds to @mentions, replies to its own messages, and messages prefixed with !loop.

Task Templates

The config.json file can include a task_templates array with reusable task patterns. Use /loop template add <name> in Discord to load a template as a scheduled task in the current channel. Templates are idempotent — adding the same template twice to a channel is a no-op.

Example templates in config.json:

{
  // ... other config ...

  "task_templates": [
    {
      "name": "tk-auto-worker",
      "description": "Automatically work on ready tickets from tk queue",
      "schedule": "*/5 * * * *",
      "type": "cron",
      "prompt": "Check the tk ticket queue with 'tk ready'. Find any tickets that are marked as ready to start. If you find a ready ticket, use 'tk start <id>' to begin working on it, implement the solution following the ticket's requirements, and when complete use 'tk close <id>' to mark it as done. If no tickets are ready, report the current queue status."
    },
    {
      "name": "daily-summary",
      "description": "Generate a daily summary of completed tickets",
      "schedule": "0 17 * * *",
      "type": "cron",
      "prompt": "Generate a summary of all tickets closed today using 'tk list --status=closed'. Include ticket IDs, titles, and brief descriptions of what was accomplished."
    }
  ]
}

To use a template, copy its schedule, type, and prompt values into the /loop schedule command in Discord.

REST API

MCP Tools

Development

Requires Go 1.25+.

make build            # Build the loop binary
make install          # Install to $GOPATH/bin
make docker-build     # Build the Docker agent image (from local source)
make restart          # Reinstall + restart daemon
make test             # Run tests
make lint             # Run linter
make coverage-check   # Enforce 100% test coverage
make coverage         # Generate HTML coverage report
make clean            # Remove build artifacts

License

This project is licensed under the GNU General Public License v3.0.