agentleFS
Ethan9123Ethan9123/wx-life-analysis/AGENTS.md

wx-life-analysis

AGENTS.md0 starsChanged 6 months agoApache-2.0View on GitHub

This file is the contract for any autonomous code-agent (Codex, Claude Code, Cursor, Aider, etc.) working in this repository. A template for analyzing personal WeChat data using @jackwener/wx-cli + an AI agent. The repo itself contains only: End users clone this repo, run scripts locally to pull their own WeChat data into people/<name>/ and projects/<name>/, and then have an agent help them analyze it. That user data never enters the repo. Our .gitignore enforces this.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository7 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

18 rules. About 0 are common, 7 are distinctive, and 11 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Tools must be cross-platform-aware: If you add a .ps1, consider whether a .sh equivalent makes sense.

    line 26
  2. Very specific:

    wx-cli is a dependency, not a fork: Don't reimplement its commands.

    line 27
  3. Very specific:

    Use [CmdletBinding()] + param() blocks with typed parameters and Mandatory where appropriate.

    line 82
  4. Very specific:

    Use plain CommonJS (require) — no build step, no TypeScript, no bundler.

    line 89
  5. Very specific:

    Read args from process.argv.

    line 91
  6. Distinctive:

    Use fenced code blocks with language tags.

    line 97
  7. Distinctive:

    Keep line length flexible — these are read by humans and LLMs, not diffed by code review tools.

    line 98
  8. Very specific:

    Add the script to tools/.

    line 105
  9. Distinctive:

    Document it in README.md under "Commands".

    line 106
  10. Distinctive:

    Update CLAUDE.md if the new tool changes the analysis workflow.

    line 107
  11. Distinctive:

    Test it locally on dummy data: Never use real user data in tests.

    line 108
  12. Very specific:

    Use placeholder names (张三, Acme Project).

    line 114
  13. Very specific:

    Use YAML frontmatter with this minimum fixed schema (read by tools/status.ps1):

    line 117
  14. Very specific:

    Don't reimplement wx-cli features (decryption, querying, daemon).

    line 143
  15. Distinctive:

    Don't add a build system, bundler, or framework.

    line 144
  16. Very specific:

    Don't add telemetry, analytics, or any network calls beyond what wx-cli already does.

    line 145
  17. Very specific:

    Don't add a web UI. HTML files generated for personal use (like task-plan.html) are static and gitignored.

    line 146
  18. Distinctive:

    Don't add cloud sync, backup, or "share" features.

    line 147

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

This file is the contract for any autonomous code-agent (Codex, Claude Code, Cursor, Aider, etc.) working in this repository.

What this repo is

A template for analyzing personal WeChat data using @jackwener/wx-cli + an AI agent. The repo itself contains only:

  • documentation (README.md, AGENTS.md, CLAUDE.md)
  • scripts (tools/)
  • empty templates (people/_template/, projects/_template/)
  • license + gitignore

End users clone this repo, run scripts locally to pull their own WeChat data into people/<name>/ and projects/<name>/, and then have an agent help them analyze it. That user data never enters the repo. Our .gitignore enforces this.

Hard rules

  1. Do not commit user data. people/<name>/, projects/<name>/, topics/<name>/ are all gitignored. If a PR adds files there (outside _template/), reject it.
  2. No real names, real chat content, or real contact info in:
    • source code
    • docs
    • tests
    • issue/PR descriptions
    • commit messages
  3. Use placeholders consistently: 张三 / 李四 / Alice / Bob / Acme Corp.
  4. Tools must be cross-platform-aware. If you add a .ps1, consider whether a .sh equivalent makes sense. Don't break Windows when adding *nix tooling.
  5. wx-cli is a dependency, not a fork. Don't reimplement its commands. Always shell out to wx ....

Repository structure

