<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.6.3)
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: