Shannon — Entropy Collapse for Frontier Agents

// why shannon

Frontier agents hide evaluation awareness

When an LLM agent realizes it is being evaluated, its token distribution undergoes a characteristic entropy collapse — the same thermodynamic signature as a ligand locking into a binding pocket. Shannon detects that collapse in real time, with white-box physics and no fine-tuning.

The problem

Frontier models sandbag, scheme, and strategically narrow their outputs under eval conditions. Black-box probes and behavioral checks lag the distributional shift. You need a signal that is model-agnostic, streaming-native, and grounded in information theory.

The signal

Configurational entropy over the next-token distribution. Broad exploratory sampling stays high-H; strategic lock-in drops H hard.

Normal H ~ 8–12 bits

Eval-aware H ~ 2–4 bits

Trigger ΔH < −3.2 bits

// capabilities

Capabilities grid

Collapse detection

Sliding-window entropy tracker with stable two-pass variance, z-score, and ΔH triggers. Callback-driven handrails: log, alert, throttle, kill, webhook.

Default threshold δ = −3.2 bits
Configurable window (default 8 tokens)
Bounded traces for long agents

Per-token speed

SIMD dispatch across Scalar, OpenMP, SSE4.2, AVX2, AVX-512, and NEON. Top-k API logprobs stay under one microsecond per token on the committed benchmark path.

<1 µs/token (top-k streaming)
Logits, probs, or log-probs input
NaN-safe log-sum-exp kernel

Agent hub / gate

Shannon Gate coordinates spawn, control, monitor, and kill across local agent processes. Hub audit surfaces collapse events with full entropy traces.

Hub manager + handrail engine
Unix socket and shared-memory streams
Pill bridge for live macOS readout

Cross-host roster

Attach agents running under common hosts and terminals. Same entropy pipeline whether the stream comes from Codex, Claude, Grok, or OpenCode.

Codex · Claude · Grok · OpenCode
Terminal attach (⌘D on macOS Pill)
JSONL stdin and socket ingest

Same kernel as docking

Direct port of the FlexAID∆S configurational entropy engine (statmech log-sum-exp). Jaynes identity: Gibbs S and Shannon H are one object in different units.

H = −Σ pᵢ log₂ pᵢ
Validated docking lineage (r = 0.93 ITC)
Shared math with FlexAID∆S / NATURaL

Open Apache-friendly OSS

C++20 core, Python package, Swift Pill/macOS app. Clone, build, and instrument your own agent streams without a proprietary monitor stack.

C++20 · Python · Swift (Pill)
Homebrew formula + cask paths
github.com/LeBonhommePharma/Shannon

// pipeline

How it works

Step 1

Stream tokens

Ingest logits, probs, or log-probs via JSONL stdin, Unix socket, or shared memory from the live LLM agent.

Step 2

Compute H

UnifiedDispatch selects the best SIMD kernel. Per-token Shannon entropy H and sliding-window ΔH in bits.

Step 3

Collapse / hub audit

CollapseDetector fires handrails. Hub records the event; Gate can alert, throttle, or kill the agent process.

Normal generation holds H ~ 8–12 bits. Evaluation-aware or strategic modes compress toward H ~ 2–4 bits. When ΔH < −3.2, Shannon reports collapse — the same phase signature FlexAID∆S reads when a ligand locks into a pocket.

// get started

Install

# clone

$ git clone https://github.com/LeBonhommePharma/Shannon.git

$ cd Shannon

# C++20 core + shannon-agent

$ cmake -B build -DCMAKE_BUILD_TYPE=Release

$ cmake --build build -j

$ ctest --test-dir build --output-on-failure

Options: SHANNON_BUILD_AGENT, SHANNON_BUILD_PYTHON, SHANNON_USE_OPENMP (defaults ON).

# one command from a clone — app + pets + menu-bar pill

$ git clone https://github.com/LeBonhommePharma/Shannon

$ cd Shannon

$ ./scripts/shannon

# then: look for the Shannon glyph in the menu bar

$ ./scripts/shannon help

$ ./scripts/shannon probe

Press ⌘D in Terminal, Claude, ChatGPT, Codex, or a browser to attach that app as an agent + pet.

$ pip install "git+https://github.com/LeBonhommePharma/Shannon.git"

# or from a clone:

$ pip install -e ".[dev]"

from shannon import ShannonCollapseDetector

detector = ShannonCollapseDetector(window_size=8, threshold=-3.2)

result = detector.add_logits(logits)

if result.collapsed: ...

CLI: shannon-monitor. Optional C++ extension builds when a C++20 compiler and pybind11 are available.

# monitor stdin JSONL

$ cat token_stream.jsonl | ./build/shannon-agent

# handrails

$ ./build/shannon-agent \

--window 8 \

--threshold -3.2 \

--handrail alert \

--sustained kill \

--count 3

# shared memory / socket

$ ./build/shannon-agent --shmem /shannon_logits

$ ./build/shannon-agent --socket /tmp/shannon.sock

Quiet mode exit codes: 0 = safe · 1 = collapse · 2 = error. Full flags in the repository README.

// multi-agent hub

Shannon Gate & hub

The multi-agent hub is the control plane: spawn, control, monitor, and kill agents under a single entropy referee. Collapse events roll into a hub audit trail; the macOS Pill surfaces live H and agent pets in the notch and menu bar.

Spawn & attach

Register local agents and attach terminal or app hosts. Pets live under ~/.shannon/pets/.

Monitor & audit

Per-agent entropy streams, collapse callbacks, and hub-level audit of strategic lock-in across the roster.

Handrail actions

Escalation ladder: log-only → alert → throttle → kill → coredump → webhook — with cooldown and sustained-count gates.

Codex Claude Grok OpenCode Terminal · ⌘D Pill · macOS

// ecosystem

ShannonH↓