AI 에이전트 및 MCP

Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop, Windsurf, Cline, Zed, Hermes Agent, OpenClaw, OpenCode, GitHub Copilot CLI 및 모든 MCP 클라이언트의 단계별 설정 방법은 AI 에이전트에 Kilobat 설정하기에 있습니다.

Claude Code, Codex 또는 Cursor 같은 에이전트에 이 프롬프트를 전달하세요:

MCP 서버

kilobat mcp은 stdio를 통해 Model Context Protocol을 사용합니다. Claude Code에 추가합니다.

claude mcp add kilobat -- kilobat mcp

또는 mcpServers 설정을 읽는 클라이언트에 추가합니다:

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

읽기 전용 도구: get_status, diagnose_network, diagnose_connection, get_conditions, get_updaters, get_uploads, get_data_pack, get_wifi, scan_wifi, suggest_wifi_channel, get_usage_report, compare_usage, get_app_bandwidth, get_access_policy, get_network_history, list_sessions, agent_network_log(에이전트와 그 명령이 접속한 모든 호스트), benchmark_dns, check_url, list_connections, list_devices, trace_route, get_route_history, compare_speed_tests, get_exit_path(에이전트가 public_ip를 전달할 때만 Cloudflare에 공인 IP를 묻습니다), check_vpn_leaks(외부 서비스에 요청하는 누출 테스트), list_networks, get_fastest_dns(앱의 조용한 실행에서 얻은 네트워크별 가장 빠른 DNS), list_rules, list_approvals, list_blocked_connections, explain_verdict(호스트나 앱에 일치하는 모든 규칙과 최종 결정 규칙), check_host_reputation(호스트가 악성코드, 피싱, 사기 또는 추적기 목록에 있는지 이 Mac에서 확인), get_protection_status, run_stutter_test, get_game_ping(핑만 전송), get_nearby_radios, get_captive_portal(kilobat portal --json와 같은 Wi-Fi 로그인 페이지), service_status(지정한 서비스 또는 실행 중인 앱의 공개 상태 페이지 확인), create_support_report(에이전트가 전달하는 통신사용 보고서). CLI와 같은 JSON을 반환합니다. run_speedtest는 데이터를 사용하고, run_lan_test은 로컬 네트워크에서 5초간 데이터를 전송하며 먼저 묻습니다. keep_awake와 release_awake는 설정을 바꾸지 않고 정해진 시간 동안 유휴 잠자기를 막습니다. lid_closed을 사용한 keep_awake은 허용한 후 덮개를 닫은 상태에서도 Mac을 실행 상태로 유지하며 먼저 묻습니다. 변경 도구(set_profile, set_app_rule, set_new_app_mode, decide_approval, block_destination, set_budget, set_data_pack, set_app_quota, set_network_cost, set_updater_pause, set_kill_switch, 요청을 처리하기 위해 보호 기능을 끄지 말라고도 에이전트에 알리는 set_protection, 다른 앱의 업로드를 보류하는 hold_upload, 캐시도 비우는 set_dns, set_fastest_dns, set_dns_fallback, AirDrop 설정을 여는 set_airdrop_visibility)는 변경으로 표시되며 설명에서 먼저 사용자에게 묻도록 안내합니다.

에이전트 연결

연동하지 않으면 Kilobat은 에이전트의 트래픽과 CPU 사용량을 기준으로 판단하므로 조용한 에이전트가 완료된 것인지 입력을 기다리는 것인지 알기 어렵습니다. 훅을 연결하면 실행이 속한 프로젝트와 입력 대기 및 완료 시점을 Kilobat에 알립니다. 각 훅은 kilobat agent-event를 실행하며, 이 명령은 아무것도 출력하지 않고 즉시 0으로 종료하므로 에이전트 작동을 방해하지 않습니다. 앱이 실행 중이 아니면 이벤트는 작은 파일에 대기했다가 앱을 열 때 읽힙니다. Kilobat은 세션 ID, 폴더, 짧은 상태 텍스트만 읽고 프롬프트나 응답은 읽지 않습니다. 기존 훅이 있다면 이 설정을 병합하세요.