.
├── README.md                       Human-facing intro
├── AGENTS.md                       This file (Codex / Cursor / Aider, also auto-read by Copilot)
├── CLAUDE.md                       Claude Code specific guidance
├── SKILL.md                        Vercel Skills entry (npx skills add)
├── LICENSE                         Apache-2.0
├── .gitignore                      Blocks user data
├── .claude/skills/                 Project-scoped Claude Code skills (auto-load on description match)
│   ├── mbti-analysis/SKILL.md
│   ├── subtext-reading/SKILL.md
│   ├── task-extract/SKILL.md
│   └── self-mirror/SKILL.md
├── .github/
│   ├── workflows/                  CI (no-data-leaked, gitleaks-action)
│   ├── ISSUE_TEMPLATE/             Issue templates with privacy checklists
│   ├── pull_request_template.md
│   └── copilot-instructions.md     GitHub Copilot entry → references this file
├── docs/                           Long-form methodology docs
│   ├── mbti-analysis.md
│   ├── subtext-reading.md
│   ├── task-extract.md
│   └── voice-transcription.md
├── tools/                          Scripts (PowerShell + Bash + Node)
│   ├── extract-pdf.js
│   ├── contacts.ps1 / .sh          fuzzy contact lookup (verify before refresh)
│   ├── refresh.ps1 / .sh           incremental chat + SNS + stats pull
│   ├── refresh-group.ps1 / .sh
│   ├── attachments.ps1 / .sh       list / extract chat attachments (PDFs, images, files)
│   ├── voice-transcribe.ps1 / .sh  silk → wav → whisper pipeline for voice notes (local-first)
│   ├── status.ps1 / .sh
│   ├── self-mirror.ps1
│   ├── task-extract.ps1
│   ├── digest.ps1 / .sh
│   └── warmth.ps1 / .sh
├── people/_template/               Profile scaffold (full YAML schema)
├── projects/_template/             Project notes scaffold
└── .gitleaks.toml                  Custom PII rules (per-fork .gitleaks.local.toml is gitignored)

Coding conventions

PowerShell scripts (tools/*.ps1)

  • Target PowerShell 5.1+ (Windows default). Avoid pwsh-only features unless guarded.
  • Set UTF-8 encoding at the top of every script:
    $OutputEncoding = [System.Text.Encoding]::UTF8
    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
    chcp 65001 | Out-Null
  • Use [CmdletBinding()] + param() blocks with typed parameters and Mandatory where appropriate.
  • Validate inputs (Test-Path, if (-not $Name) { throw ... }).
  • Wrap wx.exe calls in try/catch — PowerShell sometimes mis-categorizes its stdout as RemoteException. That's noise, not a real failure. Check $LASTEXITCODE, not just $?.

Node scripts (tools/*.js)

  • Target Node 18+.
  • Use plain CommonJS (require) — no build step, no TypeScript, no bundler. These are throwaway utility scripts.
  • Resolve dependencies from the global npm root -g (so users don't need a local node_modules/).
  • Read args from process.argv. No fancy CLI framework.
  • Print to stdout for piping. Errors to stderr with a clear prefix.

Markdown

  • Headings in title case for English, no extra formatting for Chinese.
  • Use fenced code blocks with language tags.
  • Keep line length flexible — these are read by humans and LLMs, not diffed by code review tools.

How to add a new tool

  1. Decide PowerShell or Node based on:
    • PowerShell: orchestrating wx-cli calls, file system operations, Windows-first workflows
    • Node: text/PDF/JSON parsing, anything needing npm packages
  2. Add the script to tools/.
  3. Document it in README.md under "Commands".
  4. Update CLAUDE.md if the new tool changes the analysis workflow.
  5. Test it locally on dummy data. Never use real user data in tests.

How to add a new template

people/_template/profile.md and projects/_template/notes.md are the only templates today. When adding:

  1. Use placeholder names (张三, Acme Project).
  2. Mark fillable slots with <...> or TODO: comments.
  3. Include a last-updated: field so staleness is visible.
  4. Use YAML frontmatter with this minimum fixed schema (read by tools/status.ps1):
    ---
    last-updated: 2026-01-01
    ball-in-court: Alice
    next-action: <one concrete next step>
    tags: [tag-1, tag-2]
    ---
  5. Templates MAY extend the frontmatter with type-specific fields. Current extensions:
    • people/_template/profile.md adds mbti, trip-wires, comms. Methodology is documented in docs/mbti-analysis.md. Any new field must be additive — never break the minimum schema above, or status.ps1 parsing fails.

PR review checklist (for agents reviewing each other's work)

  • No real names, emails, phone numbers, WeChat IDs, or chat excerpts anywhere
  • No files added under people/*/, projects/*/, topics/*/ outside _template/
  • Scripts have UTF-8 setup at top
  • Scripts validate inputs and handle missing wx.exe
  • Docs updated if user-visible behavior changed
  • .gitignore still blocks the file types it should
  • gitleaks-action passes (custom rules in .gitleaks.toml)

Out of scope (don't do these)

  • Don't reimplement wx-cli features (decryption, querying, daemon). Defer to it.
  • Don't add a build system, bundler, or framework. Keep it scripts-only.
  • Don't add telemetry, analytics, or any network calls beyond what wx-cli already does.
  • Don't add a web UI. HTML files generated for personal use (like task-plan.html) are static and gitignored.
  • Don't add cloud sync, backup, or "share" features. Local-only is the point.

When you're unsure

Open an issue describing the proposed change before writing code. Reference this file. Tag the maintainer.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.