ascii-chat / web
AGENTS.md203 starsChanged 8 days agoMITView on GitHub
- www/ — ascii-chat.com: Project homepage with installation instructions, a live ASCII mirror demo, usage guides, and searchable CLI, configuration, and C API manual pages (/man1, /man5, /man3). - web/ — web.ascii-chat.com: Browser client using the C engine compiled to WebAssembly. /mirror renders webcam, file, or URL media locally; /client connects to servers over WebSocket; /discovery creates or joins named sessions through ACDS and WebRTC. - discovery/ — discovery.ascii-chat.com: Discovery-service information site with signaling/STUN/TURN status checks, SSH/GPG public keys and…
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 32,671 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 repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ascii-chat-c-developmentSkill
- ascii-chat-cli-releaseSkill
- ascii-chat-cross-platform-development-and-or-testingSkill
- ascii-chat-documentationSkill
- ascii-chat-mcp-devSkill
- ascii-chat-python-developmentSkill
- ascii-chat-testingSkill
- ascii-chat-wasm-developmentSkill
- ascii-chat-web-deploySkill
- sentry-commit-messagesSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
16 rules. About 2 are common, 5 are distinctive, and 9 are very specific to this project.
≈2
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 14
All three are React/TypeScript apps and share components and utilities through packages/shared/ (@ascii-chat/shared).
- Very specific: line 25
Keep generators, guide definitions, dependency manifests/lockfiles, authored dist/index.html, dist/app.js, dist/guides.js, dist/style.css, …
- Very specific: line 29
Do not ignore the entire dist/ directory: it contains authored frontend code.
- Common: line 41
Use the Sites skill to publish the compressed output through its isolated checkout.
- Common: line 43
Do not publish this Site through a Vercel release branch or commit credentials.
- Very specific: line 49
After packaging, serve cloudflare-dist/ locally and run vp exec node test-browser-state.mjs http://127.0.0.1:4189 from the atlas directory.
- Distinctive: line 66
create - Create a new project from a template
- Distinctive: line 76
check - Run format, lint, and TypeScript type checks
- Distinctive: line 83
run - Run monorepo tasks
- Distinctive: line 98
add - Add packages to dependencies
- Very specific: line 99
remove (rm, un, uninstall) - Remove packages from dependencies
- Very specific: line 100
update (up) - Update packages to latest versions
- Distinctive: line 117
Using the package manager directly: Do not use pnpm, npm, or Yarn directly.
- Very specific: line 118
Always use Vite commands to run tools: Don't attempt to run vp vitest or vp oxlint.
- Very specific: line 121
Use Vite+ wrappers for one-off binaries: Use vp dlx instead of package-manager-specific dlx/npx commands.
- Very specific: line 122
Import JavaScript modules from
vite-plus: Instead of importing from vite or vitest, all modules should be imported from the project's …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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.
Files
Websites
www/— ascii-chat.com: Project homepage with installation instructions, a live ASCII mirror demo, usage guides, and searchable CLI, configuration, and C API manual pages (/man1,/man5,/man3).web/— web.ascii-chat.com: Browser client using the C engine compiled to WebAssembly./mirrorrenders webcam, file, or URL media locally;/clientconnects to servers over WebSocket;/discoverycreates or joins named sessions through ACDS and WebRTC.discovery/— discovery.ascii-chat.com: Discovery-service information site with signaling/STUN/TURN status checks, SSH/GPG public keys and fingerprints, connection examples, security guidance, and self-hosting instructions.
All three are React/TypeScript apps and share components and utilities through
packages/shared/ (@ascii-chat/shared).
ChatGPT Sites
chatgpt-sites/ascii-chat-code-atlas/— code-guide.ascii-chat.com: Interactive source map and guided walkthroughs of native C, TypeScript, and shared C/WASM implementations. This static Python/JavaScript project is hosted with the Sites plugin, separately from the three Vercel apps. Its dependencies use the shared pnpm workspace. Keep future ChatGPT Sites projects underchatgpt-sites/.- Keep generators, guide definitions, dependency manifests/lockfiles, authored
dist/index.html,dist/app.js,dist/guides.js,dist/style.css, and.openai/hosting.jsonin Git. Ignore generated source data, standalone HTML, QA screenshots, dependency caches,cloudflare-dist/, and.sites-checkout/. Do not ignore the entiredist/directory: it contains authored frontend code. - From the atlas directory run
vp install --ignore-scripts,uv run --project tests/ascii_chat_tests --frozen python generate.py,uv run --project tests/ascii_chat_tests --frozen python package.py, anduv run --project tests/ascii_chat_tests --frozen python prepare_cloudflare.py. Packaging parses complete references, validates every guide checkpoint against current source, highlights code, and creates the standalone bundle. Compression verifies a lossless round trip for the hosting payload. These are the atlas's build/check commands; the Reactvp check/vp testworkflow below applies to the three React apps. - Python and JavaScript source scanners resolve the repository root three levels above the atlas directory. Update both when relocating a Site.
- Use the Sites skill to publish the compressed output through its isolated checkout. Preserve the recorded project ID, public access, and custom domain. Do not publish this Site through a Vercel release branch or commit credentials.
- Atlas view state uses scalar URL query parameters:
inspector=closed,expanded=true,node,edgeSource/edgeTarget/edgeKind,file/trace,detailFile/symbol,zoom/x/y, and inspectorscroll. The hash retains the guide/chapter. Omit default values, preserve unrelated query parameters, and restore after source data and the selected layout are ready. - After packaging, serve
cloudflare-dist/locally and runvp exec node test-browser-state.mjs http://127.0.0.1:4189from the atlas directory. This browser regression checks refresh and copied URLs across desktop/mobile sizes, including closed inspectors and selected connections.
<!--VITE PLUS START-->Using Vite+, the Unified Toolchain for the Web
This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called vp. Vite+ is distinct from Vite, but it invokes Vite through vp dev and vp build.
Vite+ Workflow
vp is a global binary that handles the full development lifecycle. Run vp help to print a list of commands and vp <command> --help for information about a specific command.
Start
- create - Create a new project from a template
- migrate - Migrate an existing project to Vite+
- config - Configure hooks and agent integration
- staged - Run linters on staged files
- install (
i) - Install dependencies - env - Manage Node.js versions
Develop
- dev - Run the development server
- check - Run format, lint, and TypeScript type checks
- lint - Lint code
- fmt - Format code
- test - Run tests
Execute
- run - Run monorepo tasks
- exec - Execute a command from local
node_modules/.bin - dlx - Execute a package binary without installing it as a dependency
- cache - Manage the task cache
Build
- build - Build for production
- pack - Build libraries
- preview - Preview production build
Manage Dependencies
Vite+ automatically detects and wraps the underlying package manager such as pnpm, npm, or Yarn through the packageManager field in package.json or package manager-specific lockfiles.
- add - Add packages to dependencies
- remove (
rm,un,uninstall) - Remove packages from dependencies - update (
up) - Update packages to latest versions - dedupe - Deduplicate dependencies
- outdated - Check for outdated packages
- list (
ls) - List installed packages - why (
explain) - Show why a package is installed - info (
view,show) - View package information from the registry - link (
ln) / unlink - Manage local package links - pm - Forward a command to the package manager
Maintain
- upgrade - Update
vpitself to the latest version
These commands map to their corresponding tools. For example, vp dev --port 3000 runs Vite's dev server and works the same as Vite. vp test runs JavaScript tests through the bundled Vitest. The version of all tools can be checked using vp --version. This is useful when researching documentation, features, and bugs.
Common Pitfalls
- Using the package manager directly: Do not use pnpm, npm, or Yarn directly. Vite+ can handle all package manager operations.
- Always use Vite commands to run tools: Don't attempt to run
vp vitestorvp oxlint. They do not exist. Usevp testandvp lintinstead. - Running scripts: Vite+ commands take precedence over
package.jsonscripts. If there is atestscript defined inscriptsthat conflicts with the built-invp testcommand, run it usingvp run test. - Do not install Vitest, Oxlint, Oxfmt, or tsdown directly: Vite+ wraps these tools. They must not be installed directly. You cannot upgrade these tools by installing their latest versions. Always use Vite+ commands.
- Use Vite+ wrappers for one-off binaries: Use
vp dlxinstead of package-manager-specificdlx/npxcommands. - Import JavaScript modules from
vite-plus: Instead of importing fromviteorvitest, all modules should be imported from the project'svite-plusdependency. For example,import { defineConfig } from 'vite-plus';orimport { expect, test, vi } from 'vite-plus/test';. You must not installvitestto import test utilities. - Type-Aware Linting: There is no need to install
oxlint-tsgolint,vp lint --type-awareworks out of the box.
Review Checklist for Agents
- Run
vp installafter pulling remote changes and before getting started. - Run
vp checkandvp testto validate changes.
<!--VITE PLUS END-->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
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.