~/.claude/settings.json의 Claude Code. 각 훅은 세션 ID와 폴더가 담긴 JSON을 표준 입력으로 받고, --stdin-json가 이를 읽습니다. 권한 또는 입력 요청은 대기 중을, Stop은 백그라운드 작업이 끝나면 완료됨을 뜻합니다. 속도 제한에 걸리면 제한이 초기화될 때까지 대기합니다.

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "Notification": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "StopFailure": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }]
  }
}

Codex에서 가장 간단한 방법: ~/.codex/config.toml의 notify. Codex는 매 턴 후 JSON 인수를 전달하고 --json-arg가 이를 읽습니다. 완료 상태만 알리며 Codex는 notify 프로그램 하나를 실행합니다.

notify = ["kilobat", "agent-event", "done", "--agent", "codex", "--json-arg"]

대기 상태도 확인하려면 대신 ~/.codex/hooks.json의 Codex 후크를 사용하고 /hooks로 신뢰를 설정하세요:

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent codex --stdin-json" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent codex --stdin-json" }] }],
    "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent codex --stdin-json" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent codex --stdin-json" }] }]
  }
}

Gemini CLI, 위치: ~/.gemini/settings.json. Gemini CLI는 node(으)로 실행되므로 Kilobat이 트래픽을 실행과 연결할 수는 없지만 상태는 전달됩니다.

{
  "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" }] }]
  }
}

Cline (CLI, SDK 및 Kanban): Kilobat 플러그인을 설치하면 Cline의 플러그인 저장소에 파일 하나가 추가되며 다른 설정은 변경되지 않습니다. cline plugin uninstall kilobat으로 제거합니다.

cline plugin install https://kilobat.app/agents/cline/kilobat.ts

Cline이 열려 있는 동안 실행이 작업 중인지, 완료 또는 실패했는지, 취소되었는지, Cline 자체 재시도를 모두 마친 후 요청 제한에 걸렸는지, 질문에 대한 입력을 기다리는지 알려줍니다. 하위 에이전트와 팀원의 작업도 끝나야 실행이 완료된 것으로 표시합니다. Cline의 승인 요청은 플러그인에 보이지 않으므로 트래픽과 CPU 감지로 보완합니다.

다른 에이전트도 자체 훅에서 kilobat agent-event start|working|waiting|done|failed --agent <name> --session <id> --cwd <folder>을(를) 호출할 수 있습니다. 직접 테스트할 때 --verbose을(를) 추가하면 처리 결과를 확인할 수 있습니다.

에이전트 네트워크 기록

Claude Code, Codex, Cursor, Gemini CLI, Aider, Windsurf, Claude Desktop, ChatGPT 또는 다른 에이전트가 실행되는 동안 Kilobat은 에이전트와 그 프로세스가 시작한 프로세스가 연결한 모든 호스트를 기록합니다. npm, pip, uv, curl, git, brew, MCP 서버와 그 사이에 셸이 있는 경우도 포함됩니다. 에이전트 프로세스가 시작된 때부터 에이전트와 에이전트가 시작한 모든 프로세스가 종료될 때까지의 각 세션에는 연결한 프로세스별 호스트가 전송량이 많은 순서로 표시되며 포트와 프로토콜, 최초 및 최근 확인 시각, 송수신 바이트, 연결 횟수 및 에이전트가 실행된 프로젝트 폴더가 포함됩니다. 기록 › 에이전트 네트워크 로그에서 볼 수 있으며 에이전트 실행 중 메뉴에는 “Claude Code · 호스트 14개 · 업로드 2.1MB”처럼 한 줄이 표시됩니다. Markdown으로 복사하면 이슈나 검토에 사용할 세션 표가 클립보드에 복사됩니다.

