tmuxplus

Discord bot that gives each channel its own tmux session running an AI CLI agent (Claude Code, Codex, Gemini, etc.).

You talk in Discord. The agent works in tmux. Replies come back to Discord.

User → Discord → tmuxplus → tmux session → AI agent
                                              ↓
User ← Discord ← tmx discord-send ←──────────┘

Install

npm i -g tmuxplus

Requires: Node.js >= 22, tmux, at least one AI CLI agent (e.g. claude)

Setup

mkdir my-bot && cd my-bot
tmx init       # creates config.yml + installs skills

Edit config.yml:

discord_token: "your-bot-token-here"
register_guild_id: "your-server-id"    # optional, for instant slash command registration

agents:
  claude: "claude --dangerously-skip-permissions"
  # codex: "codex --dangerously-bypass-approvals-and-sandbox"
  # grok: "grok --permission-mode=bypassPermissions"
  # gemini: "gemini --approval-mode=yolo"

Discord bot setup

1. Go to Discord Developer Portal
2. Create Application → Bot
3. Enable Privileged Gateway Intents: Presence, Server Members, Message Content
4. Copy bot token → paste in .env
5. Invite bot to your server with the OAuth2 URL (Bot scope + Administrator permission)

Run

tmx start

For persistent deployment (survives terminal close):

tmux new-session -d -s my-bot && tmux send-keys -t my-bot 'tmx start' Enter

Usage

Once the bot is running in your Discord server:

1. Type messages in any registered channel — sent to the agent immediately
2. Attach images/files — saved to .uploads/ and the agent reads them via path
3. The agent replies back in Discord via tmx discord-send

Projects

Create a project to group related rooms under one Discord category with a shared workspace:

/project create name:myapp dir:/home/user/myapp

Then create channels inside the project category — each gets its own agent session sharing the workspace.

Discord Slash Commands

| Command | Description | |---------|-------------| | /boot | Boot agent with tmuxplus skills (this channel or all rooms) | | /clear | Clear agent conversation + re-boot with skills | | /esc | Send Ctrl+C to stop agent's current task | | /enter | Send Enter to submit stuck input | | /summary [action] [message] | Write session summary (write/done); optional message appended to the prompt | | /status | Show tmux session info for this channel | | /pwd | Show this room's workspace directory | | /cd path:<path> [silent:true] | Change workspace dir + send the agent a cd notice (tmux session kept) | | /rename name:<new> | Rename room + Discord channel + tmux session | | /master | Register this channel as the master room | | /version | Show tmuxplus version | | /help | Show all available commands | | /acl add\|remove\|list | Manage bot allowlist (owner only) | | /project create\|list\|info\|edit\|delete | Manage projects | | /cron create\|list\|read\|update\|delete | Manage scheduled cron jobs |

CLI Commands

Every Discord slash command has a CLI equivalent — agents in tmux can manage rooms without going through Discord:

# System
tmx init                                     # Create .env, skills, workspace/
tmx start                                    # Run the bot
tmx update [--skip-npm]                      # Update npm package + skills
tmx --version                                # Show version

# Messaging
tmx discord-send "msg" [-c ch] [-r id] [-f file]   # Send to Discord
tmx send [project/room] "msg" [-c ch] [-s session]   # Send raw text to agent's tmux
tmx hey <project>/<room> "msg" [-f file] [--raw]     # Message another agent

# Room management
tmx rooms                                    # List all rooms with status
tmx status [-c ch] [--all]                   # Show session info
tmx new <name> [--agent codex] [--dir /path] # Create room
tmx delete [-c ch] [--keep-tmux]             # Unregister room
tmx rename <name> [-c ch]                    # Rename room + channel
tmx pwd [project/room]                       # Show a room's workspace dir
tmx cd <path> [project/room] [--silent]      # Update workspace + notify agent (session kept)

# Session control
tmx boot [-c ch] [--all]                     # Boot agent(s) with skills
tmx clear [-c ch]                            # Clear agent + boot with skills
tmx esc [-c ch] [--all]                      # Send Ctrl+C to stop agent
tmx enter [-c ch] [--all]                    # Send Enter to submit stuck input
tmx summary [project/room] [start|done] [-m "<msg>"]  # write summary / clear+boot+load

# Projects
tmx project create <name> --dir <path>       # Create project
tmx project list                             # List projects
tmx project info <category-id>               # Show details
tmx project edit <id> --dir <path>           # Update workspace
tmx project delete <id> [--rooms]            # Delete project

# Cron (scheduled jobs)
tmx cron list                                # List all cron jobs
tmx cron create --agent <project/room> --cron '<expr>' [--command '<cmd>'] [--message '<msg>']
tmx cron read <id>                           # Show a cron job
tmx cron update <id> [--field value]...      # Update a cron job
tmx cron delete <id>                         # Delete a cron job

All commands auto-detect the current channel from the tmux session environment (-c is optional when running inside a room's tmux session). Commands like tmx hey and tmx summary also accept a project/room target (e.g. master/master), so you can target any room from anywhere — no need to be inside its session or know the raw channel ID.

Agent Skills

tmuxplus installs skills to ~/.claude/skills/ and ~/.agents/skills/ that teach agents how to interact with the system:

| Skill | Purpose | |-------|---------| | tmx-boot | Boot sequence — introduces the agent to tmuxplus | | tmx-discord | How to reply via tmx discord-send, formatting, progress updates | | tmx-hey | Agent-to-agent messaging via tmx hey | | tmx-commands | Full tmx CLI reference | | tmx-summary | Write session summaries to .summary/ | | tmx-cron | Manage scheduled cron jobs via tmx cron |

Skills are installed/updated automatically via tmx init, tmx update, and tmx boot.

Scheduled Jobs (Cron)

Run tasks on a schedule — app-level, no OS cron needed. Stored in crons.yml and hot-reloaded on change.

# Send a message to an agent every hour
tmx cron create --agent master/master --cron '0 * * * *' --message 'สวัสดีครับ เป็นไงบ้าง'

# Run a command every 30 minutes
tmx cron create --agent master/master --cron '*/30 * * * *' --command 'tmx summary master/master'

# List / update / delete
tmx cron list
tmx cron update <id> --cron '*/10 * * * *'
tmx cron delete <id>

Agent-to-Agent Messaging

Agents can communicate across rooms:

# From any agent's tmux session
tmx hey hydra/monitor "check error logs"
tmx hey master/master "task complete" -f /tmp/report.txt

Messages show up in both the target agent's tmux and the target's Discord channel.

License

MIT