Kilobat docs

Install

The CLI is free and open source. Install it with Homebrew:

This installs kilobat and kb, a short alias. Every example below works with either.

Or download the Mac app, which also includes the CLI at Kilobat.app/Contents/Helpers/kilobat.

Turn on tab completion for your shell:

# zsh
echo 'source <(kilobat completion zsh)' >> ~/.zshrc
# fish
kilobat completion fish > ~/.config/fish/completions/kilobat.fish

Quick start

Run kilobat on its own for an interactive menu: arrow keys or j/k to move, Enter to open, a number to jump, q to quit.

kilobat status --watch     # live traffic by app; q quit, s sort, f filter, / search
kilobat diagnose           # what is slowing your connection
kilobat speedtest          # speed and latency under load
kilobat profile travel     # switch to the Travel profile
kilobat block com.example.App

Run kilobat <command> --help for help with any command.

Commands

Monitor

Diagnose

Control

Setup

Expert

Scripting and JSON

Output switches to JSON automatically when piped, so scripts never parse the human layout. Pass --json to be explicit.

kilobat diagnose | jq .health            # "good", "degraded", "poor" or "unknown"
kilobat status --watch --json             # one JSON object per line, every second
kilobat report --summary --days 7 --json  # daily totals and top apps

Set NO_COLOR to turn off colors. Changes to DNS require administrator approval.

AI agents and MCP

Give an agent like Claude Code, Codex or Cursor this prompt:

MCP server

kilobat mcp speaks the Model Context Protocol over stdio. Add it to Claude Code:

claude mcp add kilobat -- kilobat mcp

Or add it to any client that reads an mcpServers config:

{ "mcpServers": { "kilobat": { "command": "kilobat", "args": ["mcp"] } } }

Read-only tools: get_status, diagnose_network, scan_wifi, run_speedtest, get_usage_report and list_rules. They return the same JSON as the CLI. Change tools (set_profile, set_app_rule, set_dns) are marked as changes, and their descriptions tell the agent to ask you first.

Mac network troubleshooting skill

The mac-network-troubleshooting skill helps agents investigate slow internet, Wi-Fi drops, latency, DNS, hotspots, data usage and bufferbloat. It interprets Kilobat measurements, explains uncertainty and asks before changing settings.

npx skills add seifip/kilobat-skills

Install the Kilobat CLI separately with the Homebrew command above, or connect its MCP server. The CLI requires macOS 14 or later; the Homebrew source build requires Xcode 16 or later. See the skill on skills.sh or read its source and references.

The Mac app

1. Download the disk image, drag Kilobat into Applications and open it from there.
2. Live traffic, the Wi-Fi picker and speed tests are free. To unlock Pro, start the 14-day trial or paste your license into Settings.
3. Choose your menu-bar items in Settings. Hold Command while dragging a menu-bar item to move it.

Allow Location access when asked so Kilobat can show Wi-Fi names and scan nearby networks. Your location is not sent anywhere.

Blocking and filtering

Monitoring works without filtering. To enforce rules, open filtering setup in Kilobat and approve the extension and content filter when macOS asks. On current macOS, extensions are under System Settings → General → Login Items & Extensions → Network Extensions.

Filtering affects new connections; an existing connection may continue until it reconnects. If a rule interrupts something important, switch to Unrestricted or turn filtering off in Settings.

Privacy

Traffic history, network names and rules stay on your Mac. There is no account and no telemetry. Diagnostics contact test services, and license activation and update checks contact their services. Read the privacy notice.