Multiplexed Vibes with tmux-mcp
I started using tmux in 2018 (?) and I never looked back. I typically have 5-6 different tmux sessions at any given time. Each with a different context: a web server, logs I’m monitoring, or simply neovim.
(If you don’t know what’s tmux, check this out)
When I started using Claude as my personal “tuttofare” (italian expression for handyman that can do everything), I quickly found myself bored by copying and pasting terminal content or taking screenshots just to give Claude the context it needed. I thought: “There must be a better way to connect these worlds.”
And here we are! tmux-mcp grew out of this discomfort. A simple but powerful bridge that connects Claude AI directly to your tmux sessions, eliminating that tedious back-and-forth.
Show me the code! Here’s the repo.
What Is tmux-mcp?
tmux-mcp is an implementation of Model Context Protocol (MCP) that enables Claude (and possibly any other AI assistant) to:
- View and navigate your tmux sessions, windows, and panes
- Capture and analyze terminal output in real-time
- Execute commands on your behalf (when you permit it) and get the result back
- Create new tmux sessions and windows programmatically
But there is more!
- Panes’ content are treated as resources: every tmux pane’s content can be attached to your chat context, making it instantly visible to Claude.
- Same for command results: when Claude executes a command in a tmux pane, its results also become a resource that can be attached to the conversation (it’s available for 10 minutes).
This means Claude can now see what you’re seeing in your terminal, understand the context of your work, and provide more targeted assistance without you having to copy and paste terminal output.
How It Works
The secret sauce behind tmux-mcp is Anthropic’s protocol for connecting AI assistants to external systems. Explaining how it works is outside the scope of this blog post, you can find a good introduction here.
At high level, the MCP server acts as a “translator” between tmux and the Claude, exposing tmux’s functionality through standardized MCP resources and tools. When you ask Claude about something happening in your terminal, it can query the appropriate tmux pane, read the content, and analyze it - all seamlessly (you can read more on how to build a custom MCP here).
Use Cases
Debugging
Imagine you’re debugging a crash in your web application. Instead of copying and pasting error logs to Claude, you can simply ask: “Claude, can you help me understand what’s causing the crash in my web app? It’s in session ‘webapp’“. Claude can now look at your terminal output, understand the context, and provide a more informed analysis.
Guided Command Execution
Working with unfamiliar tools or commands? Let Claude help: “I need to parse this JSON log file and extract all events with status ‘error’. Can you help me craft the command?”
Claude can suggest a command and, with your permission, execute it in the appropriate pane and analyze the results.
Pair Programming
Uncle Claude can access your terminal output by attaching the pane to the chat and provide contextual suggestions:
“I can see from your terminal that the command failed. You typed git comit instead of git commit. Try running it again with the correct spelling.”
Security Considerations
The ability to execute commands is powerful but comes with responsibilities. With tmux-mcp, Claude can suggest commands to run in your terminal, and if you approve, the MCP server will execute them directly in the specified pane. It’s important to understand that:
- You should carefully review any command Claude suggests before approving its execution
- You maintain control by choosing whether to approve command execution
- Commands are sent directly to the specified tmux pane after the approval
- All executed commands and their outputs remain visible in your terminal history
Conclusion
I’m still tweaking and testing tmux-mcp to see if it fits my workflow, but this MCP has some potential: no more copy/pasta or screenshots - just seamless collaboration.
I hope other tmux fans will find this small project useful in their daily work. Give it a try, and let me know what you think, feedback are always welcome. Happy hacking 🤖!