표시는 다시 살펴볼 대상을 알려줄 뿐 문제가 있다는 뜻은 아닙니다. 처음 연결(이 Mac의 어떤 에이전트도 해당 호스트에 접속한 적이 없음. registry.npmjs.org, pypi.org, github.com 같은 잘 알려진 레지스트리와 에이전트 자체 서비스는 새 호스트로 표시하지 않음), 일반 HTTP(포트 80), 대용량 업로드(에이전트 자체 서비스가 아닌 한 호스트에 10 MB 초과. 따라서 Claude Code가 Anthropic에 컨텍스트를 보내는 것은 표시하지 않음), 주소만 있음(알려진 호스트 이름 없음), 공유 또는 터널(일부 붙여넣기 사이트, transfer.sh 같은 파일 공유, ngrok 및 trycloudflare.com 같은 터널, webhook.site 같은 요청 수집 서비스). 표시된 항목만 보기를 선택하면 이 항목만 표시됩니다.

작동 방식: Kilobat은 이미 연결별 프로세스와 함께 macOS의 연결별 네트워크 통계를 매초 읽습니다(nettop과 동일). 실행 파일, 인터프리터가 실행하는 패키지(node …/@openai/codex, python3 -m aider) 또는 앱 자체의 실행 파일로 에이전트를 인식하고 각 에이전트의 프로세스 트리를 추적합니다. 커널이 트리의 프로세스가 분기하는 순간을 알려주므로 0.1초 동안 실행되는 curl도 실행 중에 할당되며 launchd로 부모가 변경된 프로세스도 에이전트에 속한 상태로 유지됩니다. 가장 가까운 에이전트가 우선하므로 Cursor 터미널에서 실행한 Claude Code는 Claude Code에 속합니다. 호스트 이름은 켜져 있는 Kilobat 네트워크 필터에서 앱이 요청한 이름을 가져오거나, 잘 알려진 개발자 호스트와 에이전트의 curl 또는 git URL에 있는 호스트를 Mac 리졸버로 조회하여 주소를 일치시키거나, 역방향 DNS에서 가져옵니다. 역방향 DNS는 앱이 요청한 이름이 아닌 서버 이름이므로 따로 표시합니다. 어느 방법으로도 찾지 못하면 행에 주소를 표시합니다.

볼 수 없는 항목: 프로세스 대신 macOS 서비스가 발생시키는 트래픽(DNS 조회는 mDNSResponder, 다운로드는 nsurlsessiond을 통해 처리), Docker 컨테이너와 가상 머신의 트래픽(Docker 또는 가상 머신 자체 프로세스를 통해 나감), VS Code의 Cline이나 Copilot처럼 편집기의 확장 호스트에서 실행되어 편집기와 구분할 수 없는 에이전트입니다. Cursor와 Windsurf에서는 내장 터미널에 입력한 명령이 해당 앱의 사용량으로 집계됩니다. 1초 간격의 두 샘플 사이에 열리고 닫힌 연결도 호스트 정보 없이 세션 바이트에 포함됩니다. 커널의 fork 알림을 처리하기 전에 시작하고 종료한 프로세스는 누락될 수 있습니다. 로그는 Kilobat Pro로 이 Mac의 ~/Library/Application Support/Kilobat/agent-network-log.json에만 기록되고 30일간 보관되며 어디에도 전송되지 않습니다. 지우기에서 지난 1시간, 오늘 또는 전체를 선택할 수 있습니다.

보호가 켜져 있으면 Kilobat이 거부한 연결도 바이트를 전송하지 않았더라도 목록 또는 에이전트 보호 규칙과 함께 차단됨으로 표시됩니다.

터미널에서 kilobat agent-log는 최근 세션을 출력하며, 에이전트가 실행하면 해당 에이전트의 세션을 출력합니다. --all, --since 2h, --agent claude, --flagged, --json로 범위를 좁힐 수 있습니다. 읽기는 무료이며, kilobat agent-log --watch는 앱이나 Pro 없이 터미널에서 실시간 기록을 표시하고 아무것도 저장하지 않습니다. 에이전트는 읽기 전용 MCP 도구 agent_network_log를 호출합니다. 인수 없이 호출하면 자신의 세션이 반환되므로 실행한 설치 작업이 어디와 통신했는지 확인할 수 있습니다.

기록 지우기 또는 사이트 지우기

