zsh-tool

<img align="right" src="logo.png" width="150">

<!-- mcp-name: io.github.ArkTechNWA/zsh-tool -->

<br><br><br>

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: ```bash

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: ``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: ``json { "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: ``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.

---

<p align="center"> <b>For Johnny5. For us.</b><br> <i>ArkTechNWA</i> </p>