Zsh Tool (Arktechnwa)

MCP开发工具

提供方 未标注

开发工具 stdio · 本地进程 Token 社区 / 第三方

全面解析Zsh ToolMCP Server的核心功能、安装配置和实用案例。作为顶级Model Context Protocol服务器,Zsh Tool能让AI助手访问实时数据、执行操作,为您提供更智能的工作体验和自动化解决方案。

一句话选型结论

按资料字段整理

Zsh Tool (Arktechnwa) 属于开发工具类 MCP 服务器,stdio · 本地进程,Token,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 基础信息齐全,可以先按官方文档接入试跑。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Zsh Tool (Arktechnwa)当前 未标注 stdio · 本地进程 本地部署 无 2026-05-17
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类开发工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

18.7 KB
来自项目仓库与上游目录的原文,未做删改

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```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 for details.


For Johnny5. For us.

ArkTechNWA

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Zsh Tool (Arktechnwa) 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

Zsh Tool (Arktechnwa) 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

Zsh Tool (Arktechnwa) 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Zsh Tool (Arktechnwa) 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

Zsh Tool (Arktechnwa) 能提供哪些能力?

资料显示能力标签包括 Token认证、开发工具、命令行工具。具体工具清单以官方文档为准。

Zsh Tool (Arktechnwa) 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Zsh Tool (Arktechnwa) 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。