agentleFS
christos-antonochristos-antono/NPCTalk/AGENTS.md

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…

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
  1. Very specific:

    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 …

    line 15
  2. Distinctive:

    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 …

    line 61
  3. Distinctive:

    Wording: keep skills and docs agent-neutral ("the agent"), except in sections about one specific agent.

    line 71

≈ “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.

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

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

  1. Read skills/make-npcs-talk/SKILL.md and 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.
  2. 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 tried, what was measured, what went wrong).
  3. Check knowledge/ for a field note on the game; write one at the end (knowledge/README.md).

Skills (skills/*/SKILL.md, Agent Skills format)

SkillUse it for
make-npcs-talkThe whole loop, the four hooks a game must provide, engine choices, latency, rules
fish-voice-serverHosting Fish Audio Drama 3 / S2 Pro on Modal (or fal): API, keep-warm, best-of, fine-tune, gotchas
voice-referencesReference clips from recordings the user has the rights to; npctalk voice make/upload
npc-dialoguePersonas, the prompt, scene facts, output cleaning, content rules, speed
npc-actionsWhat NPCs physically do, and following spoken orders (TypeSafe Jev)
voice-inputOpen mic, push-to-talk, speech-to-text, echo and noise
voice-likeness-evalMeasuring whether a voice change really helped
npc-showcase-clipsGameplay-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 with uv; bin\npctalk.cmd on Windows). Put bin on PATH, or uv 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 from NPCVOICE_URL, token from NPCVOICE_TOKEN)
    • voice make, voice upload: reference voices from a recording, into the server's volume (FAL_KEY for 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 the modal CLI.
  • fal MCP server (https://mcp.fal.ai/mcp, header Authorization: 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 /health needs no token and wakes the GPU); write your-workspace in 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.md in the working folder) that becomes your field note.

Working on the toolkit itself

  • Python: 3.10+, numpy only (uv handles it via bin/npctalk). One module per command group in npctalk/, each with register(sub) and a docstring that doubles as --help.
  • Tests: uv run --with pytest pytest -q tests. CI also runs every --help screen and npctalk check ..
  • C# example: dotnet build -c Release in examples/gta-v/mod and in examples/gta-v/tools/npcvoice-check.
  • Wording: keep skills and docs agent-neutral ("the agent"), except in sections about one specific agent.

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.