NPCTalk
AGENTS.md231 starsChanged 32 days agoMITView on GitHub
A Universal Modder project. Community: the Universal Modder Discord. Skills, a self-hosted Fish Audio voice server and tools for AI coding agents (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and anything else that reads AGENTS.md). When someone opens an agent in this repo, they almost always want to make the NPCs in a game talk: the player speaks, the NPC answers in character, in a cloned voice, about a second later, and acts on what was said. Or…
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 repository25 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- fish-voice-serverSkill
- make-npcs-talkSkill
- npc-actionsSkill
- npc-dialogueSkill
- npc-showcase-clipsSkill
- voice-inputSkill
- voice-likeness-evalSkill
- voice-referencesSkill
- fish-voice-serverSkill
- make-npcs-talkSkill
- npc-actionsSkill
- npc-dialogueSkill
- npc-showcase-clipsSkill
- voice-inputSkill
- voice-likeness-evalSkill
- voice-referencesSkill
- fish-voice-serverSkill
- make-npcs-talkSkill
- npc-actionsSkill
- npc-dialogueSkill
- npc-showcase-clipsSkill
- voice-inputSkill
- voice-likeness-evalSkill
- voice-referencesSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Read the worked example: before inventing anything: examples/gta-v/ (the mod, its tools and README) and docs/how-it-was-made.md (what was …
- Distinctive: line 61
Ask first: before driving the user's keyboard and mouse in a running game (never while they're typing), installing into a game folder, or …
- Distinctive: line 71
Wording: keep skills and docs agent-neutral ("the agent"), except in sections about one specific agent.
≈ “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
NPCTalk
A Universal Modder project. Community: the Universal Modder Discord.
Skills, a self-hosted Fish Audio voice server and tools for AI coding agents (Claude Code, Codex, Cursor, Gemini
CLI, GitHub Copilot, OpenCode and anything else that reads AGENTS.md). When someone opens an agent in this
repo, they almost always want to make the NPCs in a game talk: the player speaks, the NPC answers in
character, in a cloned voice, about a second later, and acts on what was said. Or they want to learn how the GTA
V example was made.
Start here
- Read
skills/make-npcs-talk/SKILL.mdand follow its loop: recon the game → pick engines → voice server first, outside the game → reference voices → one NPC answering typed text in the game → voice input → characters → actions → verify in the real game → show it → write a field note. - Read the worked example before inventing anything:
examples/gta-v/(the mod, its tools and README) anddocs/how-it-was-made.md(what was tried, what was measured, what went wrong). - Check
knowledge/for a field note on the game; write one at the end (knowledge/README.md).
Skills (skills/*/SKILL.md, Agent Skills format)
| Skill | Use it for |
make-npcs-talk | The whole loop, the four hooks a game must provide, engine choices, latency, rules |
fish-voice-server | Hosting Fish Audio Drama 3 / S2 Pro on Modal (or fal): API, keep-warm, best-of, fine-tune, gotchas |
voice-references | Reference clips from recordings the user has the rights to; npctalk voice make/upload |
npc-dialogue | Personas, the prompt, scene facts, output cleaning, content rules, speed |
npc-actions | What NPCs physically do, and following spoken orders (TypeSafe Jev) |
voice-input | Open mic, push-to-talk, speech-to-text, echo and noise |
voice-likeness-eval | Measuring whether a voice change really helped |
npc-showcase-clips | Gameplay-style clips of conversations |
Copies of skills/ sit where agents look for them in a clone: .agents/skills (Codex, Gemini CLI, Copilot,
Cursor, OpenCode) and .claude/skills (Claude Code). Edit skills/, then copy it over; a test fails while the
copies differ.
Tools
bin/npctalk(Python, sets itself up withuv;bin\npctalk.cmdon Windows). Putbinon PATH, oruv tool install git+https://github.com/christos-antono/NPCTalk. Every command has--help:health,say: talk to the voice server like a game does (URL fromNPCVOICE_URL, token fromNPCVOICE_TOKEN)voice make,voice upload: reference voices from a recording, into the server's volume (FAL_KEYfor transcription, ffmpeg on PATH)check: nothing that mustn't ship (audio, transcripts, keys, real server URLs)
server/: Modal apps.drama3.py(default voice server),s2pro.py,keepwarm.py,fal/(S2 Pro on fal),finetune/(dataset, LoRA, the scorer). Run them with themodalCLI.- fal MCP server (
https://mcp.fal.ai/mcp, headerAuthorization: Bearer $FAL_KEY), pre-configured per agent:.mcp.json,.codex/config.toml,.cursor/mcp.json,.vscode/mcp.json,gemini-extension.json,opencode.json. Useful for speech-to-text, MiniMax voices and anything else on fal. - The GTA V example's tools (
examples/gta-v/tools/):npcvoice-check(the mod's network half without the game),shoot.ps1+edit.ts(recording and cutting clips),reload-mod.ps1.
Rules (full reasoning in skills/make-npcs-talk/references/safety.md)
- Where: single-player games, or servers the user runs. Never inject into online games with anti-cheat (GTA V: never launch GTA Online with ScriptHookV installed). No anti-cheat, DRM or ownership bypasses.
- Voices: clone only voices the user has the rights to. Never commit or publish voice clips, cloned renders,
game audio or a game's dialogue. Run
npctalk check .before every commit you're asked to make. - Secrets: keys from environment variables only. A voice server URL is a secret too (its
/healthneeds no token and wakes the GPU); writeyour-workspacein examples. - Money: say what a GPU kept up will cost before keeping it up (an H100 is about $4/hour).
- Content: slurs off by default and opt-in per persona; no anti-gay slurs or racial insults from anyone; undressing stops at underwear.
- Ask first before driving the user's keyboard and mouse in a running game (never while they're typing), installing into a game folder, or publishing anything (repos, PRs, videos, posts).
- Measure voice changes before claiming them (skill
voice-likeness-eval), and keep a journal (NPCLOG.mdin the working folder) that becomes your field note.
Working on the toolkit itself
- Python: 3.10+, numpy only (
uvhandles it viabin/npctalk). One module per command group innpctalk/, each withregister(sub)and a docstring that doubles as--help. - Tests:
uv run --with pytest pytest -q tests. CI also runs every--helpscreen andnpctalk check .. - C# example:
dotnet build -c Releaseinexamples/gta-v/modand inexamples/gta-v/tools/npcvoice-check. - Wording: keep skills and docs agent-neutral ("the agent"), except in sections about one specific agent.
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.

