Skip to content

Commit 157455f

Browse files
SimonSchubertSimonSchubert
committed
Add commands
1 parent 4914f4f commit 157455f

3 files changed

Lines changed: 219 additions & 0 deletions

File tree

‎assets/commands/index.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5129,6 +5129,7 @@ notox.md
51295129
nova.md
51305130
now.md
51315131
nox.md
5132+
npc-forge.md
51325133
nping.md
51335134
npm-access.md
51345135
npm-adduser.md
@@ -7834,6 +7835,7 @@ termscp.md
78347835
termshark.md
78357836
termtosvg.md
78367837
termusic.md
7838+
termy.md
78377839
terraform-apply.md
78387840
terraform-console.md
78397841
terraform-destroy.md

‎assets/commands/npc-forge.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# TAGLINE
2+
3+
CLI for deterministic NPC agents that run without an LLM
4+
5+
# TLDR
6+
7+
Install the framework from a **git clone** (user-space, not root)
8+
9+
```git clone [https://github.com/gioblu/NPC-Forge.git] && cd NPC-Forge && chmod +x setup.sh && ./setup.sh```
10+
11+
Install the bundled **TERMy** assistant
12+
13+
```npc-forge install [npcs/termy]```
14+
15+
Install an NPC in **editable** developer mode
16+
17+
```npc-forge install [./npcs/termy] --dev```
18+
19+
**List** installed NPCs
20+
21+
```npc-forge list```
22+
23+
**Start**, **stop**, or **restart** the user systemd service
24+
25+
```npc-forge start```
26+
27+
```npc-forge stop```
28+
29+
```npc-forge restart```
30+
31+
Follow the **service log**
32+
33+
```npc-forge logs```
34+
35+
Run the **test suite**
36+
37+
```npc-forge test```
38+
39+
# SYNOPSIS
40+
41+
**npc-forge** _command_ [_options_]
42+
43+
# PARAMETERS
44+
45+
**-h**, **--help**
46+
> Print the command list and exit. Also shown when **npc-forge** is invoked with no arguments (that path exits 1).
47+
48+
**--dev**
49+
> With **install** only. Passes **--dev** to the NPC's **setup.sh** hook (symlinks / editable install). Ignored on other commands.
50+
51+
# COMMANDS
52+
53+
**serve**, **start**
54+
> **systemctl --user start npc-forge.service**. The unit runs **server.py** from **~/.local/share/npc-forge** (Flask on **127.0.0.1:5000**).
55+
56+
**stop**
57+
> **systemctl --user stop npc-forge.service**.
58+
59+
**restart**, **reboot**
60+
> **systemctl --user restart npc-forge.service**. Use this after editing an NPC dataset so the gateway reloads intents.
61+
62+
**logs**, **watch**
63+
> If the unit is inactive, start it, then **tail -n 20 -f** **~/.local/share/npc-forge/npc_forge.log**. Ctrl+C leaves the service running.
64+
65+
**list**
66+
> Print each directory under **~/.local/share/npc-forge/npcs/** with creator, intent count, vocabulary size, dataset size, and whether any intent declares tools.
67+
68+
**install** _path_ [**--dev**]
69+
> Copy _path_ into **~/.local/share/npc-forge/npcs/**_name_ (_name_ is the directory basename, lowercased) and run **setup.sh** in the source tree if present. If the source already resolves to the target (dev symlink), the copy is skipped.
70+
71+
**test**, **tests**
72+
> Run **tests/run_tests.py** with the framework venv Python, or **unittest discover** if that runner is missing.
73+
74+
# DESCRIPTION
75+
76+
**npc-forge** administers **NPC-Forge**, a Python framework for CPU-only conversational agents (NPCs) that do not use embeddings, machine learning, or LLMs. Intents live in JSON datasets (NDF 0.0). FlintParser matches prompts with exact, template, and probabilistic steps; FlintNPC then returns a message and optional tool calls. The same engine is exposed over HTTP so editors and LLM harnesses can treat an NPC as an OpenAI-compatible model.
77+
78+
The **npc-forge** wrapper on **PATH** is a short script written by **./setup.sh** into **~/.local/bin/npc-forge**. It runs **cli.main** inside **~/.local/share/npc-forge/venv**. The installer also copies or symlinks the Python sources, creates that virtualenv (**pip install** the **pyproject.toml** package, Python **3.8+**), and, when **systemctl** exists, installs a user unit **npc-forge.service**. **./setup.sh --dev** symlinks sources for live editing. **./setup.sh --uninstall** stops the unit and deletes the wrapper and data directory. Do not run the installer as root.
79+
80+
The gateway listens on **http://127.0.0.1:5000**. Native routes include **POST /api/chat/**_npc_ and **GET /**_npc_**/chat/** (compiled HTML). OpenAI-shaped routes include **GET /api/v1/models** and **POST /api/v1/chat/completions**, which is how TERMy is wired into Copilot-style clients. **termy** is a separate binary installed with **npc-forge install npcs/termy**.
81+
82+
The README currently limits this experimental release to **Linux** and **WSL**.
83+
84+
# CONFIGURATION
85+
86+
**~/.local/share/npc-forge/**
87+
> Framework prefix: Python modules, **venv/**, **npcs/**, **tests/**, and **npc_forge.log**.
88+
89+
**~/.local/share/npc-forge/npcs/**
90+
> One subdirectory per installed NPC. **list** and the HTTP registry read this tree.
91+
92+
**~/.local/bin/npc-forge**
93+
> User-space launcher. **setup.sh** appends **~/.local/bin** to **PATH** in **~/.bashrc** or **~/.zshrc** when it is missing.
94+
95+
**~/.config/systemd/user/npc-forge.service**
96+
> User unit. **WorkingDirectory** is the framework prefix; **ExecStart** is the venv Python running **server.py**; stdout/stderr append to **npc_forge.log**; **Restart=always**.
97+
98+
# CAVEATS
99+
100+
Experimental **1.0.0** release, licensed **AGPL-3.0**, distributed **AS IS**. There is no **npc-forge uninstall**; use **./setup.sh --uninstall** from a checkout.
101+
102+
**serve** / **start** / **stop** / **restart** / **logs** all call **systemctl --user**. They fail if systemd is unavailable (including typical macOS). The Flask app is the development server bound to localhost; the API docs recommend gunicorn for anything public.
103+
104+
**install** needs a real directory path. The CLI has no package registry or download step. **--dev** is only meaningful with **install**.
105+
106+
Requires **python3**, the **venv** module, and write access to **~/.local**. **~/.local/bin** must be on **PATH** after install.
107+
108+
# HISTORY
109+
110+
**NPC-Forge** is written by **Giovanni Blu Mitolo** (known for the **PJON** protocol). The public repository was created on **18 July 2026**. The first Python package version is **1.0.0**. The **npc-forge** CLI, systemd user service, OpenAI-compatible gateway, and bundled **termy** NPC were the experimental Linux/WSL surface shown on Hacker News in **September 2026**. License: **GNU Affero GPL v3**.
111+
112+
# SEE ALSO
113+
114+
[termy](/man/termy)(1), [systemctl](/man/systemctl)(1), [python3](/man/python3)(1), [flask](/man/flask)(1), [aichat](/man/aichat)(1), [copilot](/man/copilot)(1)
115+
116+
# RESOURCES
117+
118+
```[Source code](https://github.com/gioblu/NPC-Forge)```
119+
120+
```[Documentation](https://github.com/gioblu/NPC-Forge/blob/main/docs/NPC-Forge-cli.md)```
121+
122+
<!-- verified: 2026-09-04 -->

‎assets/commands/termy.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# TAGLINE
2+
3+
Deterministic natural-language terminal assistant (no LLM)
4+
5+
# TLDR
6+
7+
Translate a request into a **shell command** (asks before running)
8+
9+
```termy [list files in this directory]```
10+
11+
Skip the **confirmation** prompt
12+
13+
```termy -y [create a file notes.txt]```
14+
15+
Look up **related intents** for a keyword
16+
17+
```termy files```
18+
19+
Pipe a prompt on **stdin**
20+
21+
```echo "[print json file data.json]" | termy```
22+
23+
Talk to a **different installed NPC**
24+
25+
```termy --npc [name] [status]```
26+
27+
# SYNOPSIS
28+
29+
**termy** [**-y**] [**--npc** _name_] [_query_ ...]
30+
31+
# PARAMETERS
32+
33+
_query_
34+
> Natural-language prompt. Remaining arguments are joined with spaces. Required unless the prompt is piped on stdin.
35+
36+
**-y**, **--yes**
37+
> Skip the interactive Yes/No prompt and run matched commands. Also sets **TERMY_YES=1** for child processes.
38+
39+
**--npc** _name_
40+
> NPC profile to query (default **termy**). The profile must already be installed under the NPC-Forge registry.
41+
42+
# DESCRIPTION
43+
44+
**termy** is the bundled Linux terminal assistant of **NPC-Forge**. It maps a natural-language prompt to a canned intent from a JSON dataset and, when the intent includes a tool call, proposes a shell command. Matching is deterministic: there are no embeddings, no trained classifier, and no LLM. The parser (FlintParser / FlintNPC) strips interjections, scores sentiment, then tries an exact match, a template match, and a slower probabilistic match that uses inverse document frequency, bag-of-words, and IDF-weighted Levenshtein for typos.
45+
46+
On each run **termy** first POSTs the prompt to the local NPC-Forge gateway at **http://127.0.0.1:5000/api/chat/**_npc_ (1 second timeout). If the server is down it loads the NPC engine in-process from **~/.local/share/npc-forge**. A match prints a status line (name, match status, confidence), optional thinking text, the command, and a short response. Intents tagged **permission: yolo** run immediately through **bash**. Intents tagged **ask** wait for an interactive Yes/No choice unless **-y** was given. Before execution, every **.sh** file in the NPC's **scripts/** directory is sourced in the same bash command.
47+
48+
If confidence is too low the request is **rejected** and **termy** lists related intents (deduplicated by category, capped by the NPC **suggestions** setting). Typing a listed number re-runs **termy** with that intent's sample phrase.
49+
50+
Install **termy** only after the framework: clone **NPC-Forge**, run **./setup.sh**, then **npc-forge install npcs/termy**. The NPC installer writes a wrapper to **~/.local/bin/termy** that uses the framework virtualenv. The project currently documents Linux and WSL only.
51+
52+
# CONFIGURATION
53+
54+
**~/.local/share/npc-forge/npcs/termy/**
55+
> Installed NPC profile: **config.json**, **dataset/**, **scripts/**, and the Python client. **npc-forge install** copies this tree from the source checkout (or leaves a symlink in **--dev** mode).
56+
57+
**~/.local/share/npc-forge/npcs/termy/config.json**
58+
> NPC profile. Keys include **npc_name**, **tts** (speech synthesizer binary, default **espeak-ng**), **creator**, **sentence_threshold**, **word_threshold**, and **suggestions** (how many related intents to list).
59+
60+
**~/.local/share/npc-forge/npcs/termy/dataset/**
61+
> Intent files (**dataset_*.json**, **templates_*.json**) plus vocabulary. Format is NDF 0.0 (NPC-Forge Dataset Format). After editing, run **npc-forge reboot** so the gateway reloads the dataset.
62+
63+
**~/.local/share/termy/config.json**
64+
> Per-user file created on first install. The client reads this path for optional spoken replies (it speaks the response when the **tts** key is **on**, using the synthesizer named in the NPC profile).
65+
66+
**TERMY_YES**
67+
> Environment flag. **1** has the same effect as **-y**.
68+
69+
# CAVEATS
70+
71+
This is an **experimental** first release. The author ships it **AS IS** with no warranty and warns that matched intents can emit long command chains. Review every proposed command; **yolo** intents and **-y** skip that review.
72+
73+
A prompt is mandatory (arguments or a non-empty stdin). There is no interactive REPL: **termy** with no input prints usage and exits.
74+
75+
Matched commands run with **shell=True** and **executable=/bin/bash** as the installing user. Destructive intents are supposed to use **permission: ask**, but a dataset or parser bug can still run the wrong command.
76+
77+
The HTTP path assumes the NPC-Forge Flask service on **127.0.0.1:5000**. **serve** / **start** / **stop** / **logs** go through a **systemd --user** unit (**npc-forge.service**). Without systemd, start **server.py** yourself or rely on the in-process fallback.
78+
79+
**~/.local/bin** must be on **PATH**. Do not run the installer as root. Optional spoken output wants **espeak-ng** on **PATH** (the NPC **setup.sh** tries to install it).
80+
81+
# HISTORY
82+
83+
**termy** is the first NPC shipped with **NPC-Forge**, written in Python by **Giovanni Blu Mitolo** (author of PJON) under the **GNU Affero GPL v3**. The GitHub repository was created on **18 July 2026** after about two months of work that started from a local LLM harness and then dropped machine learning entirely. Version **1.0.0** in **pyproject.toml** is the experimental public CLI; **Show HN** followed in **September 2026**.
84+
85+
# SEE ALSO
86+
87+
[npc-forge](/man/npc-forge)(1), [aichat](/man/aichat)(1), [sgpt](/man/sgpt)(1), [navi](/man/navi)(1), [fuck](/man/fuck)(1), [espeak-ng](/man/espeak-ng)(1), [bash](/man/bash)(1)
88+
89+
# RESOURCES
90+
91+
```[Source code](https://github.com/gioblu/NPC-Forge)```
92+
93+
```[Documentation](https://github.com/gioblu/NPC-Forge/blob/main/npcs/termy/README.md)```
94+
95+
<!-- verified: 2026-09-04 -->

0 commit comments

Comments
 (0)