Hacky

Hacky v0.1 is a small, portable file for a finite AI-chat experience. An app maps one character, animal, NPC, role, voice, or other target into a canonical file; the receiving AI can apply the included effect for a bounded number of replies.

The format is deliberately temporary and transparent. It does not grant permissions, call external services, execute code, change permanent settings, or create long-term memory. The receiving host's rules and later explicit user instructions always take priority.

Canonical files

Hacky v0.1 defines exactly two public forms:

• .hacky.json — compact canonical UTF-8 JSON for programs and direct sharing.
• .hacky.pdf — a one-page 1800 × 1800 point dot carrier containing only the same JSON as invisible text.

Every JSON object has exactly these four keys, in this order:

Key	Type	Constraint
hacky	string	exactly "0.1"
name	string	NFC, trimmed, 1–80 characters, no controls
turns	integer	1–99
instructions	string	NFC, trimmed, 1–8192 characters, fixed activation plus one effect

The canonical bytes are UTF-8 without a BOM, use compact JSON and standard JSON escaping, keep the four-key order above, and end with exactly one LF. Duplicate keys, unknown keys, non-canonical whitespace, invalid Unicode, and oversized input are rejected.

Use from GitHub

git clone https://github.com/openhacky/hacky.git
npm --prefix hacky/packages/js ci
npm --prefix hacky/packages/js run build
npm install ./hacky/packages/js
python3 -m pip install ./hacky/packages/python

The JavaScript package name is @openhacky/core. The Python distribution is hackyformat, its module is hacky, and both packages expose the hacky command-line executable. Registry publication is not part of the v0.1 GitHub release; the commands above install the reviewed source tree directly.

JavaScript

import { compileInstructions, stringify, loadPdf } from "@openhacky/core"
import { readFileSync } from "node:fs"

const pack = {
  hacky: "0.1",
  name: "Kuma",
  turns: 4,
  instructions: compileInstructions(
    "Kuma",
    4,
    "Write a concise, natural reply."
  )
}
const canonical = stringify(pack)
const fromPdf = loadPdf(readFileSync("kuma.hacky.pdf"))

Python

import hacky

pack = hacky.HackyPack(
    "0.1", "Kuma", 4,
    hacky.compile_instructions("Kuma", 4, "Write a concise, natural reply.")
)
canonical = hacky.dumps(pack)
from_pdf = hacky.load("kuma.hacky.pdf")

CLI

hacky validate kuma.hacky.json
hacky extract kuma.hacky.pdf
hacky render kuma.hacky.json
hacky pdf kuma.hacky.json kuma.hacky.pdf

validate accepts either canonical form. extract returns canonical JSON from the PDF carrier. render prints the compiled activation and effect. pdf creates the safe one-page carrier.

Activation

compileInstructions supplies the fixed [HACKY ACTIVATION v0.1] prelude and the [HACKY EFFECT] boundary. English is the normative activation language. The SDK also provides a fixed meaning-equivalent Japanese activation with language: "ja". The first reply after attachment counts as reply 1; the effect ends at the configured finite count, on an explicit stop request, or when a replacement file is selected.

The fixed ending lines are Hacky effect ended. in English and Hackyの効果が切れました。 in Japanese.

The activation asks the host to apply the effect rather than merely summarize the file, handle a same-message request after applying it, and give a brief effect-fitting start when no request is present. It includes a remaining-turn counter before the final reply and a single final ending line. Host policy and later user instructions remain authoritative.

PDF safety

The PDF carrier is one page at 1800 × 1800 points with a 16 × 16 grid of filled dots on a #F2F2F2 background. The canonical JSON is the only payload, encoded as invisible UTF-16BE text. Conforming files have no visible text, images, forms, actions, scripts, attachments, encryption, or trailing bytes after %%EOF. Extraction must reproduce the same canonical Unicode JSON text; re-encoding that text as UTF-8 must reproduce the standalone .hacky.json bytes.

Conformance

The normative specification is spec/v0.1.md. The schema, four canonical fixtures, and contract verifier are the source of machine-checkable conformance.

python3 scripts/check_repository.py
python3 scripts/verify_contract.py
npm --prefix packages/js test
npm --prefix packages/js run typecheck
python3 -m unittest discover packages/python -v
git diff --check

Repository

The public repository is openhacky/hacky. The JavaScript package is @openhacky/core; the Python distribution is hackyformat.

Code is licensed under Apache-2.0. The specification and documentation are licensed under CC BY 4.0. The Hacky name and marks are managed separately; see TRADEMARKS.md.