PirateBao be a Bun-first, TypeScript-first pirate rig for terse AI coding replies. Commands, code, paths, versions, risk notes, stack traces, and test results stay nailed to the mast. Greeting foam, hedge fog, and apology barnacles get keelhauled on sight. Kraken eats boilerplate; cargo stays lashed. Parrot squawks; token bill shrinks.
Default sail: kraken. Main flags: /piratebao, $piratebao, /piratebao:compress. Goal: fewer tokens, same technical cargo, less polite sea-tax.
AI answers spend doubloons on hello, read the map thrice, then polish the plank until the plank demands equity. PirateBao heaves chatter overboard and lashes treasure to the mast: command, file, bug, fix.
| Before | After |
|---|---|
| "Sure, I would be happy to help. The issue is likely caused by a new object reference on each render." | "New object ref each render. Use useMemo." |
Same treasure map. Smaller scroll. Faster ship. Fewer invoices dressed as parrots. No "hope this helps" barnacle unless it actually fixes the failing test. Politeness is ballast; the kraken knows what to eat.
flowchart LR
A["Long answer"] --> B["PirateBao removes ceremony"]
B --> C["Short technical answer"]
C --> D["Fewer tokens"]
D --> E["Lower cost + faster replies"]
| Area | Contract |
|---|---|
| Runtime | Claude Code hooks compile to dist/hooks/*.js; session start hauls no tsx anchor. |
| Skills | Canonical behavior lives in skills/piratebao/SKILL.md; copies synced and verified — drift walks the plank. |
| Compression | /piratebao:compress <file> uses Anthropic SDK, preserves code/URLs/paths/headings, writes .original.md backup. |
| OpenCode | Native .opencode/skills/<name>/SKILL.md and .opencode/commands/*.md; no plugin dependency in this pass. |
| npmjs | package.json exports compiled TypeScript cargo and gates the payload with npm pack --dry-run --json. No imaginary barrels aboard. |
.bao |
bao/piratebao.manifest.json is a cargo ledger, not an archive format. The quartermaster checks it. |
| Not aboard | Reason |
|---|---|
| Legacy aliases | Break rename is intentional. Old names are barnacles — scrape them. |
| CLI fallback for compression | Missing ANTHROPIC_API_KEY fails directly. Ghost oars cost maintenance and sometimes row toward prod. |
.bao archive builder |
This pass counts barrels and checks labels only. No archive builder lurks below deck. |
| Runtime TypeScript loader for hooks | Hooks run compiled JS. Ship does not stop to compile at dawn. |
日本語 README
PirateBao は Bun-first / TypeScript-first の海賊リグです。AI コーディング返答から挨拶の泡、遠慮の霧、謝罪のフジツボを斬り捨てます。コード、コマンド、パス、バージョン、危険、スタックトレース、テスト結果はマストに釘打ちます。クラーケンは boilerplate を食べ、TypeError は残します。オウムは騒ぐ。token は金貨。礼儀に銀貨を払う船長はおらぬ。
AI は宝箱の前で長々と挨拶し、地図を三度読み直し、甲板を磨いて磨いて磨きがちです。PirateBao は泡を海に捨て、宝だけマストに残します: コマンド、ファイル、バグ、修正。金貨で霧を買わぬ。海賊は礼儀に銀を払わぬ。
flowchart LR
A["長い返答"] --> B["前置きを捨てる"]
B --> C["短い技術返答"]
C --> D["token削減"]
D --> E["速い航海"]
| 項目 | 内容 |
|---|---|
| 既定の帆 | kraken |
| 主要コマンド | /piratebao, /piratebao:compress <file>, /piratebao-help |
| 日本語モード | nihon-skiff, nihon-brig, nihon-kraken |
| 検証 | bun run check が TypeScript、Vitest、.bao、OpenCode、npmjs dry-run を通す |
| 積荷台帳 | bao/piratebao.manifest.json に README と OpenCode 積荷を載せる |
bun install --frozen-lockfile
bun run check船長向け結論: これは翻訳された飾りではなく、日本語の短縮モードと検証対象の README です。nihon-kraken は短く切る。rm -rf と npm publish の危険は切りすぎない。髑髏は少なめ、検証は多め。
Schwiizerdütsch README
PirateBao isch es Bun-first, TypeScript-first Pirat-Rigg für churzi AI-Coding-Antworte. Code, Befehle, Pfäd, Versione, Risiko, Stacktraces und Testresultat bliibe am Mascht feschtgnaglet. Begrüessigs-Schaum, Hättegli-Nebel und Entschuldigungsmuschele gönd über Bord — kielholt ohni Gnade. De Chrottekrake frisst Boilerplate, nöd Fehlermeldige. De Papagei chiflet; d token-Rechnig schrumpft. Höflichkeit isch Ballascht.
AI redt mängisch hoi, list d Charte drüümal und poliert s Brett bis es nach Büro riecht. PirateBao seit: Ladig bhalte, Blabla ab is Wasser. Tokens sind Münze; mir zahled nöd für Nebel mit Schnauz. De Hafemeister nickt; de Papagei chrächzt.
flowchart LR
A["Langi Antwort"] --> B["Blabla usem Logbuech streiche"]
B --> C["Kurzi Technik-Antwort"]
C --> D["weniger Tokens"]
D --> E["schnäller Hafe"]
| Teil | Sinn |
|---|---|
| Standard-Segel | kraken |
| Befehle | /piratebao, /piratebao:compress <file>, /piratebao-help |
| Schwiizerdütsch-Modi | swiss-skiff, swiss-brig, swiss-kraken |
| Gate | bun run check prüeft TypeScript, Vitest, .bao, OpenCode und npmjs dry-run |
| Ladigslischte | bao/piratebao.manifest.json listet README und OpenCode-Fracht |
bun install --frozen-lockfile
bun run checkKurz: kei lackierts Fass. Es isch e technischi README-Kopie mit eigenem Pirateton, Sprachmodi und Gate. swiss-kraken schneidet hart; bi Security, Publish und Dateverlust blibt er nüchtern. De Chäpten unterschriibt mit trockene Stiefel und em Schwert am Gurt.
Bun is the package manager of record. npm is used only where npmjs itself is the thing being tested, because even pirates respect the harbor office and its tiny clipboard of pain.
| Harbor | Command | Checks |
|---|---|---|
| Install deps | bun install --frozen-lockfile |
Uses bun.lock; fails if package.json drifted. |
| Build | bun run build |
Emits dist/ JS, declarations, and source maps. |
| Test | bun run test |
Builds, packs piratebao.skill, runs Vitest. |
| Verify all | bun run verify |
Sync, .bao, OpenCode, stale-name scan, npm registry, npm pack dry-run. |
| Complete gate | bun run check |
Typecheck, build, tests, verify, registry, pack dry-run. |
| Post-publish bunx smoke | bunx -p piratebao piratebao-verify |
Runs the npmjs binary from Bun's package runner after the crate exists in the registry. |
Agent installs:
| Agent | Install |
|---|---|
| Claude Code | claude plugin marketplace add d4551/piratebao && claude plugin install piratebao@piratebao |
| Codex | Clone repo, open Codex, install local plugins/piratebao |
| OpenCode | Clone repo; OpenCode reads .opencode/skills/*/SKILL.md and .opencode/commands/*.md |
| Gemini CLI | gemini extensions install https://github.com/d4551/piratebao |
| Cursor/Windsurf/Cline/Copilot | npx skills add d4551/piratebao |
Standalone Claude Code hooks:
bun install --frozen-lockfile
bun run build
bash hooks/install.shUninstall:
bash hooks/uninstall.sh| Command | Loot |
|---|---|
/piratebao |
default kraken mode |
/piratebao skiff |
light terse prose |
/piratebao brig |
strong terse prose |
/piratebao kraken |
maximum terse prose |
/piratebao jade-skiff |
light classical Chinese terse mode |
/piratebao jade-brig |
strong classical Chinese terse mode |
/piratebao jade-kraken |
maximum classical Chinese terse mode |
/piratebao nihon-skiff |
light Japanese terse mode |
/piratebao nihon-brig |
strong Japanese terse mode |
/piratebao nihon-kraken |
maximum Japanese terse mode |
/piratebao swiss-skiff |
light Swiss German terse mode |
/piratebao swiss-brig |
strong Swiss German terse mode |
/piratebao swiss-kraken |
maximum Swiss German terse mode |
/piratebao-commit |
terse Conventional Commit message |
/piratebao-review |
one-line review findings |
/piratebao:compress <file> |
compress natural-language memory file |
/piratebao-help |
command card |
$piratebao |
Codex skill trigger |
Deactivate with stop PirateBao or normal mode.
| Family | Modes | Output contract |
|---|---|---|
| English | skiff, brig, kraken |
shorter prose, same technical payload, stricter ceiling as sail gets heavier |
| Classical Chinese | jade-skiff, jade-brig, jade-kraken |
terse classical Chinese phrasing, examples gated by token monotonicity |
| Japanese | nihon-skiff, nihon-brig, nihon-kraken |
Japanese terse mode with the same no-filler/no-self-reference rules |
| Swiss German | swiss-skiff, swiss-brig, swiss-kraken |
Swiss German terse mode with the same compression ceilings |
All families forbid self-announcements like mode banners unless the user explicitly asks. PirateBao steers the ship; it does not give a speech from the crow's nest. The best compression is the sentence never emitted. The second best is the sentence that lost its adjectives at sea.
flowchart TD
Prompt["agent prompt"] --> Hook["readCaptainOrder"]
Hook --> Flag["~/.claude/.piratebao-active"]
Session["session start"] --> Raise["raiseJollyRoger"]
Raise --> Skill["skills/piratebao/SKILL.md"]
Skill --> Filter["mode-specific rule filter"]
Filter --> Agent["agent context"]
Flag --> Status["paintStatusFlag"]
SessionStart loads the compiled hook and canonical skill once per invocation. UserPromptSubmit updates the mode flag. Statusline reads the flag and prints a small badge. This keeps startup work bounded; the ship does not inspect every barrel on each wave or bill you for barnacle inventory.
flowchart TD
Skill["skills/piratebao/SKILL.md"] --> Sync["syncTreasureMap"]
Sync --> Copies["OpenCode/Cursor/Windsurf/Copilot/plugin copies"]
Skill --> Pack["packSkillCargo"]
Pack --> Zip["piratebao.skill"]
Schema["schemas/piratebao-bao-manifest.schema.json"] --> Gate["verifyHarbor"]
Manifest["bao/piratebao.manifest.json"] --> Gate
Copies --> Gate
Zip --> Gate
Gate --> Release["npmjs-ready package"]
Canonical files are edited once, then synced. verifyHarbor rejects copy drift, stale brand tokens, missing OpenCode cargo, malformed plugin manifests, missing compiled artifacts, wrong zip contents, and README drift. The quartermaster is boring on purpose; comedy belongs in prose, not package invariants. The gate has no sense of humor and no parrot.
Use this before publishing or after touching docs, skills, hooks, manifests, or compression logic:
bun install --frozen-lockfile
bun run typecheck
bun run build
bun run test
bun run verify
bun run pack:dryRuntime smoke for standalone Claude Code hooks:
tmp_home="$(mktemp -d)"
HOME="$tmp_home" bash hooks/install.sh --force
HOME="$tmp_home" node "$tmp_home/.claude/hooks/piratebao-dist/hooks/raiseJollyRoger.js"
printf '{"prompt":"/piratebao swiss-kraken"}' | HOME="$tmp_home" node "$tmp_home/.claude/hooks/piratebao-dist/hooks/readCaptainOrder.js"
cat "$tmp_home/.claude/.piratebao-active"
HOME="$tmp_home" bash hooks/uninstall.sh
rm -rf "$tmp_home"Expected smoke result: install succeeds, session hook emits PirateBao rules, prompt hook writes swiss-kraken, uninstall removes hook cargo. No bottle note required.
OpenCode support is project-native:
| File | Purpose |
|---|---|
opencode.json |
Points OpenCode at AGENTS.md and allows piratebao* skills. |
.opencode/skills/piratebao/SKILL.md |
Synced main skill. |
.opencode/skills/piratebao-compress/SKILL.md |
Synced compressor skill. |
.opencode/commands/piratebao.md |
/piratebao command template. |
.opencode/commands/piratebao-compress.md |
Platform-safe /piratebao-compress; uses $ARGUMENTS. |
Command filenames avoid : for cross-platform safety. Frontmatter descriptions are verified. This is not a TypeScript OpenCode plugin; no extra runtime hook hides in the bilge wearing a false moustache.
Pinned current stack, verified on 2026-04-12:
| Tool | Version | Role |
|---|---|---|
| Bun | 1.3.12 |
install/scripts; lockfile authority |
| TypeScript | 6.0.2 |
strict compile for src/ and tests |
| Node | >=24.11.0 |
runtime target for compiled hooks/CLIs |
| Vitest | 4.1.4 |
behavior tests |
| AJV | 8.18.0 |
.bao schema validation |
| Anthropic SDK | 0.88.0 |
compressor API client |
| js-tiktoken | 1.0.21 |
token evals |
No direct env reads outside config modules. No any in implementation/tests. No TypeScript suppressions. If the mast cracks, the compiler gets first complaint, not a postmortem parrot. Types are the rigging; if they fray, the sail falls before the wind arrives.
PirateBao validates manifest contract. .bao is cargo ledger, not archive chest. The verifier counts barrels, then complains like a sober quartermaster.
| Item | Path |
|---|---|
| schema | schemas/piratebao-bao-manifest.schema.json |
| manifest | bao/piratebao.manifest.json |
| validator | src/shipyard/validateBaoChest.ts |
| full gate | src/shipyard/verifyHarbor.ts |
| OpenCode cargo | .opencode/skills/*/SKILL.md + .opencode/commands/*.md |
Gate checks manifest schema, key order, referenced files, README inclusion, synced skill copies, OpenCode files, plugin metadata, stale brand tokens, compiled artifacts, shell scripts, npmjs package files, and piratebao.skill contents.
flowchart LR
M["manifest"] --> S["schema validate"]
S --> F["referenced files exist"]
F --> O["OpenCode cargo present"]
O --> Z["zip contains piratebao/SKILL.md"]
Z --> P["package files checked"]
P --> OK["ship"]
Package name: piratebao. Registry gate checks availability before publish. npm dry-run checks payload, not vibes. The harbor rejects imaginary treasure; the verifier checks labels before the crate reaches the dock. Painted barrels without rum get thrown back.
Required npmjs fields are set: main, types, exports, bin, files, license, repository, bugs, publishConfig.
Dry-run before publish:
bun run checkPost-publish binary smoke:
bunx -p piratebao piratebao-verify
npx -p piratebao piratebao-verifyUse -p piratebao because the npm package is piratebao while the binary names are specific tools like piratebao-verify and piratebao-compress. That is not a riddle; it is just npm making the plank longer.
package.json files includes README, .bao manifest/schema cargo, OpenCode files, agent plugin files, compiled dist/, shell hooks, and piratebao.skill. Painted barrels without files fail verification. CLI bin entries use npm-normalized paths and shebang-bearing JS so npm does not quietly saw the rudder off during publish dry-run.
/piratebao:compress <file> is for natural-language memory files: agent notes, project instructions, todos, and preference docs. It preserves code blocks, inline code, URLs, paths, headings, commands, versions, and proper nouns. It removes prose barnacles, not your mast. If a paragraph is mostly velvet rope, it becomes rope.
Set:
export ANTHROPIC_API_KEY=...
export PIRATEBAO_MODEL=claude-sonnet-4-5-20250929No CLI fallback. Missing key fails with direct error. No ghost oar under the floorboards, no mystery subprocess paddling toward a rate limit.
flowchart TD
File["memory file"] --> Detect["inspectFilling"]
Detect -->|prose| Call["Anthropic Messages API"]
Detect -->|code/config| Skip["skip"]
Call --> Backup["write .original.md"]
Backup --> Validate["sealBaoScroll"]
Validate -->|ok| Done["compressed file"]
Validate -->|bad| Fix["targeted fix prompt"]
Fix --> Validate
| Path | Loot |
|---|---|
skills/piratebao/SKILL.md |
canonical behavior |
piratebao-compress/SKILL.md |
canonical compressor skill |
.opencode/ |
native OpenCode commands + skills |
src/hooks/ |
compiled Claude Code hooks |
src/dumpling/ |
compressor + token logic |
src/evals/ |
js-tiktoken snapshot accounting |
src/shipyard/ |
sync, packaging, .bao, verify |
hooks/ |
shell/PowerShell installer + statusline entrypoints |
piratebao.skill |
deterministic skill zip containing piratebao/SKILL.md |
Eval snapshots live in evals/snapshots/results.json. Current committed gate: 77% average saved, 68% worst saved. README claims must come from committed snapshot output. No treasure-map fiction; the sea already has enough myths, several consultants, and a kraken who cannot count.
bun run build
node dist/evals/countTreasureTokens.jsLive benchmark needs ANTHROPIC_API_KEY:
node dist/benchmarks/runTreasure.jsbun install --frozen-lockfile
bun run check
npm publish --access publicBefore publish, confirm piratebao.skill contains only piratebao/SKILL.md, .opencode files appear in npm pack --dry-run --json, README token numbers match evals/README.md, and npm publish --dry-run --access public --json emits no npm auto-correction warnings. Then ship. Quietly. Pirates can be professionals; the cannon is for bugs.