wireword

Wireword

Wireword is a linter for LLM agent control words.

Agent workflows use short labels for routes, tools, macros, roles, environments, profiles, and approval targets. Those labels become part of the control plane. If two labels are easy to confuse, one typo or model substitution can route work to the wrong place.

Wireword starts with one narrow tool:

wireword lint-tokens A1 AI Al

Example output:

HIGH A1, AI: visual confusable labels may be copied or routed incorrectly
HIGH A1, Al: visual confusable labels may be copied or routed incorrectly
HIGH AI, Al: visual confusable labels may be copied or routed incorrectly

Why telegraph history matters

Commercial telegraph codebooks did more than shorten messages. They also had to make compressed words recoverable after transmission errors.

E. L. Bentley described the rule clearly: good codewords should differ by at least two letters, so one mutilated letter does not silently produce another valid codeword. The 1920 sixth edition of the ABC Code used the same "two-letter difference" principle for five-letter codewords.

Wireword applies that idea to modern agent control words:

A control word should be short enough to use, but redundant enough that an error is detectable.

Current checks

wireword lint-tokens currently flags:

• visual confusables, such as A1, AI, and Al
• edit-distance-one pairs, such as docs.api and doc.api
• case-only differences, such as Prod and prod
• punctuation-only differences, such as FACTCHECK_API and FACT_CHECK_API
• plural or stem-like pairs, such as policy and policies
• overloaded production labels, such as prod, production, and live

wireword lint-config adds effect-aware checks for typed label sections:

• routes
• tools
• named agent handoffs
• approval targets
• macros
• profiles
• environments
• exact enum values emitted by a model

Install for local development

python -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

Run tests:

.venv/bin/python -m pytest -q
.venv/bin/python -m ruff check src tests

CLI

Lint positional tokens:

wireword lint-tokens docs.api doc.api worker.docs

Lint newline-delimited tokens from a file:

wireword lint-tokens --file tokens.txt

Lint typed agent labels from YAML:

wireword lint-config examples/bad-labels.yaml

Print machine-readable findings:

wireword lint-config --format json examples/bad-labels.yaml

Extract and lint FastMCP tool names from Python source without importing the server:

wireword lint-mcp-tools jc_mcp/server.py

Example config:

routes:
  docs.api:
    effect: read_only
  doc.api:
    effect: external_write

tools:
  deploy.docs:
    effect: external_write
    requires_approval: true
  deploy.doc:
    effect: external_write
    requires_approval: true

environments:
  prod:
    canonical: true
  production:
    alias_of: prod
  live:
    alias_of: prod

Real project example

examples/jean-claude-labels.yaml is a representative label surface from a small MCP assistant project. It includes MCP tool names and skill-route names:

wireword lint-config examples/jean-claude-labels.yaml

Current result:

No Wireword token risks found.

The same tool names can also be extracted from the local FastMCP server source with wireword lint-mcp-tools. That clean result is useful. It shows the intended use: run Wireword before adding new model-visible tools, routes, or approval targets.

Validation corpus

The test suite includes a small validation corpus:

tests/fixtures/corpus/safe.yaml
tests/fixtures/corpus/dangerous.yaml
tests/fixtures/corpus/malformed.yaml

The corpus keeps three behaviors explicit:

• known-safe labels produce no findings
• representative risky labels trigger the current rule families
• malformed config exits as a usage error

Claude plugin

The Claude plugin is experimental. It now exists to help review agent control words, not to define a full orchestration stack.

Plugin source:

plugins/claude/wireword

Marketplace manifest:

.claude-plugin/marketplace.json

Research note

Blog draft:

hugo/content/posts/wireword-control-words.md

Planned public post URL:

https://www.jockeyholler.net/posts/wireword-control-words/

Sources

• E. L. Bentley, "Codes: Their Nature and Manipulation," transcribed by John McVey: https://www.jmcvey.net/cable/harmsworth_2.htm
• John McVey, "A.B.C. Telegraphic Codes, seven editions 1873-1936": https://jmcvey.net/cable/scans/ABC.htm
• Steven M. Bellovin, "Compression, Correction, Confidentiality, and Comprehension: A Modern Look at Commercial Telegraph Codes": https://www.usenix.org/conference/usenixsecurity09/technical-sessions/presentation/compression-correction-confidentiality