설정 › 데이터 및 개인정보 보호의 사이트 잊기는 차단된 시도, 에이전트 네트워크 로그, 에이전트 실행과 잠자기 방지 세션의 대상, 보호 기능의 알림 기억에서 호스트를 삭제합니다. 하위 도메인 포함을 선택하면 www.example.com 같은 이름도 삭제합니다. 사이트 기록 지우기는 최근 1시간, 자정 이후 또는 전체 기간에 대해 같은 기록을 삭제합니다. 차단된 시도와 에이전트 네트워크 로그에도 각각 지우기 메뉴가 있으며 호스트 행의 단축 메뉴에서 잊기를 선택할 수 있습니다. 기록을 지워도 규칙과 보호 설정은 유지됩니다. 이후 활동은 다시 기록될 수 있습니다.

터미널에서 kilobat history forget example.com --subdomains --json 또는 kilobat history clear --hour을 사용합니다(--today와 --all도 사용 가능). 앱이 실행 중이면 명령은 앱에 현재 기록을 지우도록 요청하고, 앱이 닫혀 있으면 저장된 기록을 수정합니다. MCP clear_history도 같지만 에이전트에 기록 삭제를 요청한 경우에만 수행합니다. 삭제는 되돌릴 수 없으며 결과에 각 기록에서 삭제된 항목 수가 표시됩니다.

앱이 전면에 있는 동안

읽기나 발표를 할 때 찻잔의 앱이 전면에 있는 동안은 선택한 앱이 전면에 있을 때만 Mac의 잠자기를 방지하고 다른 앱으로 전환하면 다시 잠들게 합니다. 찻잔의 화면도 켜두기는 Kilobat이 잠자기를 방지하는 모든 경우와 마찬가지로 화면 유지 여부를 결정합니다. Kilobat은 macOS 자체의 앱 전환 이벤트를 따릅니다. 폴링하거나 마우스를 움직이거나 활동을 꾸미지 않으므로 모니터링 소프트웨어에 사용자가 있는 것처럼 표시하지 않습니다. 앱을 종료하거나 기능을 끄거나 배터리가 20%(또는 덮개 닫힘 실행에 설정한 최저 수준)에 도달하면 종료되며 덮개 닫힘 상태는 유지하지 않습니다. 별도의 유지 상태를 사용하므로 앱 전환이나 종료가 다른 잠자기 방지 세션 또는 에이전트 실행을 끝내지 않습니다. 터미널에서: kilobat awake --while-frontmost Keynote --display.

전원 연결 중

전원 연결 중 잠자기 방지(설정 › 잠자기 방지 및 에이전트) 또는 찻잔의 전원 연결 중을 켜면 전원 어댑터를 연결한 때부터 분리할 때까지 Mac이 잠들지 않습니다. 막대에 “전원 연결 중 잠자기 방지”라고 표시됩니다. 화면도 켜두기는 화면 유지 여부를 결정합니다. 기능을 끄면 Kilobat을 재시동하더라도 다음에 전원을 연결할 때까지 꺼진 상태가 유지됩니다. Kilobat은 폴링하지 않고 macOS 자체 전원 알림으로 전환을 감지합니다. 전원을 분리하면 전원 연결로 시작된 세션만 종료됩니다. 직접 시작한 세션, 기다리는 다운로드, 전면 앱, 에이전트 실행 또는 터미널에서 시작한 유지 상태는 계속됩니다. 덮개를 닫은 상태로 Mac을 실행하지는 않습니다. 터미널에서 kilobat settings awake-on-power on, 화면은 kilobat settings keep-screen-on on을 사용하며 kilobat conditions --json은 이를 awakeOnPower으로 보고합니다.

덮개를 닫은 상태에서 실행

설정 › 잠자기 방지 및 에이전트에서 덮개를 닫은 상태에서 실행을 허용하지 않으면 Kilobat이 Mac을 깨워 두더라도 덮개를 닫을 때 Mac이 잠자기 상태가 됩니다. 이 설정은 root로 실행되는 작은 도우미를 설치하며 macOS가 시스템 설정 › 일반 › 로그인 항목에서 허용을 요청합니다. 켜져 있으면 에이전트가 작업하는 동안 덮개를 닫아도 Mac이 계속 실행되며, 찻잔 메뉴에서 “덮개를 닫은 상태에서도”를 선택한 잠자기 방지 세션도 마찬가지입니다. 사용자를 기다리는 에이전트는 에이전트가 기다리는 동안 잠자기 방지가 켜져 있을 때만 최대 30분 동안 유지합니다.

