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:

Problem	zsh-tool Solution
Bash/zsh quotation confusion	Native zsh — no shell mismatch, no debug loops
Commands hang forever	Yield-based execution — always get control back
No visibility into running commands	zsh_poll — incremental output collection
Can't interact with prompts	PTY mode + zsh_send — full interactive support
Can't type passwords	PTY mode — let Claude Code type its own passwords
Timeouts cascade	NEVERHANG circuit breaker — fail fast, auto-recover
No memory between calls	A.L.A.N. 2.0 — retry detection, streak tracking, proactive insights
Polling wastes tokens	Intelligent polling — 2s listen window, adaptive suggestions, duration estimates
Blind kills, no learning	Kill-aware A.L.A.N. — classifies impatience vs genuine hangs
Retrying with wrong flags	manopt — auto-surfaces command options on repeated failures
No task management	zsh_tasks, zsh_kill — full control

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.

Field	What it tells you
from_line / to_line	Line range in this delta (e.g., 801-803)
new_bytes	Byte count of new output since last poll
full_output (param)	Pass true to get entire buffer with line numbers

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:

Field	What it tells you
polls_since_output	How many empty polls in a row
elapsed_since_last_output_s	Idle time since last output
alan_estimate	A.L.A.N.'s duration prediction based on command history
suggestion	Adaptive advice: space out polls, check soon, or consider killing

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:

Category	Meaning	Example
EARLY_KILL	Killed well before median completion	"Killed at 30s. Median is 120s. Needs more time."
LATE_KILL	Ran way past expected duration	"Killed after 180s. Median is 45s. Something is wrong."
PATTERN_PROBLEM	Template gets killed >50% of the time	"This pattern may need a different approach entirely."

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:

Observation	What it tracks	Example insight
Host connectivity	Can we connect to this host?	"Host 'vps' has 67% connection failure rate"
Remote command	Does this command work across hosts?	"Remote command 'git pull' reliable across 3 hosts"

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

Tool	Purpose
zsh	Execute command with yield-based oversight
zsh_poll	Get new output (delta) from running task with line numbers
zsh_send	Send input to task's stdin
zsh_kill	Kill a running task
zsh_tasks	List all active tasks
zsh_health	Overall health status
zsh_alan_stats	A.L.A.N. database statistics
zsh_alan_query	Query pattern insights for a command
zsh_neverhang_status	Circuit breaker state
zsh_neverhang_reset	Reset circuit to CLOSED

---

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 Output Formatting — No more JSON dumps

