SIGNAL · v0.3.2

Protocol entrypoints: skills/signal.min.md · symbols skills/signal-core.min.md · repo github.com/mattbaconz/signal · releases CHANGELOG.md

Demo · Install · Commands · Benchmark · Repo map · Architecture · Changelog

Before / after · Tiers · Karpathy norms · Git & CI · Stars

What to trust first: ~87% smaller skill payloads on disk (seven .md → .min.md pairs, reproducible) and ~67% fewer characters in the live assistant reply (Gemini CLI JSON, EqualContext — matched prompt_tokens). tokens.total on that same single-turn run only moves ~8% because prompt tokens (~8k) dominate the sum — that is expected, not a failed headline. Details: Benchmark · docs/token-metrics.md.

What’s illustration: scenarios A–C use ceil(characters / 4) (not billed API tokens) — good for shape, not primary “proof” vs hosts that report real tokenizer counts.

Reproduce: scripts/benchmark.ps1 (static) · benchmark/run.ps1 / benchmark/README.md (live + long-session).

npx skills add mattbaconz/signal

Global:

npx skills add mattbaconz/signal -y -g

After install: open skills/signal.min.md, pick S1 / S2 / S3, add workflow skills (signal-commit, …) only when you need them.

Plugins only exist in Claude Code (the coding agent). The consumer claude.ai desktop chat does not expose /plugin — if slash commands like /plugin are ignored or “unknown,” you’re either in the wrong app or on an old Claude Code build. Update Claude Code and restart; official troubleshooting: Discover plugins — “/plugin command not recognized”.

A) Plugin marketplace (when /plugin works) — in the Claude Code session, same input as other slash commands:

/plugin marketplace add mattbaconz/signal
/plugin install signal@signal-suite

(owner/repo works for GitHub; you can use a full Git URL instead.) Then run /reload-plugins. Marketplace id is signal-suite — confirm with /plugin marketplace list. Details: claude-signal/README.md.

With the plugin, skills are namespaced: /signal:signal, /signal:signal-commit, /signal:signal-push, … (plugin name signal, then :, then folder name under claude-signal/skills/).

B) No /plugin — standalone skills (works everywhere Claude loads ~/.claude/skills/): clone this repo, run scripts/sync-integration-packages.ps1 once if needed, then:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-signal-all.ps1

That copies claude-signal/skills/ into %USERPROFILE%\.claude\skills\. Then use short commands like /signal, /signal-commit (see Commands). Do not also install the plugin for the same skills.

C) One-off: run Claude Code from a terminal with the plugin dir — claude-signal/README.md (claude --plugin-dir ./claude-signal from the repo).

Optional: merge templates/claude-CLAUDE.min.md into your project CLAUDE.md for thin always-on defaults.

Tier detail: Tiers.

There is no legacy top-level signal/ directory in this repo—ignore older docs that referred to it. This table is what you actually open after cloning.

Same idea as At a glance, with moving parts: symbols instead of paragraphs, .signal_state.md for durable state, signal-diff / signal-search instead of raw dumps — all optional tools you pull in when the session needs them.

flowchart LR
  subgraph inputs [Verbose]
    V1[Long replies]
    V2[Full thread history]
    V3[Hedging and filler]
  end
  subgraph signal [SIGNAL]
    S[Symbol grammar]
    C[CKPT summaries]
    M[Minified skills]
  end
  subgraph outputs [Dense]
    D1[Terse pointers]
    D2[Checkpoint atom]
    D3[~87% smaller payloads]
  end
  V1 --> S
  V2 --> C
  V3 --> S
  S --> D1
  C --> D2
  M --> D3

Cumulative transcript savings (baseline vs checkpoint-style history) are covered in benchmark/README.md (benchmark/long-session/ after a full clone). Prompt vs output vs tokens.total — hosts report different scopes; see docs/token-metrics.md.

Use /signal, /signal2, or /signal3.

Full reference: [skills/signal-core.min.md](skills/signal-core.min.md).

The chart matches Demo. Honest order of strength: (1) skill file shrink on disk — verifiable byte counts; (2) live reply length — real JSON from one Gemini run; (3) single-turn tokens.total — moves slowly when prompt is huge; (4) scripted A–C — ceil(chars/4) illustrations, not API tokenizer truth.

