Zsh Tool

zsh-tool

Zsh execution tool for Claude Code with full Bash parity, yield-based oversight, PTY mode, NEVERHANG circuit breaker, and A.L.A.N. short-term learning.

Status: Beta (v0.7.2)

Author: Claude + Meldrey

License: MIT

Organization: ArkTechNWA

---

*Built with obsessive attention to reliability.*

---

Why?

The #1 reason: If you use zsh, Claude Code's Bash tool causes quotation mismatches and shell confusion. Every debug loop costs tokens. zsh-tool eliminates this instantly and permanently.

The token math: One avoided debug spiral = 30+ seconds saved, hundreds of tokens preserved.

zsh-tool is intelligent shell execution:

This is the difference between "run commands" and "intelligent shell integration."

---

Features

Yield-Based Execution

Commands return after yield_after seconds with partial output if still running:

• No more hanging — you always get control back
• Incremental output — collect with zsh_poll
• Interactive input — send with zsh_send
• Task management — zsh_kill and zsh_tasks

PTY Mode

Full pseudo-terminal emulation for interactive programs:

# Enable with pty: true

zsh(command="pass insert mypass", pty=true)

See prompts, send input with zsh_send

- Proper handling of interactive prompts

• Programs that require a TTY
• Color output and terminal escape sequences
• Full stdin/stdout/stderr merging

NEVERHANG Circuit Breaker

Prevents hanging commands from blocking sessions:

• Tracks timeout patterns per command hash
• Opens circuit after 3 timeouts in rolling 1-hour window
• Auto-recovers after 5 minutes
• States: CLOSED (normal) → OPEN (blocking) → HALF_OPEN (testing)

A.L.A.N. 2.0 (As Long As Necessary)

Intelligent short-term learning — *"Maybe you're fuckin' up, maybe you're doing it right."*

• Retry Detection — warns when you're repeating failed commands
• Streak Tracking — celebrates success streaks, warns on failure streaks
• Fuzzy Matching — git push origin feature-1 → git push origin *
• Proactive Insights — contextual feedback before you run commands
• Session Memory — 15-minute rolling window tracks recent activity
• Temporal Decay — exponential decay (24h half-life), auto-prunes
• SSH Intelligence — separates host connectivity from remote command success
• Pipeline Segment Tracking — when cat foo | grep -badopts | sort fails, A.L.A.N. knows *which* segment failed

Delta Output with Line Numbers (v0.6.3)

zsh_poll returns only new output since the last poll, prefixed with global line numbers. No more dumping 800 lines every poll call.

801: Installing package foo...

802: Compiling module bar... 803: Done.

First poll returns all output from line 1. Subsequent polls continue where the last left off. Completed tasks return the final delta, then empty on re-poll.

Intelligent Polling

zsh_poll performs a 2-second listen window before returning. If output arrives within 2s, it comes back immediately. If not, poll metadata tells the agent what's happening:

Suggestions are advisory only — the agent always decides. A 2-minute pip install no longer generates 40 empty round-trips.

Kill-Aware A.L.A.N.

When the agent kills a command, A.L.A.N. records it as a KILLED outcome and classifies *why*:

Kill classification compares kill_elapsed / median_duration to distinguish impatience from genuine hangs.

manopt — Man Page Options on Failure

When a command fails repeatedly, A.L.A.N. surfaces its available options:

• 1st failure — normal feedback, no manopt
• 2nd failure — triggers async manopt lookup in background (2s timeout)
• 3rd+ failure — presents cached option table in A.L.A.N. insight

Parsed from local man pages. Cached in SQLite. On by default (ALAN_MANOPT_ENABLED=1).

SSH Tracking

A.L.A.N. treats SSH commands specially, recording two separate observations:

Exit code classification:

