Give your AI agent
network superpowers.

Diagnose connection failures, inspect traffic and automate Wi-Fi from your terminal or coding agent.

brew install seifip/kilobat/kilobat
Free. No license checks.Telemetry-free CLI.Built for macOS.
● ● ●Network diagnosticszsh

# A host will not connect. Start here.

$ kilobat why api.example.com

# Read the wider network picture.

$ kilobat diagnose | jq .health
"degraded" ← a machine-readable answer

# Watch what your apps are doing.

$ kilobat status --watch

From “why won’t it connect?”
to a repeatable workflow.

Use it directly, pipe structured output into your tools, or let an agent investigate with you. Your network history stays on your Mac. Your workflow stays yours.

Find the failure. Not another guess.

Start with the host that will not load. Diagnose its connection instead of bouncing between browser tabs, Wi-Fi settings and a VPN toggle.

Shell
kilobat why api.example.com
Go deeper ↗

Watch the Mac, app by app.

Keep live per-app traffic and the session budget beside your work. A quiet terminal should not hide a noisy background app.

Shell
kilobat status --watch
Go deeper ↗

Make the next step programmable.

Get structured diagnostics for your own scripts. Keep the output as JSON rather than scraping a human-readable screen.

Shell
kilobat diagnose --json
Go deeper ↗

Let the job finish.

Hold off idle sleep while a command runs. Useful for a long build or test suite without permanently changing your Mac’s sleep settings.

Shell
kilobat awake -- make test
Go deeper ↗

Look back, not just right now.

Read locally recorded usage history. Build your own reporting around the data Kilobat has actually recorded on this Mac.

Shell
kilobat report --json
Go deeper ↗

Give your agent a network toolkit.

Run a local stdio MCP server. Connect your coding agent to network diagnostics, conditions and keep-awake tools.

Shell
kilobat mcp
Go deeper ↗

Keep the signal.
Skip the ceremony.

Save a snapshot for a bug report. Follow a live stream. Keep your build running. These are starting points you can copy, understand and adapt.

Capture the network when it fails.

Save structured diagnostics alongside your debugging notes. Compare files before and after switching networks, then share only the fields your team needs.

Shell
kilobat diagnose --json > network-diagnostic.json

One observation per line.

Stream live status as newline-delimited JSON. Keep the raw stream for later inspection rather than parsing a formatted terminal display.

Shell
kilobat status --watch --json > network-status.jsonl
Control-C stops the stream.

Turn recorded usage into a report.

Export a seven-day summary from locally recorded history. Feed the result into your own analysis, reporting or support workflow.

Shell
kilobat report --summary --days 7 --json > weekly-usage.json

Scope wakefulness to the job.

Wrap your build or test command. The keep-awake assertion belongs to that run, not a permanent change to your sleep settings.

Shell
kilobat awake -- make test

Three commands.
Then make it yours.

A Mac running macOS 14 or later and Homebrew are the starting point. The free CLI installs separately from the desktop app.

Installation and desktop setup ↗
  1. Install the CLI.
    brew install seifip/kilobat/kilobat

    Homebrew installs the command-line toolkit.

  2. Explore the interface.
    kilobat --help

    See the commands supported by your installed version.

  3. Ask your first question.
    kilobat diagnose --json

    Start with diagnostics, then choose the workflow you need.

Same network.
Different interfaces.

The CLI is free. The desktop app adds a persistent visual workspace. MCP brings the diagnostic toolkit into an agent conversation. Pick the interface that fits the task.

Choose your agent and get exact setup instructions ↗
MCP configuration · JSON
{
  "mcpServers": {
    "kilobat": {
      "command": "kilobat",
      "args": [
        "mcp"
      ]
    }
  }
}

Tools that change settings are marked destructive and instruct the agent to ask first.

A toolkit, not a one-liner.

Search by task or choose a command family. Brackets describe optional arguments; use kilobat --help for help in your installed version.

Browse the complete toolkitFull reference ↗
Monitorkilobat status [--watch] [--json]

Live per-app traffic and session budget; a JSON snapshot, or a JSON-lines stream with --watch

Monitorkilobat report [--csv|--json] [--summary] [--days 1…365]