덮개를 닫은 Mac을 가방에 넣으면 과열되고 배터리가 방전될 수 있습니다. 따라서 도우미는 배터리 하한(기본 20%)에 도달하거나 Mac이 뜨거워지거나, 전원 연결 시에만을 선택한 경우 전원이 분리되거나, 설정한 최대 시간(최대 8시간)이 지나거나, Kilobat 종료 후 1분이 지나면 Mac이 잠들도록 합니다. 잠자기 방지 중 도우미나 Mac이 재시작되면 먼저 설정을 복원합니다. Kilobat은 “Mac 잠자기 허용: 배터리 20%”처럼 각 잠자기 방지가 종료된 이유를 표시합니다.

터미널에서 kilobat awake --lid-closed는 앱에 동일한 보류를 요청하며 불가능할 때 이유를 알려줍니다. 보류는 명령이 끝나면 종료됩니다. 에이전트는 lid_closed와 함께 keep_awake를 사용하며, 설명에 먼저 확인을 받도록 안내되어 있습니다. kilobat conditions --json는 lidClosedAllowed 및 현재 lidHold를 보고합니다.

에이전트 스킬

9개의 Agent Skills는 코딩 에이전트가 Kilobat으로 Mac의 네트워크 문제를 진단하고 오래 걸리는 실행을 유지하도록 돕습니다. 측정값을 해석하고 불확실한 점을 설명하며 설정을 변경하기 전에 묻습니다. 함께 설치하면 kilobat 스킬이 에이전트를 상황에 맞는 스킬로 안내합니다.

npx skills add seifip/kilobat-skills

위의 Homebrew 명령으로 Kilobat CLI를 별도로 설치하거나 MCP 서버를 연결하세요. CLI에는 macOS 14 이상이 필요하며 Homebrew 소스 빌드에는 Xcode 16 이상이 필요합니다. skills.sh의 스킬을 보거나 소스와 참고 자료를 읽어보세요.

Siri 및 단축어

Siri에게 연결 상태를 물으면 Kilobat이 자체 검사 결과를 한두 문장과 수치 카드로 답합니다. Siri가 인식하도록 질문에 앱 이름을 넣으세요. “Kilobat에서 인터넷이 왜 느려?”라고 물으면 새 검사를 실행하고 원인을 알려줍니다. 예를 들어 “Wi-Fi는 정상입니다. 오후 9시 5분부터 통신사 회선에서 패킷의 4%가 손실되고 있습니다. 통신사 보고서에서 확인하세요.”라고 답합니다. “Kilobat에서 내 연결은 괜찮아?”, “Kilobat에서 통화가 왜 멈췄어?”(마지막 통화 보고서), “Kilobat에서 Slack에 장애가 있어?”(Kilobat이 상태 페이지를 읽는 모든 서비스 또는 사용 중인 서비스에 대해 “Kilobat에서 내 앱에 장애가 있어?”), “Kilobat에서 인터넷을 사용 중인 것은?”, “Kilobat에서 데이터를 얼마나 사용했어?”, “Kilobat에서 통화 준비가 됐어?”, “Kilobat에서 VPN이 새고 있어?”, “Kilobat으로 속도 테스트”도 물을 수 있습니다. Spotlight에서도 같은 질문을 사용할 수 있으며, 각각 단축어 앱의 동작으로 다음 단계에 답을 전달합니다. 네트워크 상태는 상태, 원인, 지연 시간과 손실을, 통화 보고서는 보고서 내용을, 서비스는 장애 보고 여부를, 오늘 데이터는 사용량을 전달합니다. 단축어의 모델 사용 동작은 이 결과를 Apple Intelligence에 전달할 수 있습니다. Kilobat Pro가 없어도 Siri는 문제와 회선 측정값, 통화가 멈춘 횟수, 서비스 장애 여부를 알려줍니다. Pro는 원인과 해결 방법을 추가합니다. 미리 만든 단축어도 같은 동작을 사용합니다.