# zsh-tool
**Category:** π» Developer Tools
**Repository:** https://github.com/ArkTechNWA/zsh-tool
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/zsh-tool
## Description
Zsh for Claude Code. PTY mode lets Claude type passwords. NEVERHANG + A.L.A.N.
## Claude Desktop Quick Installation
Heuristic fallback β verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"zsh-tool": {
"command": "npx",
"args": ["-y","zsh-tool"]
}
}
```
## Documentation & README
# zsh-tool
[](https://gitlab.arktechnwa.com/arktechnwa/mcp/zsh-tool/-/pipelines)
[](LICENSE)
[](https://www.rust-lang.org/)
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](LICENSE)
**Organization:** [ArkTechNWA](https://github.com/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
```bash
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](LICENSE) for details.
---
For Johnny5. For us.
ArkTechNWA