{"id":36985379,"url":"https://github.com/wangnov/shnote","last_synced_at":"2026-02-24T12:06:19.075Z","repository":{"id":328758204,"uuid":"1116593158","full_name":"Wangnov/shnote","owner":"Wangnov","description":"让 AI Agent 的命令不再神秘 —— 强制 AI 在执行命令前说明 WHAT/WHY，一眼看懂复杂命令 | Demystify AI Agent commands — Force AI to explain WHAT/WHY before execution, understand complex commands at a glance","archived":false,"fork":false,"pushed_at":"2025-12-22T04:18:26.000Z","size":2797,"stargazers_count":8,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T19:42:18.701Z","etag":null,"topics":["claude-code","codex","gemini-cli","nodejs","pueue","python","rust","terminal","uv"],"latest_commit_sha":null,"homepage":"https://github.com/wangnov/shnote","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wangnov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-15T05:25:08.000Z","updated_at":"2025-12-25T12:17:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Wangnov/shnote","commit_stats":null,"previous_names":["wangnov/shnote"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/Wangnov/shnote","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wangnov%2Fshnote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wangnov%2Fshnote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wangnov%2Fshnote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wangnov%2Fshnote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wangnov","download_url":"https://codeload.github.com/Wangnov/shnote/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wangnov%2Fshnote/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28405148,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T21:51:37.118Z","status":"ssl_error","status_checked_at":"2026-01-13T21:45:14.585Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex","gemini-cli","nodejs","pueue","python","rust","terminal","uv"],"created_at":"2026-01-13T23:01:40.669Z","updated_at":"2026-01-13T23:01:41.527Z","avatar_url":"https://github.com/Wangnov.png","language":"Rust","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.svg\" alt=\"shnote logo\" width=\"120\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eshnote\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/wangnov/shnote/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/wangnov/shnote/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/wangnov/shnote\"\u003e\u003cimg src=\"https://codecov.io/gh/wangnov/shnote/branch/main/graph/badge.svg\" alt=\"Coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/wangnov/shnote/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/wangnov/shnote\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey\" alt=\"Platform\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/rust-1.74%2B-orange\" alt=\"Rust\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/shnote_promo.jpg\" alt=\"shnote - From confusion to clarity\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003e 一个轻量级命令包装器，强制让 AI 在编写复杂命令的时候编写出该命令的 WHAT/WHY，方便用户直观快速地理解 AI Agent 编写的复杂命令（如临时编写的 Python 脚本）\n\n\u003e A lightweight command wrapper that forces AI to document WHAT/WHY when writing complex commands, helping users quickly understand complex commands written by AI Agents (such as temporary Python scripts)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#介绍\"\u003e中文\u003c/a\u003e | \u003ca href=\"#introduction\"\u003eEnglish\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 介绍\n\n### 特性\n\n- **强制 WHAT/WHY**：对执行类命令（`run/py/node/pip/npm/npx`）要求在子命令前填写 `--what/--why`\n- **协议化输出**：`WHAT:` 和 `WHY:` 输出在最前面，便于解析\n- **完全透传**：命令输出不做拦截/改写（stdout/stderr 继承），用户自己决定如何使用 pueue\n- **多命令支持**：shell、Python、Node.js，以及 `pip/npm/npx` 透传封装\n- **跨平台**：支持 macOS、Linux、Windows\n- **国际化**：支持中英双语帮助和消息\n\n### 效果展示\n\n在不同 AI 工具中使用 shnote 的实际效果：\n\n**Claude Code** - 用 Python 生成二维码，清晰显示命令意图\n\n\u003cimg src=\"assets/Chinese_example_claude.png\" alt=\"Claude Code 示例\" width=\"100%\"\u003e\n\n**OpenAI Codex CLI** - 运行复杂 Node.js 脚本，一目了然\n\n\u003cimg src=\"assets/Chinese_example_codex.png\" alt=\"Codex CLI 示例\" width=\"100%\"\u003e\n\n**Gemini CLI** - 执行复杂管道命令，不再困惑\n\n\u003cimg src=\"assets/Chinese_example_gemini.png\" alt=\"Gemini CLI 示例\" width=\"100%\"\u003e\n\n### 安装\n\n#### 1. 安装 shnote\n\nmacOS / Linux:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/wangnov/shnote/main/scripts/install.sh | sh\n```\n\nHomebrew (macOS):\n\n```bash\nbrew tap wangnov/tap\nbrew install shnote\n```\n\nWindows (PowerShell):\n\n```powershell\nirm https://raw.githubusercontent.com/wangnov/shnote/main/scripts/install.ps1 | iex\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e🇨🇳 国内用户（使用 GitHub 代理加速）\u003c/summary\u003e\n\n可用代理列表：https://ghproxylist.com/\n\nmacOS / Linux:\n\n```bash\ncurl -fsSL https://ghfast.top/https://raw.githubusercontent.com/wangnov/shnote/main/scripts/install.sh | GITHUB_PROXY=https://ghfast.top sh\n```\n\nWindows (PowerShell):\n\n```powershell\n$env:GITHUB_PROXY = \"https://ghfast.top\"; irm https://ghfast.top/https://raw.githubusercontent.com/wangnov/shnote/main/scripts/install.ps1 | iex\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e从源码安装\u003c/summary\u003e\n\n```bash\ncargo install --path .\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e通过 Cargo 安装（crates.io）\u003c/summary\u003e\n\n```bash\ncargo install shnote\n```\n\n\u003c/details\u003e\n\n#### 2. 初始化 AI 工具（必需）\n\n安装后，需要为你使用的 AI 工具初始化 shnote 规则：\n\n```bash\n# 根据你使用的 AI 工具选择一个或多个（默认用户级）\nshnote init claude   # Claude Code\nshnote init codex    # OpenAI Codex CLI\nshnote init gemini   # Gemini CLI\n\n# 项目级初始化（写入当前目录）\nshnote init -s project claude   # 或 shnote init --scope p claude\n```\n\n**这一步做了什么？**\n\n将 shnote 的使用规则写入 AI 工具的 **memory 文件**：\n\n| 范围 | AI 工具 | 写入位置 |\n|------|---------|----------|\n| user (默认) | Claude Code (\u003e= 2.0.64) | `~/.claude/rules/shnote.md` |\n| user | Claude Code (\u003c 2.0.64) | `~/.claude/CLAUDE.md` |\n| user | OpenAI Codex CLI | `~/.codex/AGENTS.md` |\n| user | Gemini CLI | `~/.gemini/GEMINI.md` |\n| project | Claude Code (\u003e= 2.0.64) | `.claude/rules/shnote.md` |\n| project | Claude Code (\u003c 2.0.64) | `.claude/CLAUDE.md` |\n| project | OpenAI Codex CLI | `.codex/AGENTS.md` |\n| project | Gemini CLI | `.gemini/GEMINI.md` |\n\nAI 在执行命令时会读取这些规则，自动使用 shnote 并填写 WHAT/WHY。\n\n\u003cdetails\u003e\n\u003csummary\u003e💡 为什么不使用 Skills 方式？\u003c/summary\u003e\n\nSkills 是 Claude Code 的另一种扩展机制，但 **Bash 工具的默认优先级高于 Skills**。当 AI 需要执行命令时，会优先使用内置的 Bash 工具而不是调用 Skill。\n\n因此，必须通过 memory 文件（rules/CLAUDE.md）进行提示词工程，在 AI 决定使用 Bash 之前就告诉它\"应该用 shnote 包装命令\"。\n\n\u003c/details\u003e\n\n#### 3. 安装 pueue（可选）\n\n[pueue](https://github.com/Nukesor/pueue) 是一个命令行任务管理器，用于在后台运行长时间任务。\n\n**为什么需要 pueue？**\n\n- **Codex CLI / Gemini CLI**：没有内置的后台任务功能，长时间运行的命令会阻塞 AI，必须通过 pueue 放到后台\n- **Claude Code**：可以不使用 pueue，因为 Claude Code 有更好的设计（Background Bash 和 Async SubAgent）\n\n安装 pueue：\n\n```bash\nshnote setup\n\n# 国内用户可使用代理加速\nGITHUB_PROXY=https://ghfast.top shnote setup\n```\n\n这会将 pueue 和 pueued 安装到 `~/.shnote/bin/`。按提示将此目录添加到 PATH：\n\n```bash\n# 添加到 ~/.bashrc 或 ~/.zshrc\nexport PATH=\"$HOME/.shnote/bin:$PATH\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e📸 pueue 使用示例（Codex CLI）\u003c/summary\u003e\n\n\u003cimg src=\"assets/Chinese_pueue_codex.png\" alt=\"pueue 使用示例\" width=\"100%\"\u003e\n\n\u003c/details\u003e\n\n### 用法\n\n#### Shell 命令\n\n```bash\nshnote --what \"列出文件\" --why \"查看项目结构\" run ls -la\n```\n\n#### Python 脚本\n\n```bash\n# 内联代码\nshnote --what \"打印消息\" --why \"测试Python\" py -c 'print(\"Hello\")'\n\n# 文件\nshnote --what \"运行脚本\" --why \"处理数据\" py -f script.py\n\n# Heredoc\nshnote --what \"多行脚本\" --why \"复杂逻辑\" py --stdin \u003c\u003c'EOF'\nimport sys\nprint(\"Python version:\", sys.version)\nEOF\n```\n\n#### Node.js 脚本\n\n```bash\nshnote --what \"运行Node\" --why \"处理JSON\" node -c 'console.log(\"Hello\")'\n```\n\n#### pip / npm / npx（透传）\n\n```bash\nshnote --what \"查看 pip 版本\" --why \"确认环境\" pip --version\nshnote --what \"查看 npm 版本\" --why \"确认环境\" npm --version\nshnote --what \"查看 npx 版本\" --why \"确认环境\" npx --version\n```\n\n#### pueue 后台任务（透传）\n\n```bash\nshnote --what \"后台编译\" --why \"编译大项目\" run pueue add -- cargo build --release\n```\n\n### 输出格式\n\n```\nWHAT: 列出文件\nWHY:  查看项目结构\n\u003c命令实际输出...\u003e\n```\n\n\u003e 注意：如果你在 `shnote ...` 外层再接管道/过滤（例如 `| tail -5`、`| head -20`、`| grep ...`），这些工具可能会截断/过滤掉前两行，从而导致输出里看不到 `WHAT/WHY`。\n\u003e 这不影响 `shnote` 的强制记录：请以实际执行命令里的 `--what` / `--why` 参数为准（它们必须写在子命令前，通常在终端/日志里总能看到）。\n\u003e\n\u003e 另外：`--what/--why` 只允许用于 `run/py/node/pip/npm/npx`，其他命令（如 `config/init/setup/doctor/completions`）不接受这两个参数。\n\n### 配置\n\n配置文件默认位置：\n\n- macOS/Linux：`~/.shnote/config.toml`\n- Windows：`%USERPROFILE%\\.shnote\\config.toml`\n\n也可以通过 `shnote config path` 查看实际路径。\n\n```bash\n# 查看配置\nshnote config list\n\n# 获取某个配置\nshnote config get python\n\n# 设置配置\nshnote config set python /usr/bin/python3\nshnote config set shell bash\nshnote config set language zh\nshnote config set color false\nshnote config set what_color cyan\nshnote config set why_color magenta\n\n# 重置配置\nshnote config reset\n\n# 查看配置文件路径\nshnote config path\n```\n\n#### 可配置项\n\n| 键 | 说明 | 默认值 |\n|----|------|--------|\n| python | Python 解释器路径 | python3 |\n| node | Node.js 解释器路径 | node |\n| shell | Shell 类型 (auto/sh/bash/zsh/pwsh/cmd) | auto |\n| language | 语言 (auto/zh/en) | auto |\n| output | 输出模式 (default/quiet) | default |\n| color | WHAT/WHY 颜色开关 (true/false) | true |\n| what_color | WHAT 颜色 (default/black/red/green/yellow/blue/magenta/cyan/white/bright_*) | cyan |\n| why_color | WHY 颜色 (default/black/red/green/yellow/blue/magenta/cyan/white/bright_*) | magenta |\n\n### 其他命令\n\n```bash\n# 查看安装信息（版本、路径、组件状态）\nshnote info\n\n# 更新到最新版本\nshnote update\n\n# 国内用户可使用代理加速\nGITHUB_PROXY=https://ghfast.top shnote update\n\n# 仅检查更新，不安装\nshnote update --check\n\n# 卸载 shnote（交互式确认）\nshnote uninstall\n\n# 卸载 shnote（跳过确认）\nshnote uninstall --yes\n\n# 检查环境依赖\nshnote doctor\n\n# 安装/更新 pueue 与 pueued 到 shnote 的 bin 目录（macOS/Linux 通常为 ~/.shnote/bin；Windows 为 %USERPROFILE%\\.shnote\\bin）\n# 优先使用内嵌二进制；未内嵌时会联网下载并校验 SHA256\n# macOS/Linux 依赖 curl（或 wget）与 shasum；Windows 使用 PowerShell 与 certutil\nshnote setup\n\n# Initialize AI tool rules\nshnote init claude   # 会先检测 claude 版本：\u003e= 2.0.64 写入 ~/.claude/rules/shnote.md（覆盖）；否则写入/更新 ~/.claude/CLAUDE.md（追加/替换标记区块）\nshnote init codex    # 写入/更新 ~/.codex/AGENTS.md（追加/替换标记区块）\nshnote init gemini   # 写入/更新 ~/.gemini/GEMINI.md（追加/替换标记区块）\n\n# 使用 --scope/-s 指定范围（user 或 project，可简写为 u 或 p）\nshnote init -s project claude   # 写入当前目录 .claude/CLAUDE.md\nshnote init --scope p codex     # 写入当前目录 .codex/AGENTS.md\n```\n\n### Shell 补全\n\nshnote 支持为多种 shell 生成补全脚本。\n\n#### Bash\n\n```bash\n# 添加到 ~/.bashrc\neval \"$(shnote completions bash)\"\n\n# 或者保存到文件\nshnote completions bash \u003e ~/.local/share/bash-completion/completions/shnote\n```\n\n#### Zsh\n\n```bash\n# 添加到 ~/.zshrc\neval \"$(shnote completions zsh)\"\n\n# 或者保存到文件（确保目录在 $fpath 中）\nshnote completions zsh \u003e ~/.zsh/completions/_shnote\n```\n\n#### Fish\n\n```bash\nshnote completions fish \u003e ~/.config/fish/completions/shnote.fish\n```\n\n#### PowerShell\n\n```powershell\n# 添加到 PowerShell 配置文件\nshnote completions powershell | Out-String | Invoke-Expression\n```\n\n#### 支持的 Shell\n\n- `bash` - Bash\n- `zsh` - Zsh\n- `fish` - Fish\n- `powershell` - PowerShell\n- `elvish` - Elvish\n\n### 语言支持\n\n支持中英双语。语言检测优先级：\n\n1. `--lang` 命令行参数\n2. 配置文件中的 `language`\n3. 环境变量 `SHNOTE_LANG`、`LC_ALL`、`LC_MESSAGES`、`LANGUAGE`、`LANG`\n4. 默认：English\n\n---\n\n## Introduction\n\n`shnote` is a lightweight command wrapper that enforces WHAT/WHY documentation before executing commands, producing structured output that makes it easy to understand complex commands (like temporary multi-line Python scripts) executed by AI Agents.\n\n### Features\n\n- **Mandatory WHAT/WHY**: Execution commands (`run/py/node/pip/npm/npx`) require `--what/--why` flags before the subcommand\n- **Structured Output**: `WHAT:` and `WHY:` are output first for easy parsing\n- **Full Passthrough**: Command output is not intercepted/modified (stdout/stderr inherited), users decide how to use pueue\n- **Multi-command Support**: Shell, Python, Node.js, plus `pip/npm/npx` passthrough wrappers\n- **Cross-platform**: Supports macOS, Linux, Windows\n- **Internationalization**: Supports English and Chinese help/messages\n\n### Screenshots\n\nSee shnote in action with different AI tools:\n\n**Claude Code** - Generate QR code with Python, intent clearly displayed\n\n\u003cimg src=\"assets/English_example_claude.png\" alt=\"Claude Code Example\" width=\"100%\"\u003e\n\n**OpenAI Codex CLI** - Run complex Node.js scripts with clarity\n\n\u003cimg src=\"assets/English_example_codex.png\" alt=\"Codex CLI Example\" width=\"100%\"\u003e\n\n**Gemini CLI** - Execute complex pipeline commands without confusion\n\n\u003cimg src=\"assets/English_example_gemini.png\" alt=\"Gemini CLI Example\" width=\"100%\"\u003e\n\n### Installation\n\n#### 1. Install shnote\n\nmacOS / Linux:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/wangnov/shnote/main/scripts/install.sh | sh\n```\n\nHomebrew (macOS):\n\n```bash\nbrew tap wangnov/tap\nbrew install shnote\n```\n\nWindows (PowerShell):\n\n```powershell\nirm https://raw.githubusercontent.com/wangnov/shnote/main/scripts/install.ps1 | iex\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eFrom Source\u003c/summary\u003e\n\n```bash\ncargo install --path .\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall via Cargo (crates.io)\u003c/summary\u003e\n\n```bash\ncargo install shnote\n```\n\n\u003c/details\u003e\n\n#### 2. Initialize AI Tools (Required)\n\nAfter installation, initialize shnote rules for your AI tool:\n\n```bash\n# Choose one or more based on your AI tool (default: user-level)\nshnote init claude   # Claude Code\nshnote init codex    # OpenAI Codex CLI\nshnote init gemini   # Gemini CLI\n\n# Project-level initialization (writes to current directory)\nshnote init -s project claude   # or shnote init --scope p claude\n```\n\n**What does this do?**\n\nWrites shnote usage rules to the AI tool's **memory file**:\n\n| Scope | AI Tool | Write Location |\n|-------|---------|----------------|\n| user (default) | Claude Code (\u003e= 2.0.64) | `~/.claude/rules/shnote.md` |\n| user | Claude Code (\u003c 2.0.64) | `~/.claude/CLAUDE.md` |\n| user | OpenAI Codex CLI | `~/.codex/AGENTS.md` |\n| user | Gemini CLI | `~/.gemini/GEMINI.md` |\n| project | Claude Code (\u003e= 2.0.64) | `.claude/rules/shnote.md` |\n| project | Claude Code (\u003c 2.0.64) | `.claude/CLAUDE.md` |\n| project | OpenAI Codex CLI | `.codex/AGENTS.md` |\n| project | Gemini CLI | `.gemini/GEMINI.md` |\n\nThe AI reads these rules when executing commands and will automatically use shnote with WHAT/WHY.\n\n\u003cdetails\u003e\n\u003csummary\u003e💡 Why not use Skills?\u003c/summary\u003e\n\nSkills is another extension mechanism in Claude Code, but **the Bash tool has higher default priority than Skills**. When AI needs to execute commands, it prefers the built-in Bash tool over calling a Skill.\n\nTherefore, we must use memory files (rules/CLAUDE.md) for prompt engineering, telling the AI to \"wrap commands with shnote\" before it decides to use Bash.\n\n\u003c/details\u003e\n\n#### 3. Install pueue (Optional)\n\n[pueue](https://github.com/Nukesor/pueue) is a command-line task manager for running long-running tasks in the background.\n\n**Why pueue?**\n\n- **Codex CLI / Gemini CLI**: No built-in background task support. Long-running commands block the AI and must be run via pueue\n- **Claude Code**: pueue is optional. Claude Code has better built-in solutions (Background Bash and Async SubAgent)\n\nInstall pueue:\n\n```bash\nshnote setup\n```\n\nThis installs pueue and pueued to `~/.shnote/bin/`. Add this directory to your PATH as prompted:\n\n```bash\n# Add to ~/.bashrc or ~/.zshrc\nexport PATH=\"$HOME/.shnote/bin:$PATH\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e📸 pueue Usage Example (Codex CLI)\u003c/summary\u003e\n\n\u003cimg src=\"assets/English_pueue_codex.png\" alt=\"pueue usage example\" width=\"100%\"\u003e\n\n\u003c/details\u003e\n\n### Usage\n\n#### Shell Commands\n\n```bash\nshnote --what \"List files\" --why \"Check project structure\" run ls -la\n```\n\n#### Python Scripts\n\n```bash\n# Inline code\nshnote --what \"Print message\" --why \"Test Python\" py -c 'print(\"Hello\")'\n\n# File\nshnote --what \"Run script\" --why \"Process data\" py -f script.py\n\n# Heredoc\nshnote --what \"Multi-line script\" --why \"Complex logic\" py --stdin \u003c\u003c'EOF'\nimport sys\nprint(\"Python version:\", sys.version)\nEOF\n```\n\n#### Node.js Scripts\n\n```bash\nshnote --what \"Run Node\" --why \"Process JSON\" node -c 'console.log(\"Hello\")'\n```\n\n#### pip / npm / npx (Passthrough)\n\n```bash\nshnote --what \"Check pip version\" --why \"Verify environment\" pip --version\nshnote --what \"Check npm version\" --why \"Verify environment\" npm --version\nshnote --what \"Check npx version\" --why \"Verify environment\" npx --version\n```\n\n#### pueue Background Tasks (Passthrough)\n\n```bash\nshnote --what \"Background build\" --why \"Compile large project\" run pueue add -- cargo build --release\n```\n\n### Output Format\n\n```\nWHAT: List files\nWHY:  Check project structure\n\u003cactual command output...\u003e\n```\n\n\u003e Note: If you pipe `shnote ...` through filters like `| tail -5`, `| head -20`, or `| grep ...`, these tools may truncate/filter the first two lines, hiding the `WHAT/WHY` output.\n\u003e This doesn't affect shnote's mandatory documentation: the `--what` / `--why` parameters in the actual command line (which must appear before the subcommand) are always visible in the terminal/logs.\n\u003e\n\u003e Also: `--what/--why` are only allowed for `run/py/node/pip/npm/npx`. Other commands (`config/init/setup/doctor/completions`) don't accept these parameters.\n\n### Configuration\n\nDefault config file location:\n\n- macOS/Linux: `~/.shnote/config.toml`\n- Windows: `%USERPROFILE%\\.shnote\\config.toml`\n\nUse `shnote config path` to view the actual path.\n\n```bash\n# View config\nshnote config list\n\n# Get a config value\nshnote config get python\n\n# Set config values\nshnote config set python /usr/bin/python3\nshnote config set shell bash\nshnote config set language en\nshnote config set color false\nshnote config set what_color cyan\nshnote config set why_color magenta\n\n# Reset config\nshnote config reset\n\n# View config file path\nshnote config path\n```\n\n#### Configuration Keys\n\n| Key | Description | Default |\n|-----|-------------|---------|\n| python | Python interpreter path | python3 |\n| node | Node.js interpreter path | node |\n| shell | Shell type (auto/sh/bash/zsh/pwsh/cmd) | auto |\n| language | Language (auto/zh/en) | auto |\n| output | Output mode (default/quiet) | default |\n| color | Colorize WHAT/WHY header (true/false) | true |\n| what_color | WHAT color (default/black/red/green/yellow/blue/magenta/cyan/white/bright_*) | cyan |\n| why_color | WHY color (default/black/red/green/yellow/blue/magenta/cyan/white/bright_*) | magenta |\n\n### Other Commands\n\n```bash\n# View installation info (version, paths, component status)\nshnote info\n\n# Update to the latest version\nshnote update\n\n# Only check for updates, don't install\nshnote update --check\n\n# Uninstall shnote (interactive confirmation)\nshnote uninstall\n\n# Uninstall shnote (skip confirmation)\nshnote uninstall --yes\n\n# Check environment dependencies\nshnote doctor\n\n# Install/update pueue and pueued to shnote's bin directory (usually ~/.shnote/bin on macOS/Linux; %USERPROFILE%\\.shnote\\bin on Windows)\n# Prefers embedded binaries; downloads and verifies SHA256 when not embedded\n# macOS/Linux requires curl (or wget) and shasum; Windows uses PowerShell and certutil\nshnote setup\n\n# Initialize AI tool rules\nshnote init claude   # Detects claude version: \u003e= 2.0.64 writes to ~/.claude/rules/shnote.md (overwrite); otherwise writes/updates ~/.claude/CLAUDE.md (append/replace marked section)\nshnote init codex    # Writes/updates ~/.codex/AGENTS.md (append/replace marked section)\nshnote init gemini   # Writes/updates ~/.gemini/GEMINI.md (append/replace marked section)\n\n# Use --scope/-s to specify scope (user or project, can be abbreviated as u or p)\nshnote init -s project claude   # Writes to .claude/CLAUDE.md in current directory\nshnote init --scope p codex     # Writes to .codex/AGENTS.md in current directory\n```\n\n### Shell Completion\n\nshnote can generate completion scripts for various shells.\n\n#### Bash\n\n```bash\n# Add to ~/.bashrc\neval \"$(shnote completions bash)\"\n\n# Or save to a file\nshnote completions bash \u003e ~/.local/share/bash-completion/completions/shnote\n```\n\n#### Zsh\n\n```bash\n# Add to ~/.zshrc\neval \"$(shnote completions zsh)\"\n\n# Or save to a file (ensure directory is in $fpath)\nshnote completions zsh \u003e ~/.zsh/completions/_shnote\n```\n\n#### Fish\n\n```bash\nshnote completions fish \u003e ~/.config/fish/completions/shnote.fish\n```\n\n#### PowerShell\n\n```powershell\n# Add to PowerShell profile\nshnote completions powershell | Out-String | Invoke-Expression\n```\n\n#### Supported Shells\n\n- `bash` - Bash\n- `zsh` - Zsh\n- `fish` - Fish\n- `powershell` - PowerShell\n- `elvish` - Elvish\n\n### Language Support\n\nSupports English and Chinese. Language detection priority:\n\n1. `--lang` command line argument\n2. `language` in config file\n3. Environment variables: `SHNOTE_LANG`, `LC_ALL`, `LC_MESSAGES`, `LANGUAGE`, `LANG`\n4. Default: English\n\n---\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwangnov%2Fshnote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwangnov%2Fshnote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwangnov%2Fshnote/lists"}