Skip to content

Back to the catalog

gioblu/NPC-Forge
github.comrepo

gioblu/NPC-Forge

NPC-Forge is a framework for building deterministic, non-ML conversational NPCs/agents with multi-turn context, sentiment analysis, and tool-call support, designed to run on CPU even on embedded or obsolete hardware. It ships with an OpenAI-compatible API server so its deterministic agents can be plugged into LLM harnesses like Open WebUI or GitHub Copilot, and includes TERMy, a bundled NPC that transpiles natural-language prompts or scripts into shell commands without using any model. Agents are defined and updated via a dataset format (NDF) rather than trained, with a CLI (npc-forge list/serve/install/reboot) for managing and running them; currently an experimental Linux/WSL-only release under AGPL-3.0.

TL;DR A deterministic, no-LLM agent framework (with an OpenAI-compatible API and a natural-language-to-shell NPC called TERMy) for building CPU-only conversational NPCs.
Open original ↗
Document

What it claims

NPC-Forge builds conversational agents (personality, multi-turn context, sentiment analysis, tool calls) without any ML model or LLM. Agents run on the CPU, either in a web browser or on the OS, and the page says they respond in milliseconds. The case for it is determinism: an agent cannot hallucinate, and the page adds that it has no safety alignment filters. The page says it tolerates typos, expletives, interjections and word inversions "much better than NLP.js", but gives no benchmark, number or test setting for that comparison.

How it works

Behaviour lives in datasets written in NDF 0.0 (NPC-Forge Dataset Format). Changing an agent means editing the dataset and running npc-forge reboot; there is no training step. The page does not describe the matching or parsing mechanism. An OpenAI-compatible API server exposes the agents to harnesses such as Open WebUI or Copilot, including their tool calls.

How to use it

Install (Linux or WSL only):

git clone https://github.com/gioblu/NPC-Forge.git
cd NPC-Forge && chmod +x setup.sh && ./setup.sh
npc-forge install npcs/termy
termy how are you

The CLI has more commands than the summary lists:

npc-forge list           # Lists the installed NPCs
npc-forge test           # Run NPC-Forge test suite
npc-forge serve          # Starts OpenAi/Copilot compatible API server
npc-forge stop           # Stops server
npc-forge reboot         # Reboots server
npc-forge watch          # Starts server and watch logs in real-time
npc-forge create         # Creates new NPC using the example profile
npc-forge install <path> # Installs a new NPC

To build your own NPC, start with npc-forge create, which scaffolds a new NPC from an example profile.

TERMy takes a one-off prompt (termy <prompt>) or a plain-English script file. For example, a file test.termy containing:

search on wiki the programma 101
append it to p101.txt
open it in the browser

is transpiled to a shell script and executed with:

termy -y < test.termy

The -y flag appears to skip confirmation; the page does not say so explicitly. To extend TERMy, edit its files in the repo's dataset directory.

Limits

  • This is the first experimental release, distributed "AS IS" with no warranty, and it runs only on Linux and WSL. The browser runtime is mentioned but not documented on this page.
  • TERMy executes generated shell commands. With -y and no alignment filtering, a script runs whatever the transpiler produces, so review the output before running it unattended.
  • Capability is limited to what the curated dataset covers. The page gives no coverage or accuracy figures.
  • The licence is AGPL-3.0. Commercial licensing is available by contacting the author, which matters if you plan to embed it behind a network service.

Technologies named here

Techniques named here

  • Deterministic agent design

Related in agents