---
title: "Kilobat in Gemini CLI: settings.json MCP server, skills and hooks | Kilobat"
url: "https://kilobat.app/agents/gemini-cli.html"
description: "Connect Kilobat's MCP server to Gemini CLI with gemini mcp add or ~/.gemini/settings.json, add the agent skills, and send run states to Kilobat with hooks."
---

Agent setup

# Set up Kilobat in Gemini CLI

Gemini CLI can diagnose the Mac's network, scan Wi-Fi and keep the Mac awake while it works. Its hooks tell Kilobat which run is working and which waits for you.

Free CLI and MCP server · macOS 14 or later · Checked: 30 October 2026

## Install the CLI

The Kilobat CLI is free and open source, and it includes the MCP server. Install it with Homebrew:

```
brew install seifip/kilobat/kilobat
```

Check it with `kilobat --version`. `kilobat doctor` says whether the Kilobat app is running, its network filter is on and Pro is active; the tools work without the app, which adds Wi-Fi names, history and rule enforcement. The CLI needs macOS 14 or later.

## Connect the MCP server

1. Add the server for your user. Without `-s user` it goes in the current project's `.gemini/settings.json`.

   ```
   gemini mcp add -s user kilobat kilobat mcp
   ```
2. Or add it to `~/.gemini/settings.json` yourself:

   ```
   {
     "mcpServers": {
       "kilobat": {
         "command": "kilobat",
         "args": [
           "mcp"
         ],
         "timeout": 120000
       }
     }
   }
   ```
3. Run `gemini mcp list`. In a folder you haven't trusted, stdio servers show as disconnected until you run `gemini trust`.

The Gemini CLI site says Antigravity CLI replaced it in June 2026, and Antigravity CLI keeps MCP servers in a config of its own. The setup and hooks on this page are for Gemini CLI.

## Add the skills

Nine Agent Skills teach the agent to read Kilobat's measurements and to ask before changing settings. Install them for all your projects with [skills.sh](https://skills.sh/seifip/kilobat-skills):

```
npx skills add seifip/kilobat-skills -g -a gemini-cli
```

This puts them in `~/.gemini/skills/`. Leave out `-g` to install them for the current project only, or leave out both flags to pick agents from a list.

The `kilobat` skill is the entry point: it holds the setup and safety rules and sends the agent to the skill that fits, such as `mac-network-troubleshooting` or `mac-agent-runs`. See [all nine skills](https://kilobat.app/docs.html#network-troubleshooting-skill).

## Try these prompts

Ask in plain words. The agent picks the tools; these are the ones each request usually needs.

| Ask | MCP tools |
|---|---|
| The internet feels slow. Find out why and tell me what to fix first. | `diagnose_network`, `get_status` |
| The Wi-Fi is weak in this room. Is the channel crowded, and which one should the router use? | `get_wifi`, `scan_wifi`, `suggest_wifi_channel` |
| npm install hangs on registry.npmjs.org. Find the layer that fails. | `diagnose_connection` |
| Keep the Mac awake for the next two hours while you run the full test suite, then release it. | `keep_awake`, `release_awake` |
| Did my agent runs today finish, or did one stall or lose the network? | `list_sessions` |
| Run a 10 MB speed test and say whether a video call will hold up. | `run_speedtest` |

## What Gemini CLI can and can't change

Kilobat's MCP server marks every tool as read-only or as a change, and each change tool's description tells the agent to get your confirmation first. The [kilobat skill](https://github.com/seifip/kilobat-skills/tree/main/skills/kilobat) holds the same rule: read freely, ask before changing.

### Runs without asking

- Measure Wi-Fi, router, internet and DNS latency, and per-app traffic: `diagnose_network`, `get_status`, `get_wifi`, `scan_wifi`.
- Find the layer that stops one host, trace a route and compare resolvers: `diagnose_connection`, `trace_route`, `benchmark_dns`.
- Read history, sessions, rules and approvals: `get_usage_report`, `list_sessions`, `list_rules`, `list_approvals`.
- Ping for latency spikes with `run_stutter_test`, which sends pings only.

### Asks you first

- A speed test, which uses up to 80 MB (`run_speedtest`; on a metered network, 10 MB or less), and a five-second LAN test (`run_lan_test`).
- Looking up your public IP with Cloudflare (`get_exit_path` with `public_ip`).
- Profiles, app rules, blocked hosts, the new-app mode, budgets, quotas, a network's data cost and pausing updaters (`set_profile`, `set_app_rule`, `block_destination`, `set_new_app_mode`, `set_budget`, `set_app_quota`, `set_network_cost`, `set_updater_pause`).
- DNS, which macOS also guards with an administrator password prompt (`set_dns`).
- Keeping the Mac running with the lid closed, every time (`keep_awake` with `lid_closed`). A plain `keep_awake` changes no settings and ends when it expires.

### Can't do

- Let a waiting app connect on its own: `decide_approval` can block at once, but allowing opens Kilobat's approval window for you to confirm.
- Change AirDrop visibility: `set_airdrop_visibility` opens System Settings for you.
- Change sleep settings, another app's settings, or anything outside Kilobat. It never reads prompts or replies.
- Enforce rules without the Kilobat app and its network filter (Pro). Without them, rules are saved, not applied, and the agent should say so.

Leave `trust` off, as it is by default, so Gemini CLI confirms each Kilobat tool call.

If the agent can also run shell commands, the `kilobat` CLI can do what the MCP tools do. The skills tell it which commands to run freely and which to ask about.

## Track agent runs

Add these to `~/.gemini/settings.json`, merged with any hooks you already have. Gemini CLI runs as `node`, so Kilobat can't tie its traffic to the run, but the state comes through.

```
{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent gemini --stdin-json" }] }],
    "BeforeAgent": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent gemini --stdin-json" }] }],
    "Notification": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent gemini --stdin-json" }] }],
    "AfterAgent": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent gemini --stdin-json" }] }]
  }
}
```

## Sources

- [Gemini CLI docs: MCP servers](https://geminicli.com/docs/tools/mcp-server/)
- [Kilobat docs: AI agents and MCP](https://kilobat.app/docs.html#agents)
- [skills.sh: supported agents and their skill folders](https://github.com/vercel-labs/skills/blob/main/docs/agents.md)

Checked on 30 October 2026. Agents change their settings often; if a step no longer matches, tell us at the support address.

## Other agents

- [Claude Code](https://kilobat.app/agents/claude-code.html): Give Claude Code your Mac's network as tools: per-app traffic, Wi-Fi, DNS, why a host fails and keep-awake.
- [Codex CLI](https://kilobat.app/agents/codex.html): Codex can check the network before a big download, find why its own request hangs and keep the Mac awake for a long task.
- [Cursor](https://kilobat.app/agents/cursor.html): Let Cursor's agent see why a package download hangs, which app is using the connection and whether the network is metered before a big pull.
- [Claude Desktop](https://kilobat.app/agents/claude-desktop.html): Ask Claude why the Wi-Fi is slow, what used your hotspot data or whether your VPN carries everything, and it reads the answer from your Mac.
- [Windsurf](https://kilobat.app/agents/windsurf.html): Cascade can find why a dependency won't download, check DNS and trace a route from your Mac, with Kilobat's MCP server.
- [Cline](https://kilobat.app/agents/cline.html): Cline can check the Mac's network and keep it awake while it works.
- [Zed](https://kilobat.app/agents/zed.html): Zed's agent can measure the Mac's network, trace a route and compare DNS resolvers through Kilobat's MCP server.
- [Any MCP client](https://kilobat.app/agents/mcp-client.html): Kilobat's MCP server is a local stdio command, kilobat mcp.