SmartCLI: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

⚠️ 硬性红线:严禁密集/并发 spawn 真实进程(会卡死/崩溃本机)

2026-07-13 事故:在一个会话里短时间内反复 spawn 大量真实进程(多个 grok/codex/ kiro-cli 全屏 TUI + 反复起关 daemon + mutation 来回 git checkout + verify_fx 每次 又开一堆 PTY 子进程),累积瞬时并发把用户 Windows 机器拖到卡死,用户被迫重启。 单个进程都清理干净了(零残留),元凶是叠加的瞬时并发峰值。

以后必须遵守:

1. 一次只驱动一个 PTY/TUI 会话。 跑完立刻 close + 确认 tui.py list 零残留, 再起下一个。绝不同时开多个 agent CLI(grok/codex/kiro-cli 每个都拉起 node/rust 进程 + winpty,极吃资源)。
2. 重活(verify_fx、run_all、drive-probe 全套)先征得用户同意再跑,且串行、 分开跑,不在一个会话里堆几十个进程。verify_fx 每跑一次要 spawn 一大批 PTY 特效 子进程——尤其重。
3. mutation 验证要克制:来回 git checkout + 重跑 PTY 探针代价高;能用代码级 断言证明的就别反复起真实进程。
4. 看到 spawn 层错误(uv_spawn、EUNKNOWN、exit 143/45、Git-bash spawn 失败)= 系统在示警资源紧张,立即停手,别换 shell 硬上。
5. 需要用户自己跑重活时,建议用 ! python tests/verify_fx.py(前缀 ! 在会话里 直接跑),而不是我又开一批子进程。

Tool priorities

本仓库已建 CodeGraph 索引。优先用配好的工具:

• 查代码用 CodeGraph:搞清符号、调用链、改动影响面时先 codegraph explore， 再决定要不要读文件。别一上来就 grep。
• 搜文件用 rg 不用 grep;找文件用 fd 不用 find。
• 读文件用 Read 工具,不用 cat/head 读代码。
• 本仓库是 Python:ruff/mypy 已装,pyproject.toml 已配好,直接用。

Git commits

• 不加任何 AI 署名(遵循用户全局 CLAUDE.md)。
• 只有用户明确要求才 commit。

Commands

Set PYTHONIOENCODING=utf-8 before running anything (box-drawing/CJK glyphs crash on legacy codepages; CI sets it too).

Use an interpreter that has pyte installed. Every test here imports smartcli_core, so a bare python/python3 from a version manager will die with ModuleNotFoundError: No module named 'pyte' — which reads like a broken test. python -m venv .venv && .venv/bin/pip install -r requirements.txt -e . gives you one; python -m smartcli_core reports what a given interpreter can actually see. And take the exit code directly — python tests/x.py 2>&1 | tail yields tail's status, so an import crash reads as a pass.

# Full self-test aggregator — exit 0 iff everything present passes, and a gate
# that is tracked by git but missing on disk now FAILS rather than skipping
# (renaming or deleting one used to be a green SKIP). Entries may still SKIP
# themselves internally when an external binary is absent — tmux, vim, less — so
# a green run on a host lacking those covers less than a green run here. SLOW: spawns real
# PTY sessions serially. Per the red line above, get user consent before running.
python tests/run_all.py

# One gate needs a test-only dependency, or it reports an internal SKIP (which
# run_all now surfaces even on a PASS). It is NOT in requirements-optional.txt —
# that file is runtime extras with guarded imports; this is test-only, and CI
# installs it inline before running the gate.
pip install hypothesis                    # test_readiness_properties

# Run a single test (each test file is a standalone script, exit 0 = pass):
python tests/test_fx_contract.py          # deterministic, pure-memory — safe
python tests/test_readiness.py
python tests/test_vendor_sync.py
python tests/_drive_probe1.py             # spawns a real PTY — run serially

# fx effect regression (spawns many PTY children — heavy, consent first):
python tests/verify_fx.py

# Coverage over the deterministic subset (no PTY spawn; --full drives PTYs):
python tools/coverage_run.py
python tools/coverage_run.py --xml        # also write coverage.xml for Codecov

# Lint / type-check. PARTLY BLOCKING in CI (lint.yml): the ruff correctness subset
# and mypy fail the build; the full ruff report and format check are advisory.
ruff check --select E9,F63,F7,F82 .       # the blocking subset
mypy                                      # config in pyproject.toml; checks smartcli_core only
ruff check .                              # advisory (full style/modernization backlog)
# mypy MUST see the real pyte. Without it, ignore_missing_imports degrades
# pyte.Screen to Any, which BOTH hides real errors in the subclass and reports a
# correct `type: ignore` as unused — that once failed CI on a clean tree while two
# genuine errors went unseen. Run it in an env where `requirements.txt` is installed.

# cmd-art effect engine (run from skills/cmd-art):
python -m fx list                         # live catalog (30 effects)
python -m fx play donut --seconds 5
python -m fx gallery

# tui-ui layout engine (run from skills/tui-ui):
python -m ui widgets                      # 17 widgets
python self_test.py

# drive-tui: drive a real interactive program (ONE session at a time).
# Use "python3 -i -q" (POSIX) / "py -i -q" (Windows) — don't assume a bare
# `python` exists on PATH (modern macOS has none):
python skills/drive-tui/scripts/tui.py start --cmd "python3 -i -q" --cols 100 --rows 30
python skills/drive-tui/scripts/tui.py wait-regex --id <SID> ">>> " --timeout-ms 15000
python skills/drive-tui/scripts/tui.py send-line --id <SID> "print(6*7)"
python skills/drive-tui/scripts/tui.py snapshot --id <SID>
python skills/drive-tui/scripts/tui.py close --id <SID>
python skills/drive-tui/scripts/tui.py list   # verify zero leaked sessions

# After ANY change to smartcli_core: re-sync the vendored copy and verify.
python tools/sync_vendor.py
python tests/test_vendor_sync.py