A mirror for the wire. A native Mac packet viewer on Wireshark's own dissectors, that draws every packet the way the RFCs do.
A TLS Client Hello, read layer by layer. Every capture in this README is synthetic: loopback and *.kagami.test only.
Download the latest release (0.1.0 beta). It needs macOS 26 on Apple silicon.
Kagami-0.1.0.dmg: drag Kagami to Applications.Kagami-0.1.0.pkg: the Installer, which can also link thekagamicommand into/usr/local/bin.
Each file has a .sig from the release key, and SHA256SUMS lists them all. Kagami is not
notarised, so macOS blocks the first open: choose System Settings > Privacy & Security >
Open Anyway, once. Recording and opening captures need Wireshark; flow files don't.
- Packets the way the RFCs draw them. The Anatomy inspector lays every fixed-format header on a 32-bit ruler, one box per field sized by its bits, the decoded value inside, linked to the bytes in both directions.
- Every protocol Wireshark knows. Kagami runs Wireshark's
tsharkandsharkdas separate programs, so it reads what Wireshark reads; no Wireshark code is linked in. - Flow files in seconds. nfdump, CSV, JSON and Zeek exports open straight into Flows, with no Wireshark needed. A 2.3 GB nfdump text export opens in about 5 seconds, and totals count every record, up to 5 million.
- Keyboard first. ⌘K searches actions, packets and hosts; filters validate as you type; native tabs keep captures side by side.
- A CLI and an MCP server for Claude and other agents. The same core answers as JSON on the command line and through 10 MCP tools. Live capture over MCP stays off until you allow it.
git clone https://github.com/mostlygino/Kagami.git && cd Kagami
open -a Kagami Demo/demo.pcapng # a synthetic capture on loopback (needs Wireshark)
open -a Kagami Demo/demo.netflow.gz # 4,000 synthetic flows, no Wireshark needed
/Applications/Kagami.app/Contents/Helpers/kagami anatomy Demo/demo.pcapng 4Pick packet 43 and read a TLS Client Hello layer by layer, or press ⌘K and type tls.
On first launch Kagami greets you: it checks your setup (Wireshark, the permission to record, GnuPG and nfdump), then opens the demo capture on that same packet. Help > Welcome to Kagami brings it back.
A kagami is a mirror, and in Japan the bronze kind was never just for vanity: it showed things as they are. Kagami does that for network traffic. Capture live or open a capture file, narrow it down, and read one packet the way the RFCs draw it: a 32-bit ruler, every field a box sized by its bits, the real value inside. Underneath is Wireshark's own dissector engine, so every protocol Wireshark understands, Kagami shows. On top is a Mac app: native tables, tabs, Liquid Glass, keyboard first. The same core also answers on the command line and over MCP, so an agent can read a capture as well as you can.
| 3 ways in: app, CLI, MCP |
10 MCP tools |
1 px diagram rules, on device pixels |
41 tests, plus CLI checks |
0 root needed to capture |
Capture, or open a file. Pick an interface on the start screen, where each one shows its live activity, add a BPF capture filter if you like, and press Record (⌘R). No root: Kagami uses Wireshark's ChmodBPF setup. Or open any capture Wireshark reads (pcap, pcapng, snoop, ERF, PacketLogger, gzip, zstd or lz4 compressed) with ⌘O, drag and drop onto the window or the Dock icon, or Finder's Open With. Native tabs (⌘T) keep several captures side by side.
Narrow it down. Wireshark display filters with live validation, a ⌘F filter builder for when you don't remember the field name, quick filters in the sidebar (errors, TCP problems, TLS handshakes, DNS, new connections), protocol and host groups, and Apply as Filter on any field. Filters never touch the capture itself.
Read one packet properly. The Anatomy inspector draws each fixed-format header the way RFC 791 and friends draw it: a 32-bit ruler, one box per field, sized by its bits, with the decoded value inside. Select a field and its bytes light up in the hex view, and the other way round. The Fields tab keeps Wireshark's full protocol tree.
Follow the conversation. Follow TCP or UDP Stream (⇧⌘F) shows the exchange as a ladder, client on one side and server on the other, every payload with its frame number. Click a frame number to find it in the table. Text or hex, search with match count.
Compare and overview. Diff two packets field by field or byte by byte, side by side or unified, and step through only the differences. The Overview draws throughput by protocol, the share of each protocol, TCP health (retransmissions, resets, zero windows), the busiest hosts and service ports. The Endpoints window (⌥⌘E) lists every host and port.
Flows. Open a capture with NetFlow v5, v9 or IPFIX exports and Kagami reads the flow
records themselves: who talked to whom, how much, for how long, with TCP flags. A collector
preset sets up live collection. Flow files open straight into Flows: nfdump nfcapd files or a
folder of them (with brew install nfdump), CSV or TSV with a header (nfdump, pmacct, AWS VPC
flow logs, also gzipped), JSON or JSON lines (goflow2, pmacct, nfdump, Elastic ECS) and Zeek
conn.log, plus nfdump's own text output (-o raw and -o line, such as .netflow files).
Text exports stream with no size cap (a 2.3 GB file opens in about 5 seconds) and a file can
hold up to 5 million records; the table shows the first 100,000 by the current sort, while
totals and top talkers count every record. kagami flows and the MCP list_flows tool read
them too, without Wireshark.
Then drill down. The sidebar lists protocols, sources, destinations, service ports and exporters as filters, and top talkers are clickable. Active filters sit as chips, with Copy nfdump Filter to take the same view to the command line. The flow inspector shows one flow in full plus the whole conversation between its two hosts, with buttons to narrow to a host, that conversation or the port. A sortable Start column puts it all in order. In Flows the toolbar field searches flows (⌘L).
Keep notes. Packet comments (⌘L), highlights to mark what matters, and custom columns for any field you want in the table.
Take exactly what matters. Export all, filtered or selected packets as pcapng or pcap (⇧⌘E).
 Select a field: its box, its value and its bytes, linked. |
 The Overview: what is in this capture, at a glance. |
 Follow Stream as a ladder, with frame numbers you can click. |
 Diff two packets, side by side or unified. |
 Flows: NetFlow, IPFIX and flow files, with the flow inspector. |
 About, with the exact build and commit for bug reports. |
