cotty MCP server
Commit Nov 9, 2026Shares a terminal session between a user and an AI agent, allowing the agent to read output and type commands via SSH or serial consoles.
Also known as winebarrel/cotty
- Stars
- 1
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- CC0-1.0
What is cotty MCP?
cotty shares a terminal session between a user and an AI agent, allowing the agent to read output and type commands via SSH or serial consoles. It exposes 4 tools, such as list_sessions, send, send_key.
Summary generated from the project's README
About cotty MCP server
Sharing a terminal session between a human and an AI agent is what cotty enables through a synchronized environment. By using the wrap command, you can run tools like ssh or serial console commands such as picocom, creating a session that both you and an agent can interact with simultaneously. The agent uses the mcp command to access the session via stdio, allowing it to read command output and type inputs directly into the terminal.
Developers can manage security and privacy using specific flags and key bindings. You can start a session in read-only mode to prevent the agent from typing, or use the redact flag with regular expressions to replace sensitive strings with redacted placeholders. If you need to hide specific output like a password, you can pause the output to the agent using a keyboard shortcut. This setup works with Claude Code via a plugin or other agents using skills, providing tools to list sessions, send text, press special keys, and read terminal output.
What you can do with it
- 1Remote server maintenanceAsk an AI agent to check disk usage or manage files on a remote machine via an active SSH session.
- 2Hardware debuggingUse a serial console to let an agent observe and interact with hardware via a device like a usbserial.
- 3Secure command executionRun a session where the agent can only view output but cannot type any commands.
- 4Sensitive data protectionAutomatically hide specific patterns like API tokens from the agent's view using regular expressions.
Written from the project's README. Every use case is checked against a quote from it.
cotty MCP tools 4
Detected from the READMElist_sessionssendsend_keyread
Configuration
COTTY_REDACT
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablewinebarrel/cotty is public and reachablegithub.com/winebarrel/cotty ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)CC0-1.0spdx.org/licenses/CC0-1.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/winebarrel/cotty ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcotty
cotty shares a terminal session between you and an AI agent.
You start a command such as ssh or a serial console under cotty wrap and use it as usual. The agent reads the same output and types into the same session through an MCP server, cotty mcp. Both of you can type at any time, and you can deny the agent's input or hide the output from it with a key.
[your terminal] [agent, e.g. Claude Code]
cotty wrap -n web1 ssh web1 | stdio
runs ssh in a pty cotty mcp
listens on ~/.cotty/sock/web1.sock <-------'
Installation
go install github.com/winebarrel/cotty/cmd/cotty@latest
Or download a binary from the releases.
Agent setup
The agent needs the MCP server, cotty mcp, and preferably the cotty skill, which tells it how to work in a session: waiting for prompts, avoiding full-screen programs, asking before changing anything, and never typing passwords.
For Claude Code, install the plugin. It registers the MCP server and adds the skill:
claude plugin marketplace add winebarrel/cotty
claude plugin install cotty@cotty
For other agents, install the skill with skills and register the MCP server with the agent. For Codex:
npx skills add winebarrel/cotty -a codex
codex mcp add cotty -- cotty mcp
For any other MCP client, the server is the command cotty with the argument mcp.
Usage
Start a session with a name:
cotty wrap -n web1 ssh web1.example.com
cotty wrap -n board picocom -b 115200 /dev/tty.usbserial-0001
Then ask the agent to work in the session, for example "check the disk usage on web1".
Flags of cotty wrap go before the command; everything from the command on is passed to it as is.
Options
| Flag | Environment variable | Default | Description |
|---|---|---|---|
--home |
COTTY_HOME |
~/.cotty |
Directory for session sockets and logs. |
wrap --buffer-size |
COTTY_BUFFER_SIZE |
1MiB |
How much recent output to keep for the agent to read. |
wrap --redact |
COTTY_REDACT |
Text to show as [REDACTED] to the agent and in the log. Between slashes, as in /token=\S+/, it is a regular expression. Repeat the flag for more, or put one per line in the environment variable. |
|
wrap -r, --read-only |
COTTY_READ_ONLY |
false |
Start with the agent's input denied. Ctrl-] a allows it. |
mcp --read-max |
COTTY_READ_MAX |
32KiB |
Most output one read returns. Older output beyond it is dropped. |
mcp --tail-lines |
COTTY_TAIL_LINES |
50 |
Lines a read returns when it has no previous read to continue from. |
mcp --timeout |
COTTY_TIMEOUT |
30s |
How long a read waits when the agent does not say. |
mcp --max-timeout |
COTTY_MAX_TIMEOUT |
10m |
Longest wait the agent may ask a read for. |
Sizes take a unit of B, K, KB, KiB, M, MB or MiB, all powers of 1024. To change the mcp options, set the environment variables for the agent, or pass the flags when you register the server yourself:
codex mcp add cotty -- cotty mcp --read-max 64KiB --max-timeout 30m
To hide several strings in every session, list them in COTTY_REDACT, one per line:
export COTTY_REDACT='hunter2
/token=\S+/'
Usage: cotty <command> [flags]
Share a terminal session with an AI agent.
Flags:
-h, --help Show context-sensitive help.
--version
--home="~/.cotty" Directory for session sockets and logs ($COTTY_HOME).
Commands:
wrap --name=STRING <command> ... [flags]
Run a command in a terminal shared with the agent.
mcp [flags]
Serve the sessions to an agent over MCP on stdio.
Key bindings
| Keys | Action |
|---|---|
Ctrl-] a |
Allow or deny the agent's input (allowed at start unless --read-only) |
Ctrl-] p |
Pause or resume the output to the agent and the log |
Ctrl-] k |
Kill the command with SIGKILL, which ends the session |
Ctrl-] ? |
Show help |
Ctrl-] Ctrl-] |
Send Ctrl-] to the command |
MCP tools
| Tool | Description |
|---|---|
list_sessions |
List the running sessions. |
send |
Type text into a session, followed by Enter unless enter is false. |
send_key |
Press a special key such as ctrl-c, up or tab. |
read |
Read the output that arrived since the previous read, as plain text. wait_for waits for a regular expression, idle_ms waits for the output to settle, and tail_lines returns the last lines instead. |
To confirm each input while letting the agent read freely, allow only the read-only tools in Claude Code's permissions. With the plugin, the tools are named as follows:
{
"permissions": {
"allow": ["mcp__plugin_cotty_cotty__list_sessions", "mcp__plugin_cotty_cotty__read"]
}
}
Files
~/.cotty/sock/<name>.sock: the session socket, removed when the session ends. Only you can connect to it.~/.cotty/log/<name>-<YYYYMMDD-HHMMSS>.log: the session output as plain text, with escape sequences removed.
The command runs with COTTY_SESSION=<name> in its environment.
Notes
- The agent sees the output from the start of the session, up to
--buffer-size. The log keeps all of it. - Passwords you type at a prompt that turns echo off, as
sshandsudodo, never appear in the output, so the agent does not see them. - With
--redact, the agent and the log get[REDACTED]in place of what matches, while your terminal shows it as it is. The agent is told how many strings the session hides. A match does not span lines. A keyword cut off at the end of the output is held back from the agent until the rest arrives. A regular expression cannot be held back that way, so what arrived before the match was complete, such as the start of a secret you type with echo on, may reach the agent; useCtrl-]pfor that. - To show something the agent should not see, such as a password typed with echo on or a file with secrets, press
Ctrl-]pfirst and again when done. Until then the output is shown only on your terminal: it is kept neither for the agent nor in the log, and the agent is told that the output is paused.
cotty MCP questions
What tools does cotty MCP provide?
It exposes 4 tools, including list_sessions, send, send_key, read.
Can I prevent the AI agent from seeing sensitive information?
Yes, you can use the --redact flag with regular expressions to replace sensitive text with [REDACTED], or use the Ctrl-] p key binding to pause output to the agent.