Zsh

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.

How to use

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.

How to install

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.

Configuration and runtime details

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.

Tools and endpoints

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.

Additional notes

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.

Available tools

zsh

Execute command with yield-based oversight to prevent hangs and provide incremental output.

zsh_poll

Fetch more output from a running task to monitor progress.

zsh_send

Send input to a task's stdin to interact with prompts.

zsh_kill

Terminate a running task when needed.

zsh_tasks

List all active tasks to manage workload.

zsh_health

Provide an overall health status of the MCP server.

zsh_alan_stats

Access A.L.A.N. statistics for insights and monitoring.

zsh_alan_query

Query pattern insights for specific commands to anticipate outcomes.

zsh_neverhang_status

Show the current NEVERHANG circuit breaker state.

zsh_neverhang_reset

Reset the circuit breaker to a healthy state.