kagami ships inside the app (Kagami.app/Contents/Helpers/kagami). It speaks JSON on stdout
and returns meaningful exit codes, so it fits in scripts and CI.
kagami interfaces
kagami capture -i <interface> [-d <seconds>] [-c <count>] [-f <bpf>] [-w <out.pcapng>]
kagami packets <file> [--filter <display filter>] [--offset N] [--limit N]
kagami packet <file> <frame> [--bytes] [--text]
kagami anatomy <file> <frame> RFC-style header diagrams, as text
kagami follow <file> <stream> [--udp] [--format text|hex|base64]
kagami flows <file>
kagami stats <file> [--filter <display filter>]
kagami export <file> -o <out> [--filter <display filter>] [--pcap]
kagami check <display filter>
kagami mcp MCP server on stdio
kagami anatomy draws the same diagrams as the app, in plain text. This is a real run on the
demo capture:
$ kagami anatomy Demo/demo.pcapng 4
IPv4 (bytes 4–23)
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Ver=4 | IHL=5 | DSCP |ECN| Total Length: 78 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Identification: 0x4003 |R|D|M| Fragment Offset: 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| TTL=64 | Protocol: UDP | Header Checksum: 0x0000 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Address: 127.0.0.1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Destination Address: 127.0.0.1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
kagami mcp serves the same abilities to Claude Code or any MCP client: list interfaces,
capture statistics, list packets, packet detail, packet anatomy, follow a stream, list flows,
check a filter, export packets, and capture. It is careful by default:
- Capture is opt-in. The capture tool only works when you start the server with
KAGAMI_MCP_ALLOW_CAPTURE=1. - Writes stay in one folder. Exports go to
~/Documents/Kagami(orKAGAMI_MCP_OUTPUT_DIR) and never overwrite. - Payloads are marked untrusted. Reassembled stream text is framed as data, not instructions, and every response has a size cap.
claude mcp add kagami -- /Applications/Kagami.app/Contents/Helpers/kagami mcpflowchart LR
W["Wireshark<br/>tshark · sharkd"] --> C["KagamiCore<br/>sessions · anatomy math · stats · diff · flows"]
C --> A["Kagami.app<br/>SwiftUI + AppKit"]
C --> L["kagami<br/>JSON CLI"]
C --> M["kagami mcp<br/>MCP over stdio"]
| Path | What |
|---|---|
Sources/KagamiCore/ |
The engine: a persistent sharkd session (detail, filter checks, byte ranges) with tshark for capture, the RFC anatomy layout, statistics, diff, flows, the process map |
Sources/KagamiApp/ |
The Mac app: packet table on NSTableView, inspector, follow ladder, diff, overview, flows, endpoints, settings, updater |
Sources/KagamiCLI/ |
kagami: the JSON CLI and the MCP server |
Tests/KagamiTests/ |
Swift Testing suite on synthetic fixtures |
scripts/ |
check-cli.sh, install.sh, release.sh, make-demo-capture.sh, make-icon.swift |
Kagami runs Wireshark as a separate program and links none of its code.
Needs: macOS 26 or later, Xcode (SwiftUI macros need the full toolchain), and Wireshark
(/Applications/Wireshark.app, or tshark from Homebrew). Capturing without root needs
Wireshark's ChmodBPF, which its installer offers.
./make-app.sh # builds build/Kagami.app, with the kagami CLI inside
scripts/install.sh # or build and install into /Applications, where updates can reach it
open build/Kagami.appswift test # 41 tests on synthetic captures and flow files
scripts/check-cli.sh # CLI and MCP: exit codes, JSON, protocol errors, write confinementTry it on the demo capture: open -a build/Kagami.app Demo/demo.pcapng.
Kagami updates itself from this repository's GitHub releases, read through GitHub's public
API, and verifies every download against a pinned release key before installing, so GnuPG is
needed for the check (brew install gnupg). While a repository is private it goes through the
gh CLI and its login instead; the app never stores a token. A daily check runs in the background; Kagami > Check for Updates… runs one now.
Releases are cut with scripts/release.sh <version> [--beta] and signed on a YubiKey, which
puts the DMG, the installer package and the zip the updater uses on the release, each with its
signature. 0.1.0 is the first public beta; see the changelog. SECURITY
shows how to verify a download yourself.
Everything happens on this Mac. Kagami sends no telemetry and has no server. Captures you
open stay where they are; nothing leaves unless you export it. The demo capture and the test
fixtures are synthetic (loopback, documentation address ranges, *.kagami.test,
example.com): never commit a real capture.
Bug reports, ideas and pull requests are welcome. CONTRIBUTING covers the build, the tests and how the code is laid out; the code of conduct applies everywhere. Found a security problem? Please report it privately, as SECURITY describes, not in an issue.
Code: AGPL-3.0-or-later (LICENSE). Name, icon and artwork: all rights reserved, see BRAND.md.
- Design: the RFC Header Diagram direction, the protocol colour code, the rules it keeps
- Product: who Kagami is for and what success looks like
- Brand: the Kyōhai icon and its alternates, rendered rather than drawn
If Kagami helps you, a ⭐ helps others find it.
Built on Wireshark, which does every bit of the dissection (GPL v2+, run as a separate program).
Code under AGPL-3.0-or-later; name, icon and artwork reserved. See Licence.
