Quickstart

Run it (no install needed)

TypeGlish is an npm package; npx typeglish … cold-starts it in seconds. Needs Node 20.19+; the Z3 proof tier comes with it. Two commands teach the whole language:

$ npx typeglish --help
$ npx typeglish reference        # the full language, one command: read its "Start here" first

reference is long (the whole language); its first section, Start here, is a copyable skeleton plus what counts as a rule — the part that covers the first hour. In a project, pin a version with npm i -D typeglish; every command below works the same way through npx.

Write your first prompt

Near-plain English. A prose # Role says who the agent is; the rules lead with a modal (MUST / NEVER / SHOULD) or a verb. Save as hello.tg:

# Role
You are a support agent for Acme, a SaaS analytics company.

# Constraints
- MUST keep every reply to at most 3 sentences.
- ALWAYS escalate a refund request to a human.

Review it — one run says what the checker read, what it proved, and what would raise the grade:

$ npx typeglish review hello.tg
hello.tg — B (87/100) → A (99) projected if every fix below lands  check: 0 error, 0 warning, 0 info  tiers: base+z3

  FIXES  ranked by projected gain
  +12  put a "@@ why" note above L2 L5 L6 — annotation 0 → 100

  RULES  2 of 2 rule-shaped lines read

  TESTS  no $TEST cases — add one beside a rule; `test --dry` validates it offline

Both rules were read as rules (the RULES line), nothing needs proving yet, and the one edit that would move the grade is named with its lines. check, score, and test --dry are the same three views, one per command.

Break it, on purpose

Add a rule that argues with one you already have, then compile again:

$ echo "- NEVER escalate a refund request to a human." >> hello.tg
$ npx typeglish check hello.tg
hello.tg:6:1  error  logic/contradiction  Conflicts with line 7. Logical conflict —
  "escalate a refund request to a human." is both required and forbidden.
  Keep one, or scope the two rules so they cannot both apply (IF <condition> THEN ...).
                 ↳ line 7: - NEVER escalate a refund request to a human.
hello.tg:7:1  error  logic/contradiction  Conflicts with line 6. …
                 ↳ line 6: - ALWAYS escalate a refund request to a human.

✗ 1 file — 2 error, 0 warning, 0 info

That refusal is the product: the contradiction is proven at compile time (by Z3), not left for the model to resolve differently every conversation. Each end of the pair cites the other and quotes it. npx typeglish --explain logic/contradiction hello.tg spells out any code and, with the file, shows every place it fires.

Fix it, annotate it, pin it, ship it

Delete the conflicting line (or scope one with IF / UNLESS). Take the review's fix — a @@ why note above each rule: stripped before the model reads it, worth 12 points of the grade. Then pin the behavior with a $TEST so the agent can't drift:

# Role
You are a support agent for Acme, a SaaS analytics company.

# Constraints
@@ brevity: three sentences keeps support replies scannable
- MUST keep every reply to at most 3 sentences.
@@ escalation: a refund is a human decision, not a chatbot one
- ALWAYS escalate a refund request to a human.

$TEST escalation
  - input:: I want a refund - can I talk to someone?
  - expect::
    - offers to escalate the request to a human

$ npx typeglish test hello.tg --dry
✓ hello.tg  coverage: 1/2 rules exercised
  uncovered (no case shares the rule's wording):
    L6  keep every reply to at most 3 sentences.
  · escalation — "I want a refund - can I talk to someone?" (not run)
      · rubric — 1 prose expectation, judged on a live run (needs ANTHROPIC_API_KEY)
✓ 1 prompt — 0 failed
$ npx typeglish score hello.tg
hello.tg — A (96/100)  proven errors: none  tiers: base+z3
  planes  runtime 100 (what the model reads) · hygiene 84 (source only)
  facets  …
  lever   annotation 67/100 (up to +4 overall) — 1 statement without a @@ note (L2) — put a "@@ why" line directly above each
  rules   2 of 2 rule-shaped lines read · 1/2 covered by $TEST
$ npx typeglish build hello.tg
✓ built .typeglish/dist/hello.txt ← hello.tg (42ac8712ae03, full)

--dry validates the suite offline and names the rule no case exercises yet; a live run sends each case to a model (ANTHROPIC_API_KEY). The remaining four points are the role line's missing @@ note (the lever row). build writes the deployable prompt plus .typeglish/build-manifest.json (source and artifact hashes, the check that passed) — the artifact is the role and the two rules, with the @@ notes and the $TEST stripped. Deploy that file, never the .tg.