zsh-tool — Claude Code MCP server: what it does, how to install
Runs native Zsh sessions with PTY support and hanging-process prevention. Handles interactive password prompts and terminal deltas.
claude mcp add --env ALAN_DB_PATH=<ALAN_DB_PATH> --transport stdio zsh-tool -- uvx zsh-tool-mcpWhat zsh-tool does
Default Bash executors frequently stumble over Zsh syntax and quoting conventions. That causes unnecessary debug loops that waste tokens. This server executes commands directly inside Zsh. Its PTY mode creates a pseudo-terminal, allowing the assistant to handle interactive prompts and enter credentials.
Long-running commands do not freeze the session. Execution yields after a selected duration, returning partial output. You can then collect incremental lines via zsh_poll instead of dumping whole logs. If a command times out three times in a rolling hour, the NEVERHANG circuit breaker cuts it off for 5 minutes.
Telemetry and command history write to SQLite via the A.L.A.N. engine. Without setting the ALAN_DB_PATH environment variable, session history resets on restart.
What it helps with
- run native Zsh commands without escaping or quotation mismatches
- enter passwords and handle interactive prompts via PTY mode
- break hanging processes with the NEVERHANG circuit breaker
- stream only new console lines using
zsh_polldelta checks
Example prompts for the agent
- Run
pass insert mypassusing PTY mode and supply the password when prompted. - Start
pip install .withyield_afterset to 5 seconds and poll new output. - List all background tasks using
zsh_tasks.
How to install zsh-tool
Platform CLI
claude mcp add --env ALAN_DB_PATH=<ALAN_DB_PATH> --transport stdio zsh-tool -- uvx zsh-tool-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zsh-tool-mcp <command>
Platform CLI
codex mcp add zsh-tool --env ALAN_DB_PATH=<ALAN_DB_PATH> -- uvx zsh-tool-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zsh-tool-mcp <command>
Config file
{
"mcpServers": {
"zsh-tool": {
"command": "uvx",
"args": [
"zsh-tool-mcp"
],
"env": {
"ALAN_DB_PATH": "<ALAN_DB_PATH>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zsh-tool-mcp <command>
Config file
{
"servers": {
"zsh-tool": {
"type": "stdio",
"command": "uvx",
"args": [
"zsh-tool-mcp"
],
"env": {
"ALAN_DB_PATH": "<ALAN_DB_PATH>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zsh-tool-mcp <command>
Platform CLI
gemini mcp add -e ALAN_DB_PATH=<ALAN_DB_PATH> zsh-tool uvx zsh-tool-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zsh-tool-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about zsh-tool
How to install zsh-tool in Claude Code?
Run claude mcp add zsh-tool -- uvx zsh-tool-mcp. If you want to keep the A.L.A.N. SQLite history file, pass the path variable: claude mcp add --env ALAN_DB_PATH=<ALAN_DB_PATH> --transport stdio zsh-tool -- uvx zsh-tool-mcp.
What does zsh-tool do?
It equips Claude Code with a native Zsh runner supporting pseudo-terminals and task control. It prevents session lockups through yield execution and the NEVERHANG breaker.
How does PTY mode work in zsh-tool?
Setting pty: true creates a pseudo-terminal that merges standard streams and supports programs requiring a real TTY. You can feed answers to prompts using zsh_send.