Locally recorded usage history, or daily totals and top apps; CSV has one row per app

Monitorkilobat report compare --total 40GB [--unit GB|GiB] [--direction both|download|upload] (--from DATE --to DATE | --period last-month) [--network NAME] [--json|--csv]

A router's or provider's figure beside what Kilobat recorded on this Mac for the same period, in the same unit, with the hours recorded, every gap and likely reasons for a difference

Monitorkilobat health-history [--hours 1…720] [--json]

Router, internet, jitter and DNS checks the app recorded over time

Monitorkilobat proxy [routes [--app name] | test] [--json]

Proxy apps, the system proxy and their problems; which rule and node each app took; how fast each node answers

Monitorkilobat vpn [--json]

The VPN, whether DNS or IPv6 skip it, and the VPN kill switch's state

Monitorkilobat vpn leaks [--json]

Leak test: whether DNS, IPv6 or UDP (what WebRTC uses) goes around the VPN, each with the setting that fixes it; asks bash.ws, Cloudflare and a STUN server

Monitorkilobat calls [--limit 1…200] [--json]

After each call: how many times it froze and what caused it, from the reports the app writes

Monitorkilobat remote [--limit 1…200] [--kind ssh|mosh|desktop] [--json]

After each SSH, Mosh or remote desktop session: why typing lagged or the screen froze, and when Mosh would help

Monitorkilobat stream [status|check|reports] [--json]

OBS over its local WebSocket: whether it is live and dropping frames, a go-live check of your upload against its bitrate plus 30% (check [--bitrate ] [--measure|--no-measure]), and the reports after each stream (reports [--limit 1…200])

Monitorkilobat cloud-gaming [status|reports] [--limit 1…200] [--json]

GeForce NOW, Xbox Cloud Gaming, Boosteroid, Amazon Luna and Shadow: the session now (ping, jitter, loss, bitrate, data, what is in the way) and the report after each, with when it stuttered and why

Monitorkilobat overlay [--port 7171] [--target internet|router|cs2:fra|host]

A live ping overlay for OBS and other streaming apps, served on localhost until Ctrl-C; a game region such as cs2:fra pings that data center

Monitorkilobat support-report [--hours 1…168] [--host h] [--include-sites] [--markdown|--html] [--output f]

A report for your provider or IT desk: findings, latency, outages and speed tests, without your network’s name or local addresses

Monitorkilobat plan [--days 7…90] [--json]

Speed tests against the plan you pay for on each network: the median, evenings beside the rest of the day, and how often a test got under half

Monitorkilobat credit [--provider id] [--price n] [--month this|last|YYYY-MM] [--draft] [--json]

The month’s outages beyond your router against your provider’s published credit rule, what they may qualify for, and a drafted claim; credit providers lists the rules

Monitorkilobat week [--weeks-ago 0…12] [--json]

The weekly digest: last week’s most notable outages, frozen calls, router, blocks and metered data, compared with the week before

Monitorkilobat router [--all] [--json]

Router check-up: its usual replies, loss and drops against the last three days, restarts and whether they helped, from the checks the app keeps

Monitorkilobat router connect [fritzbox|unifi|mikrotik|openwrt] [--json]

Setup steps for the app’s Pro router connection; never takes credentials on the command line

Monitorkilobat router devices [--json]

The connected router’s clients, measured rates and today’s totals through the app; FRITZ!Box and other whole-home counters never imply a single device’s share; client counters may include LAN traffic

Monitorkilobat router disconnect [--json]

Forget the router for this network; the app removes its Keychain credential, or does so on its next start

Monitorkilobat service-speed [--all] [--test <service>] [--list] [--json]

Your own downloads from GitHub, iCloud, Steam, npm and more against the line, and when your provider’s route to one is slow; --test downloads up to 25 MB from one now

Monitorkilobat hotspot [--all] [--carrier <id>] [--detect] [--json]

On a phone hotspot: whether every download stops at a carrier’s hotspot cap, the measurements behind it and the carrier’s published rules; hotspot carriers lists them

Monitorkilobat networks [forget <name>]

Networks seen, with the profile, budget and data cost remembered for each

Monitorkilobat networks cost <metered|unmetered|automatic> [name]

Treat this network, or a named one, as metered or unmetered, or follow macOS again

