humanish

humanish

Open-source-safe persona simulation for apps, CLIs, and agent-facing product flows.

Humanish gives a project a repeatable way to ask: what happens when realistic synthetic users, with different goals and tolerances, try to use this thing? It creates committed simulation source under humanish/, ignored run evidence under .humanish/, a watchable Observer UI, verification gates, and public-safe feedback drafts.

This synthetic technical sample demonstrates the Observer's four-lane layout; it is not a completed real-application study.

Install

npm i -D humanish
npx humanish init --yes
npx humanish watch

The package is humanish; the installed binary is humanish. For a one-shot command before installation, use npx --package humanish humanish ... to guarantee the binary comes from the humanish registry package rather than a same-named command already on your PATH.

For coding agents, install the repo skill first:

npx skills add danielgwilson/humanish --skill humanish

The skill lives at skills/humanish/SKILL.md for skills.sh discovery.

Public-Safety Boundary

Humanish is designed for public repositories and public issue queues. The boundary is three planks, each enforced where it actually holds:

1. This repo and the published package are kept public-safe by CI. Every push runs a public-surface scan (secret/key/path shapes, a sha256 binary-asset allowlist, over both tracked files and the packed npm payload) plus a full-history gitleaks scan. That protects what we ship — it does not scan your repo.

2. The harness never persists secret values into run artifacts. On every route, values it provisioned are scrubbed by literal match (they have no shape for patterns to catch) and secret-shaped content is pattern-redacted before any log tail, harness error, or model narration lands on disk. Env var names are evidence; values never are. Pixels are the exception: a raw screenshot shows whatever was on screen, which is why plank 3 exists.

3. Run bundles are local by default. Evidence lands under gitignored .humanish/, and no command publishes it for you. Sharing evidence — committing screenshots, pasting transcripts, attaching bundles to issues — is a deliberate act, and reviewing what you share is on you. Use synthetic personas and synthetic data so there is nothing sensitive to capture in the first place.

What the automated gate enforces. humanish verify scans public-bound artifacts and fails closed on secret, key, and token shapes and on known local path shapes. It does not yet detect free-form PII or PHI such as names, emails, phone numbers, dates of birth, or medical identifiers. Keeping those out depends on using synthetic data and on review, so redaction: passed means the automated secret and path scan found no matches, not that the artifact was certified free of PII or PHI. A first-class PII/PHI detector is on the roadmap (#108).

humanish verify --json also reports shareSafety.status:

• shareready: the verified bundle is eligible for public feedback drafts;
• localonly: the bundle is valid local evidence, but should not be shared as-is