• Structured output — command header, separator-divided sections, status footer with icons
• Visual status icons — ✔ / ✘ replace [COMPLETED / [FAILED brackets
• Progress consolidation — consecutive progress lines (e.g., 10%, 20%, 30%) collapsed to show only the latest, preventing screen spam during downloads/builds
• Command echo — $ command header shows what ran, truncated at 120 chars
• Colored exit codes — green=0, red=nonzero, yellow=signal (129+)
• Richer notifications — background task completions use ┌ notify: with failure coloring
• ALAN insight icons — ⚠ for warnings, ℹ for info
• New format.rs module — all formatting extracted from mod.rs into isolated, testable module
• 35 new tests (121 total) covering all formatting functions

0.6.1

Protocol Fix — Bare JSON-RPC support for Claude Code v2.1+

• Fix: MCP server now auto-detects bare newline-delimited JSON (Claude Code v2.1.42+) vs Content-Length framing
• Debug logging: stderr diagnostics for protocol negotiation, request/response lifecycle, shutdown
• Log file: run-mcp.sh redirects stderr to /tmp/zsh-tool-mcp.log for MCP debugging

0.6.0

Full Rust Rewrite — Goodbye Python, hello speed

• Complete rewrite in Rust — MCP server, executor, A.L.A.N., NEVERHANG, all native
• 79 Rust tests — unit tests + full MCP integration tests (JSON-RPC round-trip)
• CI pipeline rewritten — cargo test + cargo clippy replace pytest + ruff
• Python removed — 7,600+ lines of Python deleted, zero Python dependencies
• ~2x faster CI — cold build 97s → cached 48s (vs Python's 60-120s)
• All features preserved: yield/poll/send/kill, PTY mode, A.L.A.N. 2.0, NEVERHANG, manopt, SSH tracking, pipeline segments

0.5.0

A.L.A.N. v2 Upgrade — Intelligent polling, kill awareness, manopt

• Intelligent polling: 2s listen window in zsh_poll reduces empty round-trips; poll metadata with duration estimates and adaptive suggestions
• Kill-aware A.L.A.N.: KILLED outcome type with elapsed tracking; classifies early kills (impatience), late kills (genuine hangs), and pattern problems (wrong approach)
• manopt integration: Async man-page option parsing on repeated command failures; cached in SQLite; presented on 3rd+ failure for the same command template
• New outcome_type and kill_elapsed_ms columns on observations
• New manopt_cache table for persistent man-page option storage
• ENV vars: ALAN_MANOPT_ENABLED, ALAN_MANOPT_TIMEOUT, ALAN_MANOPT_FAIL_TRIGGER, ALAN_MANOPT_FAIL_PRESENT

0.4.90

Feedback Improvements — Better signal, less noise

• ALAN insights now classified as info/warning tuples
• Command awareness: grep exit 1 = "no match" (info), exit 127 = "command not found" (warning)
• Post-execution insights: silent detection, pipe masking warnings, SIGPIPE exclusion
• ANSI coloring on metadata lines (green=success, red=failure, cyan=running, yellow=timeout)
• COMPLETED/FAILED status word based on exit code
• Raw pipestatus lists replace formatted [cmd:code] strings
• Grouped insight display: [info: A.L.A.N.: ...] and [warning: A.L.A.N.: ...]

0.4.83

Python 3.14 Support — Future-proofing

• Added Python 3.14 classifier and badge
• Removed deprecated asyncio.DefaultEventLoopPolicy fixture (slated for removal in 3.16)
• All 331 tests pass on Python 3.14.2

0.4.81

Pipestatus Marker Leak Fix — Data integrity

• Fixed race condition where ___ZSH_PIPESTATUS_MARKER___ could leak into output
• Marker now stripped in _build_task_response() before returning to caller
• Prevents corrupted file content when output is captured mid-execution
• CI: Runner switched to docker executor, added PEP 668 compliance

0.4.80

Per-Segment Exit Codes — Know exactly which command failed

• Exit codes now show [cmd1:0,cmd2:1,cmd3:0] format instead of single integer
• Each pipeline segment paired with its actual exit status from zsh $pipestatus
• A.L.A.N. learning receives accurate per-command outcomes
• Self-documenting output for human and AI analysis
• Fixes bug where all commands reported exit=0 regardless of actual status

0.4.79

Server Modular Refactoring — Cleaner architecture

• Extracted MCP server into zsh_tool/server.py module
• Centralized configuration in zsh_tool/config.py
• Fixed plugin.json version sync with package version

0.4.75

Pipeline Intelligence — Know which segment of your pipeline is failing

• A.L.A.N. now captures zsh's $pipestatus array for every pipeline
• Each segment recorded as independent observation with its own exit code
• When cat foo | grep -badopts | sort fails, you know grep was the problem
• Quote/escape-aware pipeline parsing handles complex commands correctly
• Backwards compatible: full pipeline still recorded alongside segments
• 248 new test lines covering segment tracking and edge cases

0.4.6

Configuration & Polish — User-configurable defaults, 91% coverage

• User config file (~/.config/zsh-tool/config.yaml) for custom yield_after
• Test coverage improved: 303 tests, 91% coverage
• Fixed null-check bug in task cleanup
• Logo files consolidated and fixed

0.4.5

Bundled Plugin — Zero-friction marketplace install

• Auto-install wrapper (scripts/run-mcp.sh) creates venv on first run
• Portable .mcp.json using ${CLAUDE_PLUGIN_ROOT}
• ArkTechNWA marketplace support
• No manual pip install required

0.4.0

Test Suite & CI — 290 tests, 89% coverage

• Comprehensive test suite covering all modules
• CI pipeline with test and lint stages
• Dynamic pipeline and coverage badges
• Gentle test runner (run_tests.sh) with nice and sleep between files
• Fixed deprecation warnings and lint errors
• Added pytest-asyncio for async test support

0.3.1

SSH Intelligence — Separate host connectivity from remote command success

• SSH commands now record dual observations (host + remote command)
• Exit code classification: 0=success, 255=connection_failed, 1-254=command_failed
• New ssh_observations table for SSH-specific tracking
• get_ssh_host_stats() — per-host connection/command success rates
• get_ssh_command_stats() — per-command stats across all hosts
• SSH-specific insights: flaky hosts, reliable hosts, failing commands
• 31 new tests for SSH tracking

0.3.0

A.L.A.N. 2.0 — "Maybe you're fuckin' up, maybe you're doing it right."

• Retry detection: warns when repeating failed commands
• Streak tracking: celebrates success, warns on failure
• Fuzzy template matching: similar commands grouped
• Proactive insights: contextual feedback before execution
• Session memory: 15-minute rolling window
• New database tables: recent_commands, streaks

0.2.0

• Yield-based execution with live oversight
• PTY mode for full terminal emulation
• Interactive input support via zsh_send
• Task management: zsh_poll, zsh_kill, zsh_tasks
• Fixed stdin blocking with subprocess.PIPE

0.1.0

• Initial release
• NEVERHANG circuit breaker
• A.L.A.N. learning database

---

License

MIT License - see LICENSE for details.

---

For Johnny5. For us.
ArkTechNWA