inspect-session

pitfall-harness

English · 中文

Pitfalls met while setting up machines for AI coding agents -- each with its symptom, its root cause, and how that cause was proven. The configs are the fish; the debugging method is the rod. It all comes from one person's several machines, driven mainly by Claude Code and the Antigravity CLI, with networking through a local proxy. The skills are also published on their own, ready to install: pitfall-harness-skills.

---

Philosophy: The Agent as System Operator & Closed-Loop Distillation

This project treats the AI agent as a real-world system operator. Humans define goals in natural language, prompting the agent to conduct empirical, vibe-driven exploration in live OS and development environments. Once an operational path succeeds, findings are solidified into verifiable, reproducible, and deployable Markdown, configs, scripts, and skills, ensuring future agents never have to re-explore from scratch.

Natural language goal → Agent directly operates live system & executes commands → Observe symptoms → Pinpoint & empirically prove root causes → Working config/procedure → Solidify into configs, scripts, READMEs, skills, & checklists → Future agents reproduce via deterministic knowledge.

One-off Agent Exploration
            ↓
        Experience
            ↓
   Structured Conclusions
      ↙     ↓      ↘
  Config  README   Skill
      ↘     ↓      ↙
  Executable Specifications
            ↓
    Future Agent Reuse

Documentation Audience & Language Conventions

Markdown files in this repository are strictly divided by audience:

• Agent-Facing: Written in the format most natural, context-dense, and unambiguous for LLMs -- English.
• Human-Facing: Chinese versions serve as human reference, produced via direct translation sufficient for human comprehension.
• English First: When editing or authoring documentation, always write the agent-facing English version first, then directly translate it into Chinese. The former "Chinese canonical first" requirement is eliminated.

---

AI agents: read AGENTS.md first -- the directory map, a "to do X, edit these files" table, the files that must change together, and the pre-commit checks.

Two kinds of content live here: config files you can deploy as-is, and conclusions left behind by debugging -- the latter is usually worth more than the config itself, because it records why things are the way they are.

WSL migration in progress. Ubuntu 24.04 was the primary distro; day-to-day work has moved to Fedora 44 and the configuration is being aligned to it. Both are installed side by side: Ubuntu is still the WSL default (the * in wsl -l -v), but commands are actually typed in Fedora. The three core shell-config layers (.zshenv, .shell_wslfn, .shell_common) hash identically on both; what still differs is either dictated by the distro (Fedora's fcitx5 block, its /etc/bashrc chain) or still converging. The full comparison, split into what is avoidable and what is not, is in wsl/distro-differences.md.

Most references to Ubuntu elsewhere in these docs still hold; where they do not, the difference is recorded in that file.

Every path, username, machine identifier, port and timestamp is redacted ($HOME, <your-linux-user>, <your-windows-user>, <vm-1>, <proxy-port>, <ssh-port>, <t-created>), and email addresses are written as [email protected]. Substitute your own before deploying.

The <t-...> tokens under wsl/storage/forensics/ are stable placeholders: the same token means the same instant wherever it appears, so timestamp columns can still be compared across forensic blocks. Intervals between events are spelled out in prose.

---

Start here

---

Layout

Every top-level directory except tmp/ has a README.md index. Where a directory has a files/ subdirectory, files/ holds the deployable originals and everything else is documentation.

shell/ -- four-layer bash / zsh config (shared by WSL and native Linux)

~/.zshenv -> ~/.shell_wslfn -> ~/.shell_common <- ~/.zshrc / ~/.bashrc. The README explains the split and its three hard rules (the shared file holds only what is valid in both shells, conda init is never shared, functions instead of aliases); the originals are in files/. The WSL-only interop functions skip themselves on native Linux via a /proc/version check.

wsl/ -- WSL2

The core idea is appendWindowsPath=false plus explicit function bridging: do not inject Windows' several hundred PATH entries -- wrap only the handful of .exes you actually need in shell functions.

windows/ -- the Windows side

terminal/ (Windows Terminal config) · powershell/ (PowerShell 7 profile, PSReadLine, closing every File Explorer window without killing the shell, closing or killing Typora) · ime-keyboard/ (stray keyboard layouts after uninstalling languages, first-Pinyin-letter-leaks-as-Latin checklist) · context-menu/ (diagnosing and trimming context-menu entries) · windows-update/ (pin feature updates to 24H2 while keeping updates visible)

linux-desktop/ -- native Linux desktop

Rebuild notes for Linux M