Monitorkilobat bandwidth [app] [hour|day|week|month] [--back N] [--json]

One app's sent and received bytes over an hour, day, week or month, with the peak; --back steps to earlier periods

Monitorkilobat access-policy <bundle-id> [--json]

The connections an app's developer declares in its Internet Access Policy, and why

Diagnosekilobat diagnose [--json]

Wi-Fi, router, internet, DNS and captive-portal checks with advice

Diagnosekilobat radar [--watch] [--json]

Signal score and best-spot finder

Diagnosekilobat scan [--json]

Nearby networks, channels, widths and security

Diagnosekilobat channels [--json]

Congestion per channel and the least crowded one

Diagnosekilobat speedtest [--json] [--budget-mb 1…80] [--parallel]

Cloudflare speed, loaded latency and call and streaming verdicts, 80 MB at most. One connection by default; --parallel opens four, as most speed-test sites do

Diagnosekilobat speed-compare [<test> <test>] [--json]

What differed between two saved speed tests: network, time, server, connections, Wi-Fi band and signal, VPN, other traffic

Diagnosekilobat ip [--public] [--json]

Where traffic leaves: the interface and any VPN, read on this Mac; --public also asks Cloudflare for your public IP and its registry country

Diagnosekilobat portal [open] [--json]

Wi-Fi sign-in pages: a check now (open, sign-in page or offline, with the page’s address, query values redacted), whether this network wants a sign-in, logged you out or how long is left, and each network’s usual sign-in length; open opens the page in your browser

Diagnosekilobat stutter [--seconds 10…60] [--target router|internet|<host>] [--json]

Ping every 50 ms to find the short latency spikes speed tests miss, when they happen and whether they repeat

Diagnosekilobat starlink [--hours 1…720] [--json]

A Starlink dish on this network, read from it locally: state, ground-station ping, alerts, the sky map and which way it’s blocked, and outages split into your setup, Starlink’s network and dish restarts

Diagnosekilobat games [--game <game> | --all | --match] [--json]

List the games Kilobat pings and the ones it can't, with why; with --game, ping each of that game's data centers (Valve relays, Epic ping servers, or the AWS and Azure regions it hosts in) five times and name the one closest to you; with --match, find and ping the server of the match you're playing, for any game, ready for the streaming overlay

Diagnosekilobat airdrop [status|everyone|contacts|off] [--json]

AirDrop visibility, the AirDrop link (AWDL) and what uses it; changing visibility opens System Settings

Diagnosekilobat bluetooth [--json]

Bluetooth devices and whether they share 2.4 GHz with your Wi-Fi

Diagnosekilobat bluetooth audio [--json]

While AirPods or other Bluetooth headphones play: what can make them crackle (2.4 GHz, AirDrop, a big download, a weak signal) and what to change, in order

Diagnosekilobat wired [--json]

Ethernet ports and adapters: negotiated speed and duplex, the fastest each can do, maker, chip, driver, USB link and network service, and what is wrong

Diagnosekilobat shares [--json]

Mounted SMB, AFP, NFS and WebDAV shares and whether each server answers on its port; never opens a share

Diagnosekilobat wakes [--days 1…30] [--json]

After each wake: how long the link, the address, DNS and the first web request took, and whether a VPN passed web traffic

Diagnosekilobat macos [--json]

Recent macOS versions, and this network's speed, latency, DNS, loss and drops before and after the last upgrade

Diagnosekilobat local [check] [--quick] [--json]

Can I cast or print here? The Chromecasts, AirPlay receivers and printers that answer, whether the network may keep devices apart (never confirmed from discovery alone), a printer's or camera's own Wi-Fi, and what makes a cast stutter

Diagnosekilobat dns [automatic|cloudflare|google|quad9|flush]

Read or set DNS, or flush the cache

Diagnosekilobat dns fastest [--all] [--json]

The fastest DNS on this network, from the app’s quiet runs against Cloudflare, Quad9 and Google, with who runs each and where, and its answered lookups over 14 days

Diagnosekilobat dns auto on|off [--network <name>]

Pro: switch to the fastest DNS on joining, everywhere or on one network

Diagnosekilobat dns exclude|include <resolver>

