WireBuddy

_{50-second demo · MP4 version}

You and your AI agent, looking at the same packets.

WireBuddy is a Wireshark-style packet viewer in a browser tab, built to sit next to an AI chat
(for example in the Claude Code desktop app's browser pane). The agent works the viewer over MCP
while you watch and click in the same view, and when a capture holds something Wireshark can't
decode or a packet list can't show, the agent extends the viewer itself.

• One view for both of you. The agent's filters, selected packet, marks, comments and columns
  show up in your view as it works, each with a notice; what you do there (open a file, apply a
  filter, start a capture) reaches the agent with its next call, and it sees which packets you
  selected.
  Right-click packets to ask the agent about them without leaving the view. You check its
  findings in the packets instead of taking a summary on trust.
• The agent extends the viewer. Traffic Wireshark doesn't know, such as a company's sensor
  stream or a game's protocol, shows up as "Data". The agent writes a Lua dissector for it from
  the bytes or a spec, tests it against the open capture and reloads the view, which then
  decodes the new protocol, with fields you can filter on and show as columns. When rows aren't
  enough, it writes a panel: a sandboxed page next to the packets that plots, plays or draws
  what's in the capture (images, video, point clouds, a field over time).
• Wireshark's own decoding. Everything is dissected by Wireshark's engine (sharkd), with
  your plugins and preferences (and a profile you choose), so results match Wireshark; Open in
  Wireshark jumps to the real GUI at the same file, filter and packet. When a protocol Wireshark
  knows runs on a port it doesn't expect, Decode As (a right-click, or one call from the agent)
  decodes it without a dissector.
• Live captures the agent can run. The agent starts and stops captures with dumpcap and
  reads them as they grow; so can you, with a Capture Options dialog like Wireshark's.

The viewer itself works like Wireshark:

• Packet list, details and bytes with Wireshark's menu bar, toolbar and keyboard shortcuts:
  coloring rules, a display filter bar with live validation and field autocompletion, linked tree
  and hex highlighting, custom columns ("Apply as Column"), time references the Time column counts
  from, Find Packet, packet history, zoom.
• Follow Stream like Wireshark's window (TCP, UDP, TLS, HTTP and more), and several
  packets selected with Ctrl+click and Shift+click to mark, copy or export them; the agent sees
  the selection too, so you can ask "what's wrong with these packets?".
• Statistics: Expert Information, I/O Graph, protocol hierarchy, conversations and
  endpoints, optionally limited to the display filter.
• TLS decryption with a key log file (SSLKEYLOGFILE), and Export Specified Packets
  (displayed, marked, selected or a range) to a new pcapng/pcap; in pcapng the marks and their
  notes go along as packet comments, which Wireshark shows.
• Export Objects as in Wireshark's File menu: list the files carried in HTTP, email (IMF),
  SMB, TFTP, DICOM and FTP traffic, go to their packets, and save them, each save into a new
  folder; the agent hears where, so you can ask it about them.
• Packet comments as in Wireshark's Edit › Packet Comments: add, edit and delete them, for
  you and the agent alike; the packet list marks commented packets, and pcapng exports (Save As)
  write the comments as edited.
• Live capture with traffic sparklines per interface, promiscuous mode, a capture filter
  checked as you type, new files automatically, a ring buffer and stop conditions; the view
  updates about once a second.

How it compares

Several MCP servers give an agent packet data through Wireshark's command-line tools, for example
Wireshark MCP and
WireMCP. They are the better fit when the agent works on its
own: they run wherever tshark runs (macOS, Windows and Linux, also headless on a server),
Wireshark MCP installs and registers itself with one pip command, they capture live traffic too,
and they bring ready-made analyses WireBuddy doesn't have, such as security and anomaly checks,
threat-intelligence lookups, credential extraction and capture indexes.

WireBuddy is for working on a capture together with the agent:

(Compared with what those projects describe in their READMEs, October 2026.)

Requirements

• Wireshark 4.6 with sharkd, editcap and mergecap (Debian/Ubuntu package
  wireshark-common); the wireshark package too for "Open in Wireshark". Older versions are
  untested, and Ubuntu 22.04 and 24.04 ship 3.6 and 4.2, so take the Wireshark PPA there:

  sudo add-apt-repository ppa:wireshark-dev/stable
  sudo apt install wireshark-common wireshark
  

• For live capture, dumpcap must be allowed to capture as your user:

  sudo dpkg-reconfigure wireshark-common   # answer "Yes"
  sudo usermod -aG wireshark $USER         # then log out and in again
  

• Node.js ≥ 22

Developed on Ubuntu 22.04 with Wireshark 4.6.6; CI runs on Ubuntu 24.04 with the current stable
Wireshark from the PPA. Other Linux distributions should work; macOS and Windows are untested.

Install and run

npm install -g wirebuddy
wirebuddy                      # prints the UI URL, e.g. http://127.0.0.1:8765/?token=…
wirebuddy path/to/capture.pcapng   # open a file right away

npx wirebuddy runs it without installing. From a clone of the repository:

npm install && npm run build
npm start

Options (--help shows the same):

TLS decryption

Start the program whose traffic you want to read with SSLKEYLOGFILE set, e.g.

SSLKEYLOGFILE=~/tls-keys.log firefox

then choose that file under Tools → TLS Keys… in WireBuddy (or start WireBuddy with
--tls-keylog ~/tls-keys.log). The capture is re-dissected, HTTP/2, HTTP and other protocols
inside TLS become visible, and "Open in Wireshark" passes the key log on. A key log file set in
Wireshark's own preferences is picked up automatically. The agent can see whether decryption is
on, but only you choose the file. Treat the key log like a password.

Decode As

A protocol Wireshark knows, on a port it doesn't expect (RTP on UDP port 50000, MQTT on TCP port
18830), shows up as "Data" or as the wrong protocol. Right-click one of its packets and choose
Decode As › UDP Port 50000…, then the protocol by its display-filter name (rtp, mqtt,
dns); data shows the raw bytes. The status bar lists the entries and removes them, and the
agent's decode_as tool does the same in one call.

