for developers and AI coding agentsبرای برنامه‌نویس‌ها و ایجنت‌های کدنویسی · v0.1.0
AI agents run commands in a non-login, non-interactive shell that never reads ~/.zshrc or ~/.bashrc. shellparity starts your shell both ways on the same machine, compares what each one sees, and prints the file, the line and the exact fix.ایجنت‌های هوش مصنوعی دستورها را در شلی بدون login و غیرتعاملی اجرا می‌کنند که ~/.zshrc و ~/.bashrc را نمی‌خواند. shellparity شل شما را روی همان دستگاه به هر دو شکل راه می‌اندازد، دیده‌های هرکدام را مقایسه می‌کند و فایل، خط و راه‌حل دقیق را چاپ می‌کند.
Same machine, same command, six different answers. Move the divider.یک دستگاه، یک دستور، شش پاسخ متفاوت. جداکننده را حرکت دهید.
The problemمسئله
AI coding agents run commands in a non-login, non-interactive shell that never reads ~/.zshrc or ~/.bashrc. Everything you configured there is invisible: nvm and pyenv versions, proxies, locale, the SSH agent, API keys, git signing. You get command not found, the wrong Node, hangs behind a proxy, mangled Persian text, and end up diffing env output by hand.ایجنت‌های کدنویسی هوش مصنوعی دستورها را در شلی بدون login و بدون حالت تعاملی اجرا می‌کنند که ~/.zshrc و ~/.bashrc را نمی‌خواند. هرچه آنجا تنظیم کرده‌اید دیده نمی‌شود: نسخهٔ nvm و pyenv، پروکسی، زبان و UTF-8، ssh-agent، کلیدهای API و امضای git. نتیجه command not found، نسخهٔ اشتباه Node، گیرکردن پشت پروکسی و متن فارسی خراب است و آخرش خروجی env را با چشم مقایسه می‌کنید.
Starts your shell twice on the same machine, like a terminal (login and interactive on a pty) and like an agent (bash -c, or login, interactive, bare), takes read-only snapshots and compares them: PATH, 27 common tools and their versions, project requirements (.nvmrc, engines, requires-python), proxy, locale with a real UTF-8 test, SSH agent, git signing, environment names and secret-looking names (never values), TTY and TERM. Each finding names the dotfile and line and prints the exact fix, for example the export lines for ~/.bash_env.شل شما را دو بار روی همان دستگاه راه می‌اندازد: یک بار مثل ترمینال (login و تعاملی روی pty) و یک بار مثل ایجنت (bash -c یا login، تعاملی و bare)، از هرکدام عکس فقط‌خواندنی می‌گیرد و مقایسه می‌کند: PATH، ۲۷ ابزار رایج و نسخه‌شان، نیازمندی پروژه (.nvmrc، engines، requires-python)، پروکسی، زبان با آزمون واقعی UTF-8، ssh-agent، امضای git، نام متغیرهای محیطی و نام‌های شبیه رمز (هرگز مقدار)، TTY و TERM. هر یافته نام فایل و شمارهٔ خط را می‌گوید و راه‌حل دقیق را چاپ می‌کند، مثلاً خط‌های export برای ~/.bash_env.
Demoنمایش
This is the output of shellparity --demo: real bash against a temporary fake HOME, so none of your dotfiles are read. Open a finding to see what the terminal sees, what the agent sees, where it comes from and the fix. Source: docs/demo.txt.این خروجی shellparity --demo است: bash واقعی روی یک HOME ساختگی و موقت، پس هیچ‌کدام از dotfileهای شما خوانده نمی‌شود. یک یافته را باز کنید تا ببینید ترمینال چه می‌بیند، ایجنت چه، از کجا می‌آید و راه‌حل چیست. منبع: docs/demo.txt.
3 errors · 6 warnings · 5 notes
What each startup mode sees
mode ok PATH dirs tools proxy UTF-8 SSH sock aliases
----------- --- --------- ----- ----- ----- -------- -------
human yes 7 5 1 yes yes 1
plain yes 2 4 - NO - 0
login yes 5 5 - NO - 0
interactive yes 4 5 1 yes yes 1
bare yes 7 5 - NO - 0
Startup files read by bash
/etc/profile yes login shells
~/.bash_profile yes login shells (first of the three that exists)
~/.bash_login no login shells (only if no ~/.bash_profile)
~/.profile no login shells (only if no ~/.bash_profile or ~/.bash_login)
~/.bashrc yes interactive non-login shells; login shells only if a profile file sources it interactive-only guard at line 2
$BASH_ENV n/a non-interactive shells, only if BASH_ENV is set
Note: ~/.bashrc returns early for non-interactive shells (line 2). Anything below that line is
skipped whenever the file is sourced non-interactively (BASH_ENV, scripts, ssh commands), so do
not point BASH_ENV at it; use a separate file.$ shellparity --demo
# generated 2026-10-18T14:04Z on Linux, bash 5.2, Python 3.13 (a real run of the real tool; the temp home directory is shown as /home/demo)
DEMO real bash against a temporary fake HOME (shown as /home/demo); your own dotfiles were not read
shellparity 0.1.0 · your terminal vs the agent's shell
shell bash 5.2.37 (/usr/bin/bash)
human bash -l -i login + interactive, on a pseudo-terminal (what your terminal app starts)
agent bash -c non-login, non-interactive (`-c`, what most agents run)
3 errors · 6 warnings · 5 notes (3 tools resolve identically)
Where the fixes go
~/.bash_env: non-interactive bash reads nothing except the file named by $BASH_ENV; set
BASH_ENV=$HOME/.bash_env in the environment that launches the agent.
Alternative: start the agent's shell as `bash -l -c ...` (login mode). It already sees the fix for 1
finding below, but it runs your login startup files on every command (slower, may print banners).
Alternative: start the agent's shell as `bash -i -c ...` (interactive mode). It already sees the fix
for 9 findings below, but it runs your interactive startup files on every command (slower, may
print banners).
✖ ERROR #1 `node` resolves to a different version for the agent
human /home/demo/.nvm/versions/node/v22.4.0/bin/node v22.4.0
agent /usr/bin/node v20.19.2
why Different binary first on PATH.
found ~/.bashrc:7: export NVM_DIR="$HOME/.nvm" (below the interactive-only guard at line 2)
found ~/.bashrc:8: export PATH="$HOME/.nvm/versions/node/v22.4.0/bin:$HOME/.local/bin:$PATH"
(below the interactive-only guard at line 2)
fix nvm is a shell function loaded from nvm.sh; agents never load it, so only the resolved bin
directory can be pinned. Re-pin after `nvm use`/`nvm alias default`.
Add to ~/.bash_env:
export PATH="$HOME/.nvm/versions/node/v22.4.0/bin:$PATH"
✖ ERROR #2 `npm` is not found in the agent shell
human /home/demo/.nvm/versions/node/v22.4.0/bin/npm (10.8.1)
agent command not found
why `command -v npm` finds it in your terminal only.
found ~/.bashrc:7: export NVM_DIR="$HOME/.nvm" (below the interactive-only guard at line 2)
found ~/.bashrc:8: export PATH="$HOME/.nvm/versions/node/v22.4.0/bin:$HOME/.local/bin:$PATH"
(below the interactive-only guard at line 2)
fix Same lines as finding #1.
✖ ERROR #3 the agent shell is not UTF-8
human LANG=C.UTF-8; charmap=UTF-8; UTF-8 ok
agent LANG=C; charmap=ANSI_X3.4-1968; NOT UTF-8
why Non-ASCII text (Persian, emoji, accents) in file names, git output and tool output can be
mangled or fail with encoding errors.
found ~/.bashrc:13: export LANG=C.UTF-8 (below the interactive-only guard at line 2)
fix Add to ~/.bash_env:
export LANG=C.UTF-8
⚠ WARN #4 5 PATH directories are only in the human shell
human 7 entries
agent 2 entries
why Missing for the agent: /home/demo/.nvm/versions/node/v22.4.0/bin, /home/demo/.local/bin,
/usr/local/bin, /usr/local/games, /usr/games
found ~/.bashrc:8: export PATH="$HOME/.nvm/versions/node/v22.4.0/bin:$HOME/.local/bin:$PATH"
(below the interactive-only guard at line 2)
fix Add to ~/.bash_env:
export PATH="$HOME/.nvm/versions/node/v22.4.0/bin:$HOME/.local/bin:/usr/local/bin:/usr/local/games:/usr/games:$PATH"
⚠ WARN #5 proxy variables set only in the human shell: HTTPS_PROXY, no_proxy
human HTTPS_PROXY=http://***:***@127.0.0.1:10809; no_proxy=localhost,127.0.0.1
agent not set
why Network tools run by the agent connect directly (or time out) instead of using your proxy.
found ~/.bashrc:10: export HTTPS_PROXY="http://***:***@127.0.0.1:10809" (below the
interactive-only guard at line 2)
found ~/.bashrc:11: export no_proxy="localhost,127.0.0.1" (below the interactive-only guard at
line 2)
fix Add to ~/.bash_env:
# HTTPS_PROXY contains credentials: copy the real line from ~/.bashrc:10
export no_proxy=localhost,127.0.0.1
⚠ WARN #6 SSH_AUTH_SOCK is missing in the agent shell
human /home/demo/.ssh/agent.sock
agent not set
why git/ssh over SSH cannot use your keys; it fails or waits for a passphrase that nobody can
type.
found ~/.bashrc:16: export SSH_AUTH_SOCK="$HOME/.ssh/agent.sock" (below the interactive-only
guard at line 2)
fix Add to ~/.bash_env:
# only if the socket path is stable (systemd, gnome-keyring, launchd):
export SSH_AUTH_SOCK=/home/demo/.ssh/agent.sock
⚠ WARN #7 git commit signing is on, but the agent shell has no TTY and no GPG_TTY
human GPG_TTY=/dev/pts/1
agent GPG_TTY unset, stdin is not a tty
why gpg's pinentry cannot ask for the passphrase, so `git commit` can fail with 'gpg failed to
sign the data' unless gpg-agent already has it cached.
found ~/.bashrc:17: export GPG_TTY=$(tty 2>/dev/null) (below the interactive-only guard at line
2)
fix Either let the agent commit unsigned: `git -c commit.gpgsign=false commit ...`,
or switch to SSH signing (`git config --global gpg.format ssh`) with an ssh-agent,
or pre-cache the passphrase in gpg-agent (gpg-preset-passphrase).
⚠ WARN #8 `NVM_DIR` is set only in the human shell
human /home/demo/.nvm
agent not set
found ~/.bashrc:7: export NVM_DIR="$HOME/.nvm" (below the interactive-only guard at line 2)
fix Add to ~/.bash_env:
export NVM_DIR=/home/demo/.nvm
⚠ WARN #9 1 secret-looking variable does exist only in the human shell
human OPENAI_API_KEY
agent not set
why Only the names are compared; values are never read or stored. Agents cannot call APIs that
need these keys.
found ~/.bashrc:15: export OPENAI_API_KEY=<redacted> (below the interactive-only guard at line
2)
fix Give these to the agent explicitly (its settings or a secrets manager), or `export
NAME=...` in the file named above. Never commit them.
ℹ NOTE #10 only `HTTPS_PROXY` is set in the human shell (not `https_proxy`)
why Tools disagree on which spelling they read (curl, for example, honours lowercase http_proxy
only). Setting both is safest.
found ~/.bashrc:10: export HTTPS_PROXY="http://***:***@127.0.0.1:10809" (below the
interactive-only guard at line 2)
ℹ NOTE #11 `EDITOR` is set only in the human shell
human vim
agent not set
ℹ NOTE #12 stdin is a TTY in the human shell but not in the agent shell
human tty
agent no tty
why Expected for agents. Commands that prompt (git credentials, ssh, sudo, installers) cannot
be answered; pass non-interactive flags.
ℹ NOTE #13 TERM is unset in the agent shell
human TERM=xterm-256color
agent TERM=unset
why Colour, `tput`, `less` and some CLIs behave differently without a terminal type.
ℹ NOTE #14 1 alias exists in the human shell, none in the agent shell
why Aliases like `ll`, `gs` or `python=python3` do not work for agents; use real commands or
scripts on PATH.
What each startup mode sees
mode ok PATH dirs tools proxy UTF-8 SSH sock aliases
----------- --- --------- ----- ----- ----- -------- -------
human yes 7 5 1 yes yes 1
plain yes 2 4 - NO - 0
login yes 5 5 - NO - 0
interactive yes 4 5 1 yes yes 1
bare yes 7 5 - NO - 0
Startup files read by bash
/etc/profile yes login shells
~/.bash_profile yes login shells (first of the three that exists)
~/.bash_login no login shells (only if no ~/.bash_profile)
~/.profile no login shells (only if no ~/.bash_profile or ~/.bash_login)
~/.bashrc yes interactive non-login shells; login shells only if a profile file sources it interactive-only guard at line 2
$BASH_ENV n/a non-interactive shells, only if BASH_ENV is set
Note: ~/.bashrc returns early for non-interactive shells (line 2). Anything below that line is
skipped whenever the file is sourced non-interactively (BASH_ENV, scripts, ssh commands), so do
not point BASH_ENV at it; use a separate file.
Nothing was changed on disk. Fixes above are suggestions; --write-snippet FILE saves the export lines.
$ echo $?
0
Featuresامکانات
Probes your shell as a terminal starts it and as an agent runs it (plain -c, login, interactive or bare), each in a fresh child process. A mode matrix shows what each startup mode sees.شل را همان‌طور که ترمینال اجرا می‌کند و همان‌طور که ایجنت اجرا می‌کند (-c ساده، login، تعاملی یا bare) می‌سنجد، هرکدام در یک فرایند فرزند تازه. ماتریس حالت‌ها نشان می‌دهد هر حالت چه می‌بیند.
Findings point at the exact startup line, for example "~/.bashrc:8: export PATH=… (below the interactive-only guard at line 2)", so you see why the agent never loaded it.یافته‌ها به خط دقیق فایل راه‌اندازی اشاره می‌کنند، مثل «~/.bashrc:8: export PATH=… (پایین نگهبانِ فقط‌تعاملی در خط ۲)»، تا ببینید چرا ایجنت آن را بارگذاری نکرده.
~/.zshenv for zsh, the file named by $BASH_ENV for non-interactive bash, ~/.profile for login bash, and the honest answer that plain sh reads nothing. Fixes are printed, never applied.~/.zshenv برای zsh، فایلِ معرفی‌شده با $BASH_ENV برای bash غیرتعاملی، ~/.profile برای bash با login، و پاسخ صادقانه که sh ساده چیزی نمی‌خواند. راه‌حل‌ها چاپ می‌شوند، هرگز اعمال نمی‌شوند.
The shell counts the characters of a Persian word (4 characters, 8 bytes). A byte count means the shell is not UTF-8, even when LANG claims otherwise.شل حروف یک کلمهٔ فارسی را می‌شمارد (۴ حرف، ۸ بایت). اگر بایت بشمارد یعنی UTF-8 نیست، حتی اگر LANG ادعای دیگری کند.
Secret values are never read (names only), credentials in proxy URLs are masked, and shellparity never edits your files; --write-snippet writes only the file you name. The tests assert this end to end.مقدار رمزها هرگز خوانده نمی‌شود (فقط نام)، اطلاعات ورود در نشانی پروکسی پوشانده می‌شود و shellparity فایلی را ویرایش نمی‌کند؛ --write-snippet فقط فایلی را که نام ببرید می‌نویسد. آزمون‌ها این را سرتاسر بررسی می‌کنند.
--json, --markdown for your AGENTS.md or CLAUDE.md, and --fail-on error as a hook. --demo runs against a fake home directory, so none of your dotfiles are read.--json، --markdown برای AGENTS.md یا CLAUDE.md و --fail-on error به‌عنوان هوک. --demo روی یک پوشهٔ خانگی ساختگی اجرا می‌شود و هیچ‌کدام از dotfileهای شما خوانده نمی‌شود.
Install & quick startنصب و شروع سریع
pipx install git+https://github.com/mrzroot/shellparity
# or
uv tool install git+https://github.com/mrzroot/shellparityshellparity --demo # real bash against a temporary fake HOMEshellparity # your $SHELL: terminal vs `<shell> -c`
shellparity --shell all # every bash/zsh/sh on this machine
shellparity --project ~/code/app # also check .nvmrc / engines / requires-python
shellparity --markdown > AGENT_ENV.md # paste-ready notes for your agentshellparity --fail-on error # exit 1 if the agent shell is brokenHow it worksچطور کار می‌کند
One POSIX sh script is sourced by each shell and writes records to a temp file, so banners and prompts from your rc files cannot corrupt the result. It only reads: command -v, --version, git config, alias, umask and allow-listed variables.یک اسکریپت POSIX sh در هر شل بارگذاری می‌شود و رکوردها را در فایل موقت می‌نویسد، پس بنر و پرسش‌های rc فایل‌ها نتیجه را خراب نمی‌کنند. فقط می‌خواند: command -v، --version، git config، alias، umask و متغیرهای مجاز.
human (-l -i on a pty), plain (-c), login, interactive and bare (env -i). By default each starts from a clean login-like environment, so the question answered is what the startup files provide.human (-l -i روی pty)، plain (-c)، login، interactive و bare (env -i). به‌طور پیش‌فرض هرکدام از یک محیط تمیز شبیه login شروع می‌کند، پس پرسشِ پاسخ‌داده‌شده این است که فایل‌های راه‌اندازی چه چیزی فراهم می‌کنند.
compare(human, agent) is a pure function: two snapshots in, ranked findings out. No processes and no files, which is why it is easy to test.compare(human, agent) یک تابع خالص است: دو عکس لحظه‌ای می‌گیرد و یافته‌های رتبه‌بندی‌شده می‌دهد. بدون فرایند و بدون فایل، برای همین آزمونش آسان است.
Your rc files are searched textually (export NAME=, PATH entries, version-manager markers, one level of source) so the report can say ~/.zshrc:14, and the fix is written for the right file.rc فایل‌ها متنی جست‌وجو می‌شوند (export NAME=، مسیرهای PATH، نشانه‌های مدیر نسخه، یک سطح source) تا گزارش بتواند بگوید ~/.zshrc:14، و راه‌حل برای فایل درست نوشته می‌شود.
Honest limitsمحدودیت‌های صادقانه
How it comparesمقایسه با ابزارهای دیگر
No existing tool found as of Oct 2026تا مهر ۱۴۰۵ (اکتبر ۲۰۲۶) ابزار مشابهی پیدا نشد that compares one machine's interactive and non-interactive shells across PATH, tool versions, proxy, locale, SSH and git, and prints the fix.که شل تعاملی و غیرتعاملی یک دستگاه را در PATH، نسخهٔ ابزارها، پروکسی، زبان، SSH و git مقایسه کند و راه‌حل بدهد.
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تفاوت |
|---|---|---|
| shell-drift-check.ts gist | Compares bash -lc vs zsh -lc: PATH order, resolution, versions, aliasesbash -lc و zsh -lc را مقایسه می‌کند: ترتیب PATH، مسیر، نسخه، alias | One script, zsh vs bash only; no proxy, locale, SSH, git or TTY checksیک اسکریپت، فقط zsh در برابر bash؛ بدون بررسی پروکسی، زبان، SSH، git و TTY |
| agent-environment-doctor | Diagnoses which skills and rules load in Claude Code and Codexتشخیص اینکه کدام skill و rule در Claude Code و Codex بارگذاری می‌شود | About agent configuration, not the shell environmentدربارهٔ پیکربندی ایجنت است، نه محیط شل |
| env-drift-detector | Drift between machines or teammates against a stored snapshotانحراف بین دستگاه‌ها یا هم‌تیمی‌ها نسبت به یک عکس ذخیره‌شده | Different problem: shellparity is same machine, different shell modeمسئلهٔ دیگری است: shellparity همان دستگاه با حالت شل متفاوت است |
| mise, direnv, asdf | Select tool versions per projectنسخهٔ ابزار را برای هر پروژه انتخاب می‌کنند | They fix version selection; they do not diagnose what a given shell mode seesانتخاب نسخه را درست می‌کنند؛ تشخیص نمی‌دهند هر حالت شل چه می‌بیند |
FAQپرسش‌های متداول
No. Secret-looking variables are listed by name only, values are never read or stored, credentials in proxy URLs are masked, and secret-named assignments quoted from rc files are redacted. The tests assert this end to end.نه. متغیرهای شبیه رمز فقط با نام فهرست می‌شوند، مقدارشان هرگز خوانده یا ذخیره نمی‌شود، اطلاعات ورود در نشانی پروکسی پوشانده می‌شود و تخصیص‌های با نام رمز در خط‌های نقل‌شده از rc فایل‌ها سیاه می‌شوند. آزمون‌ها این را سرتاسر بررسی می‌کنند.
Never. Fixes are printed. --write-snippet FILE is the only way it writes a file, and only the one you name.هرگز. راه‌حل‌ها چاپ می‌شوند. --write-snippet FILE تنها راهی است که فایل می‌نویسد و فقط همان فایلی که نام ببرید.
None in particular. Choose --agent-mode plain, login, interactive or bare to match how your agent starts its shell, and use --shell all to check every bash, zsh and sh on the machine.هیچ ایجنت خاصی را. --agent-mode را plain، login، interactive یا bare انتخاب کنید تا با شیوهٔ راه‌اندازی شل در ایجنت شما بخواند و با --shell all همهٔ bash، zsh و shهای دستگاه را بسنجید.
Linksپیوندها