Never time or pick a resolver, or add your own by IP address

Diagnosekilobat dns fallback <resolver>|off

The resolver to move to when the fastest fails, before your network’s own

Wi-Fikilobat wifi [status]

Current network, signal, channel and width, link rate, Wi-Fi standard, security, transmit power and whether the router sees a private Wi-Fi address

Wi-Fikilobat wifi on|off|restart|disconnect

Control Wi-Fi power and the connection

Wi-Fikilobat wifi join <name> [--password-stdin]

Join a saved network, or a new one

Wi-Fikilobat wifi known

Saved networks in order of preference

Wi-Fikilobat wifi password|share <name>

Show a saved password, or a QR code to scan with a phone

Wi-Fikilobat wifi nodes [name <node> <name>] [--json]

Mesh nodes or access points of this network, which one the Mac is on, and whether a much closer one is in range; name one, such as Office

Wi-Fikilobat wifi roams [--hours 1…336] [--csv|--text] [--json]

Each access point the Mac stayed on: how long, the signal when it left, stays under a minute and better access points it ignored; --csv or --text exports them for an IT desk

Wi-Fikilobat wifi reconnect [--json]

Move to the closer node, then say where the Mac ended up

Wi-Fikilobat low-latency on [--for 15m|1h|2h] [--until-quit <app>]

Pause AirDrop and AWDL during calls and games: 15 minutes by default, up to 4 hours, or until an app quits

Wi-Fikilobat low-latency off

Restore AirDrop and AWDL, also for a pause started in the app

Awake & agentskilobat awake [--display]

Keep the Mac awake until Ctrl-C; closing the lid still sleeps it unless you add --lid-closed

Awake & agentskilobat awake --lid-closed [--for 2h|--until-quiet|-- <command>]

Keep running with the lid closed too, 8 hours at most, through the app’s power helper; needs Allow running with the lid closed in Settings

Awake & agentskilobat awake --for 90m|2h|45s

Stay awake for a while

Awake & agentskilobat awake --until-quiet [--app <id>] [--quiet 1…60]

Stay awake until downloads or one app go quiet, below 16 KB/s for 3 minutes by default

Awake & agentskilobat awake -- <command> [args]

Stay awake while a command runs, then report the data its processes moved and exit with its status

Awake & agentskilobat awake --while-frontmost <app> [--display] [--for 2h]

Stay awake only while that app is in front, for reading or presenting. Switching away lets the Mac sleep; it ends when the app quits, at 20% battery or after --for. --display keeps the screen on too

Awake & agentskilobat settings awake-on-power on|off

The app stays awake whenever the power adapter is in and lets the Mac sleep again when it comes out

Awake & agentskilobat settings keep-screen-on on|off

Keep the screen on too for everything the app keeps awake: timers, downloads, agents, the app in front and plugged in

Awake & agentskilobat sessions [--days N] [--json]

Awake sessions and AI agent runs the app recorded, with data used and network changes

Awake & agentskilobat agent-log [--all] [--since 2h|3d|date] [--agent claude] [--flagged] [--json]

Every host an AI agent and the commands it started contacted, with bytes and flags: the latest session, or the agent's own when run from it. Recorded by the app with Pro

Awake & agentskilobat history forget <host> [--subdomains] [--json]

Remove a host from blocked attempts, the agent network log, agent-run destinations and Protection notification memory

Awake & agentskilobat history clear --hour|--today|--all [--json]

Clear those host histories for the last hour, since midnight or entirely; future activity can be recorded again

Awake & agentskilobat agent-log --watch [--agent claude] [--flagged] [--json]

Records the same live in this terminal, without the app; nothing is saved

Awake & agentskilobat protect [status|on|off|update] [--threats|--trackers|--agents] [--json]

Protection: block known malware, phishing and scam hosts (Pro), trackers in apps (free, off by default) and the agent guard (Pro); update downloads the lists now

Awake & agentskilobat protect check <host> [--json]

Whether a host is on a threat or tracker list, which one, and whether Kilobat blocks it; exits 1 if it does

Awake & agentskilobat protect allow|unallow <host>

Let a site and its subdomains past every Protection list, or undo it

Awake & agentskilobat agent-event <start|working|waiting|done|failed> [--agent name] [--stdin-json|--json-arg]