Entries apply to every capture you open until WireBuddy exits and win over your profile's Decode As
for the same port; WireBuddy never writes your Wireshark profile. Decode As needs Linux, like
extensions.

Extensions

Wireshark decodes thousands of protocols, but not your company's sensor stream or a game's
network protocol: those show up as "Data" (a protocol Wireshark knows on another port needs no
extension: see Decode As). Ask the agent to decode them. It finds the undecoded
traffic (capture_summary lists it), works out the format from the bytes or from a spec you give
it, and writes a Lua dissector into WireBuddy's extension folder:

~/.local/share/wirebuddy/extensions/<name>/
  extension.json    {"label": "ACME telemetry", "version": "1", "description": "…"}
  acme.lua          a Wireshark Lua dissector

It tests the extension against the open capture in a separate sharkd first, then reloads the
view, which decodes the new protocol: its fields appear in the details tree, in filters and
autocompletion, as columns and in "Open in Wireshark". Problems come back to the agent: Lua that
doesn't load, dissectors failing on some packets (with the frame and line), endless loops (stopped
after a second), an extension that crashes sharkd (switched off when it crashes while loading;
the view keeps its previous extensions when one crashes while reading the capture).

Analyze › Extensions… lists the extensions with their status and switches them on and off;
Analyze › Reload Lua Plugins (Ctrl+Shift+L) loads them again after you edited one. You can
write extensions yourself the same way, or share a folder of them with WIREBUDDY_EXTENSIONS.

Extensions are Lua code that runs as you, with access to your files. WireBuddy only loads
extensions no other user could have changed (see SECURITY.md): a shared team
folder that colleagues can write is ignored, and so is a folder on a network or FUSE filesystem,
where that can't be checked. Only let an agent write extensions if you would let it run commands,
and look at what it wrote. Extensions need Linux.

Panels

An extension can also bring a panel: a small web page of its own (panel/main.js, plus
optional HTML, CSS and further modules) that WireBuddy shows in a window next to the packets and
feeds with the open capture, also during a live capture: images or files in the traffic, video,
point clouds, a field over time. The agent writes one when a picture says more than packet rows,
checks it (extensions action "test" finds syntax errors with file and line), opens it with the
panel tool and gets told whether it started, what it shows and every error it throws;
panel action "snapshot" gives it an image of the panel.

You open panels under View › Panels or in Analyze › Extensions. An extension can offer its
panel for captures it fits ("offer": {"filter": "rtp", "text": "Play the video"}): the offer
shows as a chip in the status bar that opens the panel, or with × goes away for that capture. A
panel can select a packet in your view, and with the "control" permission apply a display
filter, but only right after you clicked or typed in it. It can keep up to 256 KiB of JSON
(wb.storage) across restarts. Examples to copy from are in
examples/extensions.

Each panel runs sandboxed on a one-time origin of its own (p<random>.localhost), in its own
browser process, and gets only its own files and the capture, never WireBuddy's API, its token or
(WebRTC aside) the network. A panel that stops responding is stopped after 20 seconds without
slowing WireBuddy down, and one that tries to navigate is closed; SECURITY.md has
the details.

Dissector plugins and profiles

