CANarchy

A stream-first CAN bus toolkit for analysts, security researchers, and AI agents.
Every command emits typed, machine-readable events you can pipe, script, or hand to an agent — with J1939 heavy-vehicle support as a first-class citizen.

What is CANarchy?

CANarchy is a CLI-first runtime for capturing, decoding, and manipulating CAN and CAN-FD traffic. Most CAN tools force a tradeoff: interactive but hard to automate, scriptable but too raw, or protocol-aware but inconsistent across interfaces. CANarchy is built around the opposite constraint — every output is a stream of typed events (--json, --jsonl, --text) you can parse, pipe, or forward to an LLM agent over MCP.

It's for you if you're:

• A security researcher reversing an unknown bus, fuzzing ECUs, or diffing captures for anomalies.
• A heavy-vehicle / J1939 engineer who wants PGN/SPN decoding, TP reassembly, and DM1 fault parsing without dropping to raw IDs.
• Building automation or AI agents that need a stable, machine-readable CAN interface instead of scraping human-formatted text.

Install

pipx install canarchy          # isolated, on PATH everywhere
# or:  pip install --user canarchy

Requires Python 3.12+. Live transport uses python-can (socketcan, virtual bus, UDP multicast, and more).

Try it in 60 seconds — no hardware required

canarchy --version
canarchy doctor --text          # 8 offline health checks; all green = good install

# Stream typed events from the deterministic scaffold backend —
# no hardware, no fixtures, no network. This is the JSONL contract:
CANARCHY_TRANSPORT_BACKEND=scaffold canarchy capture can0 --jsonl

Point it at a real interface once you have one:

canarchy capture can0 --candump                 # human-friendly live view
canarchy capture can0 --jsonl | jq .            # typed events, one per line

Prefer to explore visually? Launch the full-screen TUI (pictured above) and watch the bus live:

canarchy tui        # /capture <iface> to stream; /filter, /sort, /help

Why CANarchy?

The event schema is the stable contract; the CLI wraps it. That one design choice is what sets CANarchy apart from most open-source CAN tooling:

• Structured output is the contract, not an afterthought. Every command — capture, decode, fuzz, reverse-engineer — emits the same canonical JSON envelope. Parse once, reuse everywhere.
• Pipe-first. --jsonl streams one typed event per line, so | jq, | grep, or a downstream script Just Works.
• J1939 is first-class. PGN decoding, SPN extraction, TP session reassembly, and DM1 fault parsing resolve names from a bundled SAE catalog — not just raw arbitration IDs.
• Agent-ready. A built-in MCP server exposes the toolkit to Claude and other MCP clients, so an agent can drive CAN analysis directly.

See the full CAN tool feature matrix for an honest, side-by-side comparison with can-utils, SavvyCAN, Caring Caribou, TruckDevil, and others.

What can you do with it?

# Decode a capture against a DBC
canarchy decode --file trace.candump --dbc vehicle.dbc --jsonl

# J1939 heavy-vehicle analysis
canarchy j1939 decode --file trace.candump --text
canarchy j1939 spn 110 --file trace.candump --text     # Engine Coolant Temp
canarchy j1939 dm1  --file trace.candump --text          # active fault codes

# Reverse-engineer an unknown bus: rank likely signals, counters, anomalies
canarchy re signals   --file trace.candump --jsonl
canarchy re anomalies --file trace.candump --baseline known_good.candump --jsonl

# Diff two captures per arbitration ID (rate/timing/entropy deltas)
canarchy compare before.candump after.candump --json

# Active workflows (gated by the active-transmit safety model; --dry-run plans safely)
canarchy generate can0 --count 10 --gap 50 --id 7DF --jsonl
canarchy replay --file trace.candump --rate 2.0 --json

# Pipe events straight into downstream tooling
canarchy j1939 spn 110 --file trace.candump --jsonl \
  | jq '[.payload.value, .payload.units, .payload.timestamp]'