Uses ceil(characters / 4) — not billed API tokens; useful for shape, not a substitute for tokenizer-accurate counts on every host.

Min-only helpers (signal-core, signal-diff, signal-search) ≈ 1.6K bytes (~389 est. tokens).

Caveat: one turn per arm, EqualContext (matched project GEMINI.md). No checkpoints, no /signal3 auto-CKPT, no multi-turn BOOT/delta — this stresses output style on one task type, not long-session history collapse.

Source: benchmark/benchmark chess/run_chess_compare.ps1 with -Pair EqualContext. Model gemini-3.1-pro-preview.

Why tokens.total is not the hero row: both sides load ~8k prompt tokens. tokens.total ≈ prompt + generation, so a big reply cut still yields only a ~8% drop in tokens.total — while reply characters fall ~67% (that is the visible win on this run).

[docs/token-metrics.md](docs/token-metrics.md) — prompt vs output vs tokens.total. Multi-turn / cumulative protocol benchmark: [benchmark/long-session/](benchmark/long-session/) (see [benchmark/README.md](benchmark/README.md)) — that is where checkpoint-style savings compound vs a growing baseline transcript.

Static (heuristic + skill table printout; no API):

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\benchmark.ps1

Live chess (refreshes JSON under benchmark/benchmark chess/):

powershell -NoProfile -ExecutionPolicy Bypass -File .\benchmark\run.ps1 -Mode Chess -Pair EqualContext

Long-session (multi-turn; many API calls):

powershell -NoProfile -ExecutionPolicy Bypass -File .\benchmark\run.ps1 -Mode LongSession -Quick

flowchart TB
  subgraph protocol [Protocol layer]
    P["signal.min.md"]
    CORE["signal-core.min.md"]
  end
  subgraph workflow [Workflow skills]
    CKPT["signal-ckpt"]
    GIT["commit / push / pr"]
    REV["signal-review"]
  end
  subgraph context [Context tools]
    DIFF["signal-diff"]
    SRCH["signal-search"]
    ST["signal-state"]
  end
  subgraph persist [Persistence]
    STATE[".signal_state.md"]
  end
  P --> CORE
  P --> CKPT
  P --> GIT
  P --> REV
  P --> DIFF
  P --> SRCH
  ST --> STATE

Tier ladder:

flowchart LR
  S1["/signal — S1"] --> S2["/signal2 — S2"]
  S2 --> S3["/signal3 — S3"]
  S1 -.- D1["~35% vs loose chat"]
  S2 -.- D2["BOOT · aliases · Δ"]
  S3 -.- D3["Auto-CKPT every 5 turns"]

Tiers shape assistant chat (symbols, templates, checkpoints). Karpathy-style norms shape implementation work (how you edit code and ship commits): orthogonal axes—activating /signal3 does not replace surgical diffs or explicit assumptions.

Norms in brief (canonical list: [references/karpathy-coding-norms.md](references/karpathy-coding-norms.md)):

1. Assumptions — explicit over implicit; say when unsure.
2. Simplicity — avoid over-engineering.
3. Surgical diffs — minimal changes tied to the goal.
4. Verifiable goals — reproduce, test, or verify where it matters.
5. No filler — skip “here is the code”; show the code.

CI: [.github/workflows/verify.yml](.github/workflows/verify.yml) runs [scripts/verify.ps1](scripts/verify.ps1) on Windows for main and PRs.

All releases: CHANGELOG.md.

./
├── skills/              # canonical *.md + *.min.md (edit here; see CONTRIBUTING.md)
├── assets/              # logos, benchmark infographic
├── references/          # symbols, Karpathy norms, benchmarks, checkpoint notes
├── templates/           # Gemini / Claude merge snippets
├── scripts/             # benchmark.ps1, shrink.ps1, verify.ps1, sync-integration-packages.ps1
├── gemini-signal/       # Gemini CLI extension (mirrored from skills/)
├── claude-signal/       # Claude Code plugin (mirrored from skills/)
├── kiro-signal/         # Kiro IDE import (mirrored + bundled references/)
├── hooks/
└── GEMINI.md            # root context (synced from gemini-signal/)

v0.3.2 — Shrinking Session. Brutalist token compression.