Cunning Claw

Y dyn hysbys — the knowing one.

A personal AI assistant that runs on your machine and actually operates it. Sees your screen. Runs your shell. Reads your inbox. Speaks back. And refuses when a web page tells it to do something you didn't ask for.

Built in Cardiff by Dragon Forge AI · Local-first when privacy matters · Human approval when consequences matter

One take, no cuts: asked for a website, it wrote one and put it on the glass. The full 42-second film →

---

The name

Cunning folk is an occupational term, not a flourish. In Wales they were the dynion hysbys — "the knowing ones", singular dyn hysbys, literally the knowing man. They worked in villages across Wales into the twentieth century.

They were tradespeople, not mystics. You did not visit a dyn hysbys for enlightenment; you brought him a job. Find who took the horse. Read the weather before the sailing. Treat the child. He worked, you paid.

That is the posture here. Not a companion, not a personality to be enjoyed for its own sake — a practitioner you bring a job to.

The best known were John Harries and his son Henry of Cwrt-y-Cadno, Carmarthenshire — ninety minutes from where this was built. Harries kept the major medical texts of his day beside Latin and Greek, and practised as physician and astrologer both. His working papers survive at the National Library of Wales: prescriptions, payment records, horoscopes worked up on request, correspondence, lecture notes.

A practitioner keeping a record of the work and the reasoning behind each judgement. That is a case file — and it is a closer description of this software's memory, journal and skills than the name it used to carry.

Cunning cuts both ways, too. A cunning man's trade included telling a client when they were being had. Which is exactly what this does when a web page tries to give it orders.

→ docs/NAME.md for the history and sources.

---

Install

One command from a clean clone:

git clone https://github.com/Dragon-Forge-master/cunning-claw.git
cd cunning-claw
./install.sh

That checks Node 22+, runs npm install, creates .env from the example, asks for an OpenRouter key, offers the offline voice, runs npm run doctor, and prints how to start.

Then npm run dev and open http://127.0.0.1:3900. It binds to loopback only — nothing is exposed to your network.

Windows (native)

Install Node 22+ and Git, then in PowerShell:

git clone https://github.com/Dragon-Forge-master/cunning-claw.git
cd cunning-claw
powershell -ExecutionPolicy Bypass -File .\install.ps1
npm run dev

install.ps1 mirrors install.sh: Node check, npm install, .env with a no-echo key prompt, workspace seeding, npm run doctor. No Piper voice on Windows yet — he types.

Windows is the youngest platform: coded and doctor-checked, but the least field-tested — that is why the badge says beta. If you want the full Linux experience on a Windows machine (voice included), install under WSL2 instead and follow the Linux steps.

Autostart (Linux)

CUNNING CLAW is meant to survive a closed terminal. install.sh can drop a systemd --user unit (not a system unit — it needs your session for X11, audio and Chrome):

systemctl --user enable --now cunningclaw
loginctl enable-linger $USER    # still running after logout

The template lives at packaging/cunningclaw.service. macOS: keep npm run dev in a Terminal at login, or a LaunchAgent if you add one later.

By hand

npm install
cp .env.example .env        # add your OPENROUTER_API_KEY
./setup-voice.sh            # neural voice, ~60MB, fully offline
npm run doctor
npm run dev

Updating

One command, same on every platform:

npm run update

That is git pull plus npm install, run by npm in its own shell — so it works identically in PowerShell, which does not accept && on older versions, and in bash, which does. Your .env, your data/ (memory, journal, history) and your workspace are untracked and survive every update untouched.

Then relight it: systemctl --user restart cunningclaw if you use the autostart unit, or Ctrl+C and npm run dev again in a plain terminal. The claw tells you its version in the boot banner, and npm run doctor after an update names anything new it wants.

If git pull refuses because you have edited tracked files, either keep your edits (git stash, update, git stash pop) or take the fresh-clone road: rename the old folder aside, clone anew, copy .env across from the old folder, and npm install. Nothing is lost — the old folder holds everything until you delete it yourself.

Name your claw

The software is Cunning Claw. Your claw answers to whatever you put in claw.config.json:

"persona": {
  "name": "Cunning Claw",
  "addressUserAs": "sir",
  "userName": "Owner"
}

name is what it calls itself — in its own head, and when it announces itself on Telegram or Discord. addressUserAs is what it calls you; userName is who it understands you to be. Edit them, then relight (restart, as in Updating) — config is read once at boot. The HUD wordmark, the boot banner and the repo stay Cunning Claw: that is the software's name, the way the tin keeps its label whatever you christen what's inside.

This is the beginning of the README. Read the rest at the original. Read the full README ↗