For an agent's hooks: tells the app a run started, waits for you or is done. Silent, always exits 0

Awake & agentskilobat why <url|host> [--app <id>] [--proxy <url>] [--context container|vm|remote|provider] [--failed-at <time>] [--error <text>] [--json]

Find the layer that stops a connection: network and interface, proxy and the app's own proxy, DNS, Kilobat rules, IPv4 and IPv6, TLS, the server and each redirect, and whether this network blocks it or the service refuses your region, other software in the path as suspects to test, and a blocked Local Network permission with --error "No route to host". Requests the exact URL; output hides query values. Also kilobat doctor

Awake & agentskilobat path [--json]

Other software in the network path: content filters, DNS proxies, VPNs, encrypted DNS and security agents, Kilobat's own filter included; a recent macOS update; and who answers DNS, per-domain resolvers and Private Relay traffic included

Awake & agentskilobat down [service|host…] [--all] [--list] [--json]

Is it them or me? What the public status pages of Slack, Zoom, GitHub, Claude, OpenAI and about seventy other services report now, and whether each connects from here: blocked on this network, or not available in your region; with no service, those of the apps running on this Mac

Awake & agentskilobat explain <process|host…> [--process name --host name] [--json]

What a macOS process or host is, how much traffic is normal, whether blocking it is safe and what breaks, from Kilobat's own database on this Mac. The facts Kilobat has for anything it doesn't know

Awake & agentskilobat conditions [--json]

Metered, Low Data Mode, VPN, latency, battery and heat, whether the lid may close, with advice for long runs

Controlkilobat profile [essentials|work|unrestricted|<your profile>]

List or select a profile, including ones you added

Controlkilobat allow|block <bundle-id> [--minutes 1…1440] [--profile name]

Save an app rule, optionally temporary or for another profile

Controlkilobat reset <bundle-id> [--profile name]

Remove an app's rule so it follows the default

Controlkilobat rules [--profile name] [--json]

A profile’s rules

Controlkilobat limit [GB] [--cycle session|daily|weekly|monthly] [--reset-day N] [--alert 50,80,100]

Read or set this network’s data budget, when it starts over and when it notifies

Controlkilobat quota <bundle-id> <GB> [--upload] [--all-networks]

Limit one app’s data per budget cycle; quota --remove takes it off

Controlkilobat quota --list [--json]

App quotas with what each used this cycle

Controlkilobat pack [status] [--json]

Data packs such as a travel eSIM, with what is left and the day each runs out at the last three days’ pace

Controlkilobat pack add <GB> <days|YYYY-MM-DD> [--network <name>] [--name <label>] [--start YYYY-MM-DD]

Add a data pack on this network, on networks Kilobat has seen, or on any network whose name contains some text

Controlkilobat pack correct <GB-left> [--pack <name>]

Set what the carrier’s app says is left, since Kilobat counts this Mac only

Controlkilobat pack end [--pack <name>]

End a data pack now; it stays in the history

Controlkilobat updaters [--json]

Updaters paused on metered networks, the update bytes that still got through on this network, and the apps that update from inside themselves

Controlkilobat updaters on|off

Pause updater helpers such as Google Updater and macOS Software Update while the network is metered (on by default); the apps keep working

Controlkilobat settings kill-switch on|off

Pro: block new connections whenever the VPN is down; kill-switch-lan on|off keeps the local network reachable meanwhile

Controlkilobat uploads [--json]

Apps uploading a lot right now, with the rate, what they sent so far and the time left when the total is known, and the uploads held for later

Controlkilobat uploads hold <app> [--until unmetered|fast|fast:<Mbps>|2h|manual]

Hold an app’s upload until an unmetered or faster network, for a while, or until you resume it (Pro); uploads resume lets it go

Controlkilobat settings [name [value]]

Read or change settings such as new-apps (allow, ask or block), apple-software, auto-travel, pause-updaters, kill-switch, awake-on-power, public-ip (off by default), speed-streams, alerts and menu-bar

Controlkilobat verdict <host> [--app <id>] [--port N] [--incoming] [--json]

Why Kilobat allows or blocks a connection: every rule that matches, in the order the filter checks them, the one that decides and the command that changes each; verdict --app for an app's own rules