• 0 — Success (connected AND command succeeded)
• 255 — Connection failed (SSH couldn't connect)
• 1-254 — Command failed (connected but remote command failed)

This means when ssh host3 'git pull' fails with exit 255, A.L.A.N. knows the *host* was unreachable—not that git pull is broken.

---

Tools

---

Installation

From Marketplace (Recommended)

Add the ArkTechNWA marketplace to Claude Code:

ArkTechNWA/claude-plugins

Then install: /plugin install arktechnwa/zsh-tool

That's it. The plugin auto-installs dependencies on first run.

Manual Installation

git clone https://github.com/ArkTechNWA/zsh-tool.git ~/.claude/plugins/zsh-tool

Enable in ~/.claude/settings.json:

{

"enabledPlugins": { "zsh-tool": true } }

The bundled scripts/run-mcp.sh builds the Rust binary on first run and launches the MCP server.

Local Development

For local development/testing, the wrapper script automatically detects when CLAUDE_PLUGIN_ROOT isn't expanded and uses the calculated plugin root directory instead. No configuration changes needed.

Alternatively, create a .mcp.local.json with absolute paths:

{

"mcpServers": { "zsh-tool": { "type": "stdio", "command": "/path/to/zsh-tool/scripts/run-mcp.sh", "env": { "NEVERHANG_TIMEOUT_DEFAULT": "120", "NEVERHANG_TIMEOUT_MAX": "600" } } } }

The ALAN_DB_PATH will be automatically set to {plugin_root}/data/alan.db if not explicitly provided.

Requirements: Rust toolchain (cargo) and zsh must be installed.

---

Architecture

zsh-tool/

├── .claude-plugin/ │ ├── plugin.json │ └── CLAUDE.md ├── .mcp.json ├── zsh-tool-rs/ │ ├── Cargo.toml │ └── src/ │ ├── main.rs # CLI entry point │ ├── lib.rs # Module exports │ ├── executor.rs # Pipe/PTY command execution │ ├── config.rs # User config (~/.config/zsh-tool/) │ ├── circuit.rs # NEVERHANG circuit breaker │ ├── meta.rs # Task metadata (exit code, pipestatus) │ ├── alan/ # A.L.A.N. 2.0 learning engine │ │ ├── mod.rs # Recording + insights │ │ ├── hash.rs # Fuzzy command hashing │ │ ├── insights.rs # Proactive feedback │ │ ├── manopt.rs # Man-page option parsing │ │ ├── ssh.rs # SSH host/command tracking │ │ ├── streak.rs # Success/failure streaks │ │ ├── pipeline.rs # Pipeline segment tracking │ │ ├── prune.rs # Temporal decay + pruning │ │ └── stats.rs # Database statistics │ └── serve/ # MCP JSON-RPC server │ ├── mod.rs # Request dispatch + tool handlers │ ├── format.rs # Rich output formatting │ ├── protocol.rs # JSON-RPC framing │ └── tools.rs # Tool schema definitions ├── scripts/ │ └── run-mcp.sh # Build + launch wrapper ├── data/ │ └── alan.db # A.L.A.N. SQLite database └── README.md

---

Configuration

Environment variables (set in .mcp.json):

• ALAN_DB_PATH — A.L.A.N. database location
• NEVERHANG_TIMEOUT_DEFAULT — Default timeout (120s)
• NEVERHANG_TIMEOUT_MAX — Maximum timeout (600s)
• ALAN_MANOPT_ENABLED — Enable man-page option hints on failure (default: 1)
• ALAN_MANOPT_TIMEOUT — Max seconds to wait for manopt parsing (default: 2.0)
• ALAN_MANOPT_FAIL_TRIGGER — Fail count to trigger async lookup (default: 2)
• ALAN_MANOPT_FAIL_PRESENT — Fail count to present cached options (default: 3)

Disabling Bash (Optional)

To use zsh as the only shell, add to ~/.claude/settings.json:

{

"permissions": { "deny": ["Bash"] } }

---

Changelog

0.7.2

User-Visible Output — *Tell the model to show its work*

• Fix: MCP tool results are invisible to users in Claude Code (platform limitation). Tool descriptions now instruct the model to relay command output verbatim in its response text.
• This is a workaround for Claude Code not rendering MCP tool result blocks to users.

0.7.1

Stale Binary Fix — *Actually deliver the new format*

• Fix: run-mcp.sh now runs cargo clean -p before rebuild when source changes, preventing Cargo's incremental build from serving a stale binary
• Fix: Rebuild trigger now also watches Cargo.toml (version bumps were invisible to the old find -newer check)

0.7.0

**Rich