Drive it from an AI agent (MCP)

CANarchy ships a Model Context Protocol server, so an LLM agent can capture, decode, and analyze CAN traffic through the same structured contract the CLI uses.

canarchy mcp install --client claude-desktop   # or: --client claude-code
canarchy mcp serve                             # or run the stdio server directly

Active-transmit tools require an explicit acknowledgement, so an agent can't put frames on a live bus by accident. See the active-transmit safety design.

The full-screen TUI

canarchy tui opens an interactive, full-screen dashboard that streams the bus live:

• Responsive workspaces: Alt+1–Alt+5 switch Traffic, Signals (one row per decoded observation), J1939, UDS, and Findings. Traffic opens as a per-bus, standard/extended-ID summary with counts, rate, changed-byte offsets, and activity; v switches to the chronological event log. The active table uses the available height; wide terminals show a selected-row inspector, while Enter opens complete raw hex/bit details on narrow terminals (Esc returns).
• Background capture: /capture <iface> starts streaming; /stop (or x) ends it.
• Interactive: /filter traffic 'id==0x123' (also pgn== and sa==), /sort traffic <column>, arrow-key row navigation, F4 to freeze inspection or return live, F3 to expand activity, space to pause the feed, [/] to resize the backlog, ctrl+f to maximize a table. Other panes keep /filter <pane> <text> and /sort <pane> <column>.
• Type any real CANarchy command at the prompt — event output folds into the panes, while stats, DBC inspection, diagnostics, reference lookups, errors, and help appear in a scrollable result view. Press F2 to switch views or Esc to return to the panes.

The structured contract

Every successful command returns a stable envelope:

{ "ok": true, "command": "capture", "data": {}, "warnings": [], "errors": [] }

Failures return structured errors with actionable hints (and a documented error-code catalog):

{
  "ok": false,
  "command": "decode",
  "data": {},
  "warnings": [],
  "errors": [
    { "code": "DBC_LOAD_FAILED", "message": "Failed to parse DBC file.", "hint": "Validate the DBC syntax and line endings." }
  ]
}

Use --candump for a human-oriented live view; use --jsonl when feeding scripts or agents — every line is a typed event from the canonical schema. Set CANARCHY_PYTHON_CAN_INTERFACE to choose an interface type, or CANARCHY_TRANSPORT_BACKEND=scaffold for deterministic offline behavior.

Documentation

• Getting Started · Cookbook — task-oriented recipes
• Event Schema — the canonical envelope for all structured output
• Command spec · Architecture
• CAN Tool Feature Matrix — comparison to other OSS CAN tools
• J1939 Heavy Vehicle Demo · Troubleshooting
• Full docs site: hexsecs.github.io/canarchy

Install from source (development)

CANarchy uses uv for environment, dependency, and packaging workflows.

git clone https://github.com/hexsecs/canarchy && cd canarchy
uv sync                          # create the venv and install from the checkout
uv run canarchy --help
uv tool install --editable .     # optional: put `canarchy` on your PATH; edits take effect live

Run the test suite end to end:

uv run python -m unittest discover -s tests -v

Shell completions for bash, zsh, and fish come from canarchy completion <shell> — see Getting Started.

Community & contributing

CANarchy is GPL-3.0-licensed and welcomes contributions.

• ⭐ Star the repo if it's useful — it genuinely helps others find it.
• Contributing guide — local development, branch flow, and PR gates
• Code of Conduct
• Security Policy — reporting concerns and safe active-bus operation

⚠️ CANarchy can transmit on live buses. Only operate against vehicles, ECUs, and networks you own or are explicitly authorized to test. Active-transmit commands require explicit acknowledgement by design.

Philosophy

• The CLI is the contract.
• Protocol semantics over raw frames.
• Structured output over formatted text.
• Reproducible workflows over ad-hoc interaction.

_{Versioning follows SemVer; see the changelog and release workflow. src/canarchy/__init__.py is the authoritative version source.}