Controlkilobat verdict --blocked [1…50] [--json]

The rules behind the latest blocked attempts, as the filter recorded them when it blocked

Controlkilobat approvals [--json]

Apps waiting for approval while new apps are asked about, with signer and destinations

Controlkilobat approve|deny <app-id> [--minutes 1…1440]

Block a waiting app at once, or ask the person to confirm allowing it in Kilobat

Controlkilobat block-host|unblock-host <domain|IP|CIDR> [--app <id>]

Block a domain (subdomains included, *.example.com accepted), an IP or a range for every app, or for one app

Controlkilobat quit <PID> [--force]

Quit a process

Setupkilobat open

Open the Mac app

Setupkilobat doctor

Check the app, network filter and monitoring

Setupkilobat completion [zsh|bash|fish]

Print a shell completion script

Setupkilobat mcp

Run the MCP server for AI agents over stdio

Setupkilobat update

Update a Homebrew install

Expertkilobat destinations [--pid PID] [--json]

Observed process sockets

Expertkilobat devices [--all] [--bonjour] [--json]

Devices on your network, each new, known, unknown or ignored, with its type and how sure Kilobat is; --all adds ones that aren’t here now

Expertkilobat devices name <MAC> <name>

Name a device

Expertkilobat devices mark <MAC> mine|unknown|ignored

Answer for a new device, as the app’s alert does

Expertkilobat devices type <MAC> <type>|auto

Set a device’s type (camera, doorbell, tv, speaker, printer, plug, hub, console, phone, computer, drone, router, nas…); auto goes back to Kilobat’s reading

Expertkilobat household [--json]

Macs paired in the app and what each moves now; pairing stays in the app

Expertkilobat smarthome [--json]

Thread networks and border routers, Matter and HomeKit devices, and whether the network is ready for Matter; read-only

Expertkilobat trace <host> [--rounds 2…10] [--protocol udp|icmp] [--max-hops N] [--size N] [--json]

Route probe up to 30 hops, stopping after five silent hops; --rounds traces several times and shows each hop’s loss and delay; --protocol icmp gets answers where UDP is ignored

Expertkilobat trace <host> --watch [--interval 5s] [--for 15m] [--alert] [--json|--csv]

Re-traces every 1–60 s for up to 4 h, one probe a hop like mtr; stops when the Mac sleeps or the network changes; --alert beeps on sustained loss or delay at the destination; Ctrl-C stops early

Expertkilobat route-history --host <host> [--json]

Every saved trace and watch to a host, hop by hop like mtr: loss, best, average, worst, route changes and where delay starts

Expertkilobat route-history --watches | --watch <id> [--json|--csv]

Watched routes, or one watch with its hop table, destination and route changes, or every sample as CSV

Expertkilobat http-check <URL> [--json]

DNS, connect, TLS and first-byte timing

Expertkilobat dns-benchmark

Resolver timings

Expertkilobat lan-test <server> [--reverse] [--json]

Five-second iperf3 test to a device running iperf3 -s; needs iperf3, which Kilobat never installs

Expertkilobat interfaces [--json]

Physical and VPN counters, separately

Expertkilobat capture <interface> <file.pcap>

Bounded packet capture

Expertkilobat connection-rule allow|block <app> <host> [port]

Save a destination rule

Expertkilobat blocklist status|import <path>|clear

Manage a domain blocklist

Expertkilobat wake <MAC-address>

Send a Wake-on-LAN packet

Expertkilobat spots [save <name>|remove <id>]

Saved Wi-Fi spots

Expertkilobat outages / speed-history [--days N]

Recorded outages and speed tests as JSON

Local history. Explicit actions.

Network history stays on this Mac. The public CLI has no telemetry or license checks. Diagnostics contact test endpoints where needed; a speed test measures your connection by transferring data.

Know what needs the app.

Install the desktop app to record usage over time. Historical reports read that local data; protected network controls use the app’s permissions and feature access.

Open the hood.

Inspect the source, read the reference, and build your own integration. For agent-readable documentation, use the full Markdown reference.

Read llms-full.txt ↗

What is your network
actually doing?

brew install seifip/kilobat/kilobat