for developers and AI coding agentsبرای برنامه‌نویس‌ها و ایجنت‌های کدنویسی · v0.1.0
Run any command with an idle watchdog. When it goes quiet, whystuck inspects the live process and says whether it is waiting in a pager, an editor, a y/N prompt, a password prompt, watch mode, a lock or a stalled connect, with the evidence and the non-interactive command to run instead.هر دستوری را با ناظر بی‌حرکتی اجرا کنید. وقتی ساکت شد، whystuck فرایند زنده را بررسی می‌کند و می‌گوید در pager، ویرایشگر، پرسش y/N، رمز، حالت watch، قفل یا اتصال بی‌پاسخ منتظر مانده، همراه با شواهد و دستور غیرتعاملیِ جایگزین.
The problemمسئله
Humans and AI coding agents lose minutes, or whole sessions, to commands that wait silently: git log in a pager, git commit in an editor, a y/N prompt, a sudo password, a test runner in watch mode. A plain timeout just kills the command and says nothing.انسان‌ها و ایجنت‌های کدنویسی هوش مصنوعی دقیقه‌ها و گاهی یک نشست کامل را به دستورهایی می‌بازند که بی‌صدا منتظر می‌مانند: git log در pager، git commit در ویرایشگر، پرسش y/N، رمز sudo یا ابزار تست در حالت watch. timeout ساده فقط دستور را می‌کُشد و چیزی نمی‌گوید.
Runs the command on a pseudo-terminal with an idle watchdog. When it goes quiet, whystuck inspects the live process (output tail, process tree, /proc, sockets, locks) and says whether it is stuck in a pager, an editor, a y/N or password prompt, watch mode, a lock or an unanswered network connect (13 verdicts), with the evidence and the non-interactive command to run instead. --json and exit code 125 make it usable by agents.دستور را روی یک شبه‌ترمینال با ناظر بی‌حرکتی اجرا می‌کند. وقتی ساکت شد، فرایند زنده را بررسی می‌کند (انتهای خروجی، درخت فرایند، /proc، سوکت‌ها و قفل‌ها) و می‌گوید در pager، ویرایشگر، پرسش y/N یا رمز، حالت watch، قفل یا اتصال شبکهٔ بی‌پاسخ گیر کرده (۱۳ حکم)، همراه با شواهد و دستور غیرتعاملی جایگزین. خروجی --json و کد خروج ۱۲۵ آن را برای ایجنت‌ها قابل‌استفاده می‌کند.
Demoنمایش
Pick a scenario. The stand-in programs only imitate the stall; the inspection that follows (process tree, sockets, locks) is real. This is the unedited output of whystuck --demo, from docs/demo.txt.یک سناریو را انتخاب کنید. برنامه‌ها فقط گیرکردن را شبیه‌سازی می‌کنند؛ بازرسیِ بعدی (درخت فرایند، سوکت‌ها، قفل‌ها) واقعی است. این خروجی ویرایش‌نشدهٔ whystuck --demo از docs/demo.txt است.
whystuck 0.1.0 demo · Python 3.13.5 · Linux x86_64 · idle threshold 1.5s
Each scenario runs a small stand-in program (a script named like the real tool) under whystuck.
The stand-ins only imitate the stall. The inspection that follows (process tree, sockets, locks) is real.
Terminal escape sequences are stripped from the display below.
[1/8] pager — `git log`: output is handed to a pager (less) that waits for q
commit 9f3c2ab41d7e (HEAD -> main)
Author: mrzroot <mrzroot@users.noreply.github.com>
Add idle watchdog
commit 71be0c9a55f2
Initial commit
(END)
─── whystuck ───────────────────────────────────────────────────
No output for 1.6s
▸ STUCK: Waiting in a pager [confidence: high]
Output was handed to a pager that waits for you to press q.
Evidence
• descendant process is a pager: less (pid 235596)
• last output line looks like a pager prompt: "(END)"
• pid 235596 (less): blocked in read() on fd 3 -> /dev/tty (terminal input)
Fix (non-interactive)
• git --no-pager log
• GIT_PAGER=cat PAGER=cat git log
• export PAGER=cat GIT_PAGER=cat # once, for the whole session
────────────────────────────────────────────────────────────────
expected `pager`, whystuck said `pager` OK (command stopped by whystuck: stuck, exit 125)
[2/8] editor — `git commit`: git opens an editor and waits for it to close
hint: Waiting for your editor to close the file...
-- INSERT --
─── whystuck ───────────────────────────────────────────────────
No output for 1.6s
▸ STUCK: Waiting in a text editor [confidence: high]
`git commit` opened an editor and is waiting for it to be closed.
Evidence
• descendant process is an editor: vim (pid 236399)
• it is editing a git/editor temp file: /tmp/whystuck-demo-4wv3mftp/work/.git/COMMIT_EDITMSG
• output says: "Waiting for your editor to close the file..."
• pid 236399 (vim): blocked in read() on fd 4 -> /dev/tty (terminal input)
Fix (non-interactive)
• git commit -m "your message"
• git commit -F message.txt # message from a file
• GIT_EDITOR=true git commit # accept the template message
• export GIT_EDITOR=true EDITOR=true # once, for the whole session
Also matched: watch (low)
────────────────────────────────────────────────────────────────
expected `editor`, whystuck said `editor` OK (command stopped by whystuck: stuck, exit 125)
[3/8] confirm — `apt-get install ripgrep`: an installer asks [Y/n]
Reading package lists... Done
The following NEW packages will be installed:
ripgrep
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Do you want to continue? [Y/n]
─── whystuck ───────────────────────────────────────────────────
No output for 1.6s
▸ STUCK: Waiting for a yes/no answer [confidence: high]
The command is waiting for a yes/no (or Enter) answer.
Evidence
• last output line is a yes/no style prompt: "Do you want to continue? [Y/n]"
• pid 236407 (apt-get): blocked in read() on fd 0 -> /dev/pts/0 (terminal input)
Fix (non-interactive)
• DEBIAN_FRONTEND=noninteractive apt-get install -y ripgrep
• yes | apt-get install ripgrep # answers y to everything: only for commands you trust
• check `apt-get --help` for --yes / -y / --force / --non-interactive
• feed the answer instead: printf 'y\n' | whystuck -- apt-get install ripgrep
────────────────────────────────────────────────────────────────
expected `confirm`, whystuck said `confirm` OK (command stopped by whystuck: stuck, exit 125)
[4/8] secret — `sudo systemctl restart nginx`: sudo asks for a password on the terminal
[sudo] password for demo:
─── whystuck ───────────────────────────────────────────────────
No output for 1.6s
▸ STUCK: Waiting for a password / credential [confidence: high]
The command is asking for a password, passphrase or other credential.
Evidence
• last output line asks for a credential: "[sudo] password for demo:"
• pid 236418 (sudo): blocked in read() on fd 5 -> /dev/tty (terminal input)
Fix (non-interactive)
• sudo -n systemctl restart nginx # fail instead of prompting (needs NOPASSWD)
• configure passwordless sudo for the specific command in /etc/sudoers.d/
• pass the secret via an env var or file the tool supports; never paste it into an agent transcript
────────────────────────────────────────────────────────────────
expected `secret`, whystuck said `secret` OK (command stopped by whystuck: stuck, exit 125)
[5/8] watch — `vitest`: a test runner starts in watch mode and never exits
DEV v2.1.0 /project
OK src/add.test.ts (3 tests) 4ms
Test Files 1 passed (1)
PASS Waiting for file changes...
press h to show help, press q to quit
─── whystuck ───────────────────────────────────────────────────
No output for 1.6s
▸ STUCK: Stuck in watch / full-screen mode [confidence: high]
The tool is in watch / interactive full-screen mode and will never exit by itself.
Evidence
• recent output says it is watching: "PASS Waiting for file changes..."
• process looks like a watch/TUI tool: vitest
Fix (non-interactive)
• vitest run # single run instead of watch mode
• CI=true vitest # many test runners disable watch mode when CI is set
• look for a one-shot flag in `COMMAND --help` (run / --once / --no-watch)
────────────────────────────────────────────────────────────────
expected `watch`, whystuck said `watch` OK (command stopped by whystuck: stuck, exit 125)
[6/8] server — `python -m http.server 0 --bind 127.0.0.1`: a real dev server (python -m http.server) that is fine, just long-running
Serving HTTP on 127.0.0.1 port 37653 (http://127.0.0.1:37653/) ...
─── whystuck ───────────────────────────────────────────────────
No output for 1.6s
▸ NOT STUCK: Running a server [confidence: high]
It is running a server. It will keep running until stopped; that is normal, not a hang.
Evidence
• listening TCP socket: 127.0.0.1:37653 (pid 236446)
• output says: "Serving HTTP on 127.0.0.1 port 37653 (http://127.0.0.1:37653/) ..."
If you need it to finish / not wait
• nohup /usr/bin/python3 -m http.server 0 --bind 127.0.0.1 > server.log 2>&1 & # start it in the background, then poll the port
• use a process manager / a second terminal for servers, and run tests or curl against it from another command
• agents: do not wait for a server command to exit; start it detached and check the port
────────────────────────────────────────────────────────────────
expected `server`, whystuck said `server` OK (command stopped by whystuck: stopped, exit 125)
[7/8] lock — `apt-get update`: waits for a lock that another process holds
Reading package lists... Done
Waiting for cache lock: Could not get lock /tmp/whystuck-demo-4wv3mftp/lock-frontend
─── whystuck ───────────────────────────────────────────────────
No output for 1.6s
▸ STUCK: Waiting for a lock [confidence: high]
The command is waiting for a lock that another process holds.
Evidence
• recent output mentions a lock: "Waiting for cache lock: Could not get lock /tmp/whystuck-demo-4wv3mftp/lock-frontend"
• pid 236458 (apt-get) is blocked in flock()
• /tmp/whystuck-demo-4wv3mftp/lock-frontend is held open by pid 236457 (unattended-upgr)
Fix (non-interactive)
• wait for pid 236457 (unattended-upgr) to finish; stop it only if it is yours and truly stuck: kill 236457
• apt-get update -o DPkg::Lock::Timeout=120 # wait up to 2 min for the lock
• flock -w 30 LOCKFILE COMMAND # bounded wait for a lock you control
────────────────────────────────────────────────────────────────
expected `lock`, whystuck said `lock` OK (command stopped by whystuck: stuck, exit 125)
[8/8] network — `git clone https://example.invalid/whystuck.git`: a TCP connect is never answered (local listener with a full backlog)
Cloning into 'whystuck'...
─── whystuck ───────────────────────────────────────────────────
No output for 1.6s
▸ STUCK: Network connect not answered [confidence: high]
A TCP connection is not being answered (host unreachable, filtered or very slow).
Evidence
• pid 236472 has a TCP connect() in progress to 127.0.0.1:58711 (SYN_SENT: no reply yet)
Fix (non-interactive)
• nc -vz -w 5 127.0.0.1 58711 # does a plain TCP connect work from here?
• curl -v --connect-timeout 5 http://127.0.0.1:58711/
• no proxy variables are set: if this network needs a proxy or VPN, configure it
• GIT_HTTP_LOW_SPEED_LIMIT=1000 GIT_HTTP_LOW_SPEED_TIME=15 git clone https://example.invalid/whystuck.git # abort slow transfers
• try a mirror/registry mirror, another network, or check DNS/firewall for that address
────────────────────────────────────────────────────────────────
expected `network`, whystuck said `network` OK (command stopped by whystuck: stuck, exit 125)
Summary: 8/8 scenarios diagnosed as expected.
Featuresامکانات
Reads the process tree, /proc (stat, wchan, syscall, fds, sockets) and the tail of the output. A blocking read() on a terminal is the strongest "waiting for input" signal; confidence rises with the number of independent signals.درخت فرایند، /proc (stat، wchan، syscall، fd و سوکت‌ها) و انتهای خروجی را می‌خواند. read() مسدودشده روی ترمینال قوی‌ترین نشانهٔ «منتظر ورودی» است و اطمینان با تعداد نشانه‌های مستقل بالا می‌رود.
editor, pager, secret, confirm, watch, follow, lock, network, server, stdin_wait, sleeping, busy and unknown. A server, a sleep and a busy process are reported as not stuck and are never killed. If nothing matches the verdict is "unknown" with the raw evidence; it never guesses.editor، pager، secret، confirm، watch، follow، lock، network، server، stdin_wait، sleeping، busy و unknown. سرور، sleep و فرایند پرکار «گیرنکرده» گزارش می‌شوند و هرگز کشته نمی‌شوند. اگر چیزی جور نشود حکم «unknown» با شواهد خام است؛ هرگز حدس نمی‌زند.
Every verdict prints commands to run instead: git --no-pager log, GIT_EDITOR=true git commit, DEBIAN_FRONTEND=noninteractive apt-get install -y, vitest run, sudo -n, flock -w, connect timeouts.هر حکم دستورهای جایگزین را چاپ می‌کند: git --no-pager log، GIT_EDITOR=true git commit، DEBIAN_FRONTEND=noninteractive apt-get install -y، vitest run، sudo -n، flock -w و مهلت اتصال.
--json prints one document; exit code 125 means stuck and 124 means timeout, anything else is the command's own status. --kill stops the process group only when the verdict is "stuck". A ready AGENTS.md snippet is included.--json یک سند JSON چاپ می‌کند؛ کد خروج ۱۲۵ یعنی گیرکرده و ۱۲۴ یعنی مهلت تمام شد، هر کد دیگر وضعیت خود دستور است. --kill فقط وقتی حکم «stuck» است گروه فرایند را متوقف می‌کند. قطعهٔ آمادهٔ AGENTS.md هم همراه آن است.
One Python file (3.9+), no network, no telemetry. whystuck --explain PID diagnoses a process that is already hung without touching it.یک فایل پایتون (۳٫۹ به بالا)، بدون شبکه و بدون ردیابی. whystuck --explain PID فرایندی را که از قبل گیر کرده بدون دست‌زدن به آن تشخیص می‌دهد.
whystuck --demo runs 8 scenarios that stall on purpose (pager, editor, y/N, password, watch, server, lock, network). The programs are stand-ins; the inspection that follows is real. 136 tests, including a check that removing any rule breaks a case.whystuck --demo هشت سناریو را اجرا می‌کند که عمداً گیر می‌کنند (pager، ویرایشگر، y/N، رمز، watch، سرور، قفل و شبکه). برنامه‌ها نمونهٔ جایگزین‌اند ولی بازرسیِ بعدی واقعی است. ۱۳۶ آزمون، از جمله بررسی اینکه حذف هر قاعده دست‌کم یک مورد را خراب می‌کند.
Install & quick startنصب و شروع سریع
pip install git+https://github.com/mrzroot/whystuck
# or copy the single file anywhere on your PATH:
install -m755 whystuck.py ~/.local/bin/whystuckwhystuck --demo
whystuck --demo --only pager,secret,networkwhystuck -- git log # diagnose if it goes quiet for 20 s
whystuck --idle 10 --kill -- npm test # stop it if the verdict says "stuck"
whystuck --explain 12345 # diagnose a process that is already hungwhystuck --json --kill --idle 20 -- <command>
# exit 125 = stuck: read verdicts[0].fixes and re-run non-interactivelyHow it worksچطور کار می‌کند
The command runs inside a pseudo-terminal, so colours, pagers and prompts all appear. whystuck tracks the time of the last output byte (or forwarded keystroke) and a rolling tail of the output.دستور داخل یک شبه‌ترمینال اجرا می‌شود، پس رنگ‌ها، pagerها و پرسش‌ها همه ظاهر می‌شوند. whystuck زمان آخرین بایت خروجی (یا کلیدِ ارسال‌شده) و انتهای خروجی را دنبال می‌کند.
After --idle seconds it snapshots the process tree: stat, cmdline, wchan, /proc/PID/syscall, open fds, TCP sockets (LISTEN and SYN_SENT), a 0.5 s CPU sample and lock holders.پس از --idle ثانیه از درخت فرایند عکس می‌گیرد: stat، cmdline، wchan، /proc/PID/syscall، fdهای باز، سوکت‌های TCP (LISTEN و SYN_SENT)، نمونهٔ ۰٫۵ثانیه‌ای CPU و نگه‌دارندگان قفل.
classify() walks 13 rules; the first with evidence wins and the others are listed as "also matched". Confidence comes from how many independent signals agree. If nothing matches the verdict is unknown; it never guesses.classify() از ۱۳ قاعده می‌گذرد؛ اولین قاعده‌ای که شاهد دارد برنده است و بقیه «هم‌خوان‌شده» فهرست می‌شوند. اطمینان از تعداد نشانه‌های مستقلِ هم‌نظر می‌آید. اگر چیزی جور نشود حکم unknown است؛ هرگز حدس نمی‌زند.
It prints the verdict, the evidence and the non-interactive fix on stderr, keeps stdout for the command, and exits 125 when it stopped a stuck command (--kill) or 124 on timeout.حکم، شواهد و راه‌حل غیرتعاملی را روی stderr چاپ می‌کند، stdout را برای خود دستور نگه می‌دارد و وقتی دستورِ گیرکرده را متوقف کرده (--kill) با ۱۲۵ و در مهلت تمام‌شده با ۱۲۴ خارج می‌شود.
Honest limitsمحدودیت‌های صادقانه
How it comparesمقایسه با ابزارهای دیگر
No existing tool found as of Oct 2026تا مهر ۱۴۰۵ (اکتبر ۲۰۲۶) ابزار مشابهی پیدا نشد that is a standalone, agent-agnostic runner that inspects a live stalled process and returns the cause and the fix.که یک اجراکنندهٔ مستقل و مستقل از ایجنت باشد، فرایند گیرکردهٔ زنده را بازرسی کند و علت و راه‌حل بدهد.
This is the outcome of searches of GitHub, npm, PyPI and the web on 18 Oct 2026, not a guarantee: search indexes are incomplete and this space changes weekly. If you know one, please open an issue and it will be linked here.این نتیجهٔ جست‌وجو در گیت‌هاب، npm، PyPI و وب در ۲۶ مهر ۱۴۰۵ است، نه تضمین: نمایه‌های جست‌وجو ناقص‌اند و این حوزه هر هفته عوض می‌شود. اگر موردی می‌شناسید لطفاً یک issue باز کنید تا اینجا پیوند شود.
| Toolابزار | What it doesچه می‌کند | How it differsتفاوت |
|---|---|---|
| pi-non-interactive | Injects env vars into one agent's bash tool so commands avoid promptsمتغیر محیطی را در ابزار bash یک ایجنت تزریق می‌کند تا دستورها پرسش نپرسند | Prevention for one agent; no detection and no diagnosisپیشگیری برای یک ایجنت؛ بدون تشخیص و بدون علت‌یابی |
| pi-prevent-stuck | A static block-list of known-bad commands inside one agent extensionفهرست ایستای دستورهای مشکل‌دار درون افزونهٔ یک ایجنت | Static list; no runtime inspection of a live processفهرست ایستا؛ بدون بازرسی زمان اجرای فرایند زنده |
| GNU timeout, CI no_output_timeout | Kill after a time or silence limitپس از مهلت زمانی یا سکوت دستور را می‌کُشند | Kill only: no cause and no fixفقط کشتن: بدون علت و بدون راه‌حل |
| Heuristics inside IDE agents | Terminal tools that decide a command needs inputابزارهای ترمینال که تشخیص می‌دهند دستور ورودی می‌خواهد | Inside one product; not reusable from a shell or by other agentsدرون یک محصول؛ از شل یا ایجنت‌های دیگر قابل‌استفاده نیست |
FAQپرسش‌های متداول
Only with --kill, and only when the verdict says stuck. Servers, sleeping and busy processes are never killed. Without --kill it only reports and the command keeps running.فقط با --kill و فقط وقتی حکم «گیرکرده» باشد. سرور، sleep و فرایند پرکار هرگز کشته نمی‌شوند. بدون --kill فقط گزارش می‌دهد و دستور ادامه می‌دهد.
It is a plain CLI, so it is agent-agnostic: run whystuck --json --kill --idle 20 -- COMMAND and branch on the exit code (125 means stuck: read verdicts[0].fixes and re-run non-interactively). Paste docs/AGENTS.snippet.md into your AGENTS.md or CLAUDE.md.یک CLI ساده است، پس به ایجنت خاصی وابسته نیست: whystuck --json --kill --idle 20 -- COMMAND را اجرا کنید و روی کد خروج تصمیم بگیرید (۱۲۵ یعنی گیرکرده: verdicts[0].fixes را بخوانید و غیرتعاملی دوباره اجرا کنید). فایل docs/AGENTS.snippet.md را در AGENTS.md یا CLAUDE.md بگذارید.
Not yet. Install from GitHub with pip install git+https://github.com/mrzroot/whystuck, or copy the single file whystuck.py anywhere on your PATH.هنوز نه. از گیت‌هاب با pip install git+https://github.com/mrzroot/whystuck نصب کنید یا فایل تکیِ whystuck.py را در PATH بگذارید.
Linksپیوندها