WireBuddy decodes with sharkd, which loads the same plugins and settings as Wireshark:

• C plugins from the global folder (e.g. /usr/lib/x86_64-linux-gnu/wireshark/plugins/4.6/epan)
  and the personal one (~/.local/lib/wireshark/plugins/4.6/epan).
• Lua plugins from the global folder, ~/.local/lib/wireshark/plugins and
  ~/.config/wireshark/plugins.
• Preferences, Decode As, enabled/disabled protocols, coloring rules from ~/.config/wireshark;
  WireBuddy's own Decode As entries apply on top and win for the same port.
• Profiles: --profile <name> starts sharkd (and "Open in Wireshark") with that
  configuration profile.

A plugin's fields show up in the details tree, can be filtered on, appear in filter
autocompletion, and are visible to the agent through inspect_frame. After changing a Lua
plugin, use Analyze › Reload Lua Plugins; restart WireBuddy after adding a C plugin.

Use with Claude Code

Register the MCP server (it also starts the web UI):

claude mcp add wirebuddy -- npx -y wirebuddy --mcp

That needs node on the PATH Claude Code starts MCP servers with. Where it isn't (Node from
nvm or a folder of your own, Claude Code started from the desktop), install WireBuddy and register
it with full paths:

npm install -g wirebuddy
claude mcp add wirebuddy -- "$(command -v node)" "$(npm root -g)/wirebuddy/dist/server/main.js" --mcp

From a clone of the repository, use its dist/server/main.js the same way. There,
node test/agent-demo.mjs shows what the agent side looks like without Claude: it plays a short
scripted session (filter, mark, select) against the fixture; open the URL it prints.

Claude opens the viewer in the browser pane next to the chat by itself as soon as it starts
working with WireBuddy: while no viewer is connected, the tool results remind it, with the URL.

While Claude is attached, the viewer shows you no error messages. Problems (a file that won't
open, a rejected filter, a failed capture, a crashed sharkd) and what you do in the viewer go
to Claude instead, with its next WireBuddy tool call; the status bar only counts the problems
waiting for it. To react while you work, Claude runs wirebuddy --watch <instance-file> as a
background command: it waits for the next problem or question, prints it and exits, which wakes
Claude.

To ask about packets without switching to the chat, right-click them in the packet list and
choose Ask Claude about This Packet… (or Ask Claude about These N Packets…). The question
goes to Claude with the packet numbers and wakes it if its watch is running (the dialog says
whether it is); otherwise it comes with Claude's next step. Claude answers in the chat.

When you notice something during a live capture (the app froze, a reply was slow, a light
flickered), press Now: the flag in the toolbar, or N in the packet list. A tap asks what just
happened; holding it flags everything until you let go. Claude gets the packets of that moment
or span with no typing (at once if its watch is running), looks at them and shows what it found
in your view. The flagged packet, or the span's first and last, also get packet comments
("WireBuddy Now…"), which an export to pcapng keeps. Now works in captures that stay in one file.

Example prompts:

• "Open ~/captures/slow-login.pcapng and tell me why the login is slow."
• "Explain the packet I have selected."
• "Mark all DNS failures and filter to them."
• "Capture on eth0 for a minute and tell me when you see TCP retransmissions."
• "Capture on eth0 while I reproduce the freeze; I'll press Now when it happens."
• "Save the files that were downloaded over HTTP and check them against these hashes."

Example: a robot arm that stutters

examples/investigations/robot-arm is an investigation to
try, all on your machine over loopback: an emulated arm controller and the control app that drives
it. The app should send the controller 50 commands a second but gets about 22 through, and the
arm moves in jerks, while the controller's vendor says it answers in under a millisecond.

The robot arm stutters. Our control app, examples/investigations/robot-arm/app.mjs, should send
the arm controller 50 MOVE commands a second, but gets about 22 through and the arm moves in
jerks. The vendor says the controller answers every command in under a millisecond; their
protocol document is examples/investigations/robot-arm/PROTOCOL.md. The controller is running
on port 7700. Capture the traffic while the app runs and find out why.

As in the demo above, the agent:

1. starts a capture on lo with start_capture, runs the app and stops the capture;
2. finds the controller's protocol undecoded, writes a Lua dissector from the vendor's document,
   tests it on the capture and reloads the view;
3. adds a time-delta column, finds where every command loses its time and marks an example;
4. writes a panel that plots the arm's joints and each command's latency;
5. names the cause, fixes the app and captures again to show the fix.

The example's README has the setup and, at its
end, the solution; solution/armc is a dissector and a panel as the agent might write them. The
commands there assume a clone of the repository; the npm package has the examples too, in
$(npm root -g)/wirebuddy/examples after a global install.

