Provides yield-based, PTY-capable shell execution with intelligent feedback and reliability safeguards for Claude Code.
Configuration
View docs{
"mcpServers": {
"arktechnwa-zsh-tool": {
"command": "/path/to/zsh-tool/scripts/run-mcp.sh",
"args": [],
"env": {
"ALAN_DB_PATH": "/var/lib/zsh-tool/alan.db",
"NEVERHANG_TIMEOUT_MAX": "600",
"NEVERHANG_TIMEOUT_DEFAULT": "120"
}
}
}
}You will use the zsh-tool MCP server to execute and manage shell commands with enhanced control, interactive support, and automatic safeguards. It provides yield-based execution, PTY-like interactivity, a NEVERHANG circuit breaker, and intelligent feedback through A.L.A.N. learning, making it reliable to run commands inside Claude Code without hanging or confusion.
You can run arbitrary shell commands through the MCP server and interact with them as they execute. Use yield-based execution to get partial outputs and regain control, poll for more progress, and send input when prompts appear. Take advantage of PTY mode for full terminal interaction so programs that require a TTY behave correctly, including color output and prompt handling. When commands timeout or misbehave, the NEVERHANG circuit breaker prevents blocks and auto-recovers after a brief pause. A.L.A.N. 2.0 adds short-term learning, offering contextual feedback, retry detection, and per-session memory to help you optimize command runs.
Prerequisites: a host with Python and a compatible runtime, plus access to Claude Code with MCP support. You will install and run an MCP server wrapper that provisions a virtual environment and makes the MCP endpoints available.
From Marketplace (recommended): - Add the ArkTechNWA marketplace to Claude Code: ArkTechNWA/claude-plugins - Install the zsh-tool MCP: /plugin install arktechnwa/zsh-tool - The plugin auto-installs dependencies on first run.
Manual installation:
- Clone the repository into your CLAUDE plugins directory:
```
git clone https://github.com/ArkTechNWA/zsh-tool.git ~/.claude/plugins/zsh-tool
```
- Enable in your Claude Code settings:
```
{
"enabledPlugins": {
"zsh-tool": true
}
}
```
- The bundled wrapper script creates a virtual environment and prepares the MCP server for you when you run it.Local development uses a local MCP configuration. Create or edit a local MCP JSON to point to the wrapper script and set environment values if needed. Example shows using a local path to the wrapper and overriding NEVERHANG timeouts.
Environment variables you may configure directly for runtime behavior include: - ALAN_DB_PATH — path to the A.L.A.N. database - NEVERHANG_TIMEOUT_DEFAULT — default timeout duration in seconds (default 120) - NEVERHANG_TIMEOUT_MAX — maximum timeout duration in seconds (default 600)
If you are developing or testing locally, you can use a local MCP JSON that points to the wrapper script and sets the timeout values as shown in the example. The A.L.A.N. memory features operate within a 15-minute rolling window with exponential decay for long-term pruning.
The MCP server exposes a set of tools to manage and monitor command execution, including: - zsh: Execute a command with yield-based oversight - zsh_poll: Retrieve incremental output from a running task - zsh_send: Send input to a task's stdin - zsh_kill: Terminate a running task - zsh_tasks: List all active tasks - zsh_health: Get overall health status - zsh_alan_stats: Access A.L.A.N. database statistics - zsh_alan_query: Query pattern insights for a command - zsh_neverhang_status: Check the NEVERHANG circuit breaker state - zsh_neverhang_reset: Reset the circuit to a healthy state These tools enable you to monitor, control, and improve your command execution lifecycle.
A.L.A.N. 2.0 provides intelligent short-term learning, including retry detection, streak tracking, fuzzy matching, proactive feedback, and session memory. SSH-specific observations track host connectivity and remote command success to differentiate connectivity issues from command failures. The server tracks per-pipeline and per-host outcomes to help you diagnose are more precise when commands involve multiple hosts or chained operations.
Execute command with yield-based oversight to prevent hangs and provide incremental output.
Fetch more output from a running task to monitor progress.
Send input to a task's stdin to interact with prompts.
Terminate a running task when needed.
List all active tasks to manage workload.
Provide an overall health status of the MCP server.
Access A.L.A.N. statistics for insights and monitoring.
Query pattern insights for specific commands to anticipate outcomes.
Show the current NEVERHANG circuit breaker state.
Reset the circuit breaker to a healthy state.