Example: a CT archive that loses slices

examples/investigations/ct-archive is a second one, from
radiology: an emulated image archive and the reconstruction server's exporter that sends it the CT
images of a head phantom over DICOM. The exporter gets Success for all 184 images, yet the archive
holds only 100 of the 160 images of the thin-slice series, and the archive team says it keeps what
it receives.

Radiologists say our new 0.625 mm thin-slice head series show up in the archive with only about
100 of 160 images, and the reformats have steps; the 5 mm series from the same scan are complete.
Our reconstruction server's exporter, examples/investigations/ct-archive/app.mjs, logs every image
as stored with status Success. The archive vendor's conformance statement is
examples/investigations/ct-archive/CONFORMANCE.md. The archive is running on port 11112. Capture
an export and find out where the slices go.

The agent:

1. captures on lo while the exporter runs;
2. finds the DICOM decoded by Wireshark itself: 184 C-STOREs, each answered with Success;
3. lists the images with export_objects and finds 184 of them with only 124 SOP Instance UIDs;
4. marks the pairs of slices that share a UID and may write a panel that shows the series as sent
   and as the archive keeps it;
5. names the cause, fixes the exporter and, with the archive restarted, captures again: 184 UIDs,
   and the archive keeps all 160.

The example's README has the setup and the
solution; solution/ctseries is the panel.

MCP tools

Every agent action that changes the view shows a notice in the UI. Every tool result also
carries what happened in the viewer since the agent's last call: problems, what you did and
the questions you asked it.

How it works

 browser (src/web)  ──HTTP/WebSocket──▶  Node server (src/server)  ──stdio JSON-RPC──▶  sharkd ×2
                                              │                                         (alternate during
 Claude (MCP over stdio) ────────────────────▶│                                          live reloads)
                                              └──▶ dumpcap (live capture → .pcapng)
                                              └──▶ wireshark -r … -Y … -g …

• One server process holds the view state; the UI and the MCP tools share it.
• During a live capture, one sharkd answers requests while the other re-reads the growing
  file; then they swap, so the UI never waits for a reload.
• Once such a re-read takes a second or more, the packets that arrived since are listed within
  about a second anyway, in italics, until the next re-read replaces them: two more sharkd read
  them from slices of the file (about 64 MiB at most) that also hold the packets before them, the
  start of their connections, the messages under way and the answers still owed, so they nearly
  always read as the full read will. Display filters on stream indices, TCP conversation
  completeness or frame numbers, statistics, Follow Stream, Find and the agent's queries wait for
  the full read. When another full read would need more memory than is free, full reads wait
  until the capture stops, and a reload reads the file in place of the copy there is.
• The packet list is virtualized and pages rows from sharkd, so large captures stay smooth.

Security

• The session token is the only boundary. Anyone or anything holding the viewer URL with its
  token can do everything you can in the UI, starting a capture included. That covers an AI agent
  that also has a shell or controls the browser pane: give WireBuddy only to agents you trust,
  and don't share the URL.
• The server listens on the loopback addresses only (127.0.0.1, and the same port on ::1
  where there is one). API calls need the random per-session token in an X-WireBuddy-Token
  header (the WebSocket takes it in its URL); it is compared in constant time.
• Requests with a foreign Host (DNS rebinding), any Origin but the server's own (null
  included) or a body that isn't JSON are refused. The page has a Content Security Policy.
• The MCP tools can start and stop captures on the interfaces dumpcap may capture on, always
  into WireBuddy's capture folder. They can open any capture file you can read, read packets,
  change the filter, marks, time references, packet comments, selection, columns and Decode As
  entries, open and close panels, open Wireshark, and write new .pcap/.pcapng exports where
  you can write; an existing file is never replaced unless the agent exported it itself in the
  same session.
• File › Export Objects and export_objects save files from the traffic, whose names and
  contents a sender chose, only into a new folder they create (http-objects, http-objects-2,
  …) in a directory you or the agent name, under names of their own (f12-report.pdf). No other
  user may be able to change that folder or any folder above it: /tmp works, and so do your
  own folders unless one of them is writable by others; network and FUSE filesystems are
  refused. It is never a hidden folder such as ~/.config, nor one Wireshark or WireBuddy loads
  code or configuration from. It never replaces or follows an existing file. The dialog shows
  names, hosts and types from the capture as plain text, and the agent hears only the folder a
  save went to.
• Text from a capture can't pose as WireBuddy's own messages to the agent: every event is one
  line, the real events block carries a random tag the agent learns at startup, and followed
  stream payload lines start with | .
• Open only accepts files whose content is a capture (pcap, pcapng, snoop, Network Monitor; also
  gzip- or zstd-compressed), whatever their name, so it can't be used to read other files.
• Live captures, exports and saved objects are readable only by you (files 0600, folders
  0700), and so are the slices of big live captures, written to a hidden folder next to the
  capture and removed once it is read in full.
• Extensions are Lua code that runs as you inside sharkd and the Wireshark WireBuddy opens. The
  MCP tools can test, reload and switch extensions, not write them: an agent writes them with its
  own file tools, so it needs file access anyway. Extensions another user could have changed are
  not loaded.
• The traffic sparklines and list_interfaces only read per-interface packet counters
  (dumpcap -S), never packet contents; that sampler runs only while something shows it.

Tests

npm run build
npm test               # unit checks, the sharkd client, the capture file reader, live slices against full reads, the HTTP API, MCP tools and panels
npm run test:browser   # panels and the examples in headless Chrome (skipped without Chrome)
npm run test:examples  # the investigations' bugs and their fixes, over loopback without a capture
npm run test:package   # the npm package installed as users get it, run over MCP
npm run test:live      # live captures on loopback: pings, a local HTTPS server, the investigations; then big generated ones, followed in headless Chrome

The tests run their servers with an empty home folder, so your own Wireshark preferences and
plugins don't change the results. The capture checks in npm test need dumpcap permissions
(see Requirements) and are skipped without them; npm run test:live needs them.

Limitations

• In a big live capture the newest packets stay provisional until the next full read of the file,
  which takes longer the bigger the file gets (about 10 s at a million packets, more with a
  display filter). A ring buffer or a capture filter keeps files small. Provisional packets of a
  TLS connection that carried more than a few requests before (HTTP/2, keep-alive) can't be
  decrypted. Ones of a message that began more than about 16 MiB before them, or that more than
  three requests were pipelined into, read as plain TCP segments, and ones of a message that ends
  more than about 8 MiB after them don't say where it is reassembled (less when many connections
  are busy at once).
• Provisional packets count as settled once no sender with a message or an answer under way has
  sent anything for 10 s of capture time. If one goes on after such a pause (a slow response, a
  stalled download, a late DNS or ping reply), the packets listed before it keep reading as if
  it had ended there (segments don't say where they are reassembled, a request doesn't name its
  answer, and a display filter's provisional matches among them aren't checked again) until the
  next full read. Provisional packets behind more than four VLAN tags or eight MPLS labels, on
  link types other than Ethernet, Linux cooked capture, raw IP and loopback, or inside a tunnel
  (GRE, VXLAN, Geneve, IP in IP, an Ethernet pseudowire) come without the start of their own
  connection unless it is among the 2000 or so packets before them, so until read in full they
  read like a capture begun mid-connection (no window scaling, TLS not decrypted).
• A time reference the display filter hides stays hidden, while Wireshark lists time references
  whatever the filter; the packets after it count from it all the same, and Next/Previous Time
  Reference go to it. "Open in Wireshark" doesn't take the time references along.
• Display filters on frame.time_relative (also Apply as Filter on "Time since reference") count
  from the first packet, not from the time references. In a filter, frame.ref_time stands for
  the references' frame numbers: it works only as a test of its own, not inside a function or
  with # or @, and for a few hundred scattered references at most (about 4 KB of numbers).
• Packet comments added, edited or deleted in the viewer stay there until the capture is closed
  or another one opened, also when a live capture goes on in a new file (ring buffer, new file
  after …; WireBuddy says when that discards edits); only an export to pcapng (File › Save As)
  keeps them, and "Open in Wireshark" opens the file without them. Display filters on
  frame.comment, Expert Information and the agent's query_packets fields read the comments in
  the file: edits reach them once exported and that file opened.
• In the Wireshark window that "Open in Wireshark" starts, the interface list stays empty until
  Capture → Refresh Interfaces (F5): Wireshark skips the scan when it starts with a file.
• A Decode As entry is one TCP, UDP or TLS port or one RTP payload type, at most 50 of them, and
  setting one needs an open capture. A few protocols Wireshark only reaches through another one
  (SSDP, for one) can't be targets; data, not Wireshark's "(none)", stops a decode. An entry wins
  over an extension on the same port, and one for an extension's protocol does nothing while that
  extension is off. "Open in Wireshark" opens the capture without WireBuddy's Decode As entries.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md. Please report
security problems privately as described in SECURITY.md.

License

MIT © 2026 Michael Haar

Wireshark and the "fin" logo are registered trademarks of the Wireshark Foundation. WireBuddy is
an independent project and is not affiliated with or endorsed by the Wireshark Foundation.