HTTPeep CLI Skill for AI Agents

The httpeep-cli Skill is an operating guide for AI coding agents. It is not a separate packet-capture app. It teaches an agent how to use httpeep-cli from the terminal so the agent can inspect the HTTP and HTTPS traffic your application actually sends.

After the Skill is installed, an agent can check whether HTTPeep is running, capture sessions, filter requests by process or domain, inspect headers and bodies, replay failed requests, and compare traffic before and after a fix. That gives the agent runtime network context instead of forcing it to guess from source code alone.

For a beginner, the simple version is this: install HTTPeep, install this Skill, reproduce the problem, then ask your agent to look at the captured traffic before it edits code.

What this Skill does

The Skill provides an AI agent with a structured approach to using the httpeep-cli for network debugging Almost all of HTTPeep's features can be implemented via CLI, giving AI the ability to view network context.

• Verify capture is ready - check the httpeep-cli binary, proxy state, recent logs, and certificate trust.
• Capture real traffic - observe HTTP/HTTPS requests from curl, local dev servers, Node.js scripts, Python scripts, Rust binaries, SDKs, and other command-line tools.
• Find the relevant request - filter sessions by keyword, domain, status code, URL, process name, or process ID.
• Inspect request and response details - review method, URL, headers, body, status code, redirects, timing, and process metadata.
• Replay requests - reproduce a captured request to confirm whether the failure is stable.
• Test changes safely - use temporary rules before changing persistent rules.
• Create trace evidence - report command history, session IDs, important JSON fields, and rule IDs without leaking secrets.
• Rules and mocks - for advanced agents, the Skill also provides commands to create temporary rules that modify requests or responses, which is useful for debugging and testing fixes.

Why network context matters

AI agents are good at reading code, but code only describes what the program intends to do. Network traffic shows what the program actually did at runtime.

Without network context, an agent often has to infer:

• which URL was really called
• whether a request followed a redirect
• whether a POST body was preserved
• whether an Authorization header or cookie was sent
• whether a response was compressed, cached, mocked, rewritten, or malformed
• whether the slow part was DNS, connection setup, TLS, server latency, or response download
• whether an SDK or third-party library sent a different request than the code appears to build

Those guesses can sound reasonable and still be wrong. Network context changes the workflow:

Reproduce the problem
-> Agent inspects real traffic
-> Agent identifies the likely root cause from evidence
-> Agent edits code or configuration
-> Agent captures traffic again and verifies the behavior changed

That is the closed loop: observe, diagnose, fix, verify. For a deeper explanation, read How API network context enables AI to debug closed loops.

Problems it helps solve

Use this Skill when the bug has anything to do with an API, proxy, SDK, login flow, webhook, local dev server, or external service. Common examples include:

• A frontend says "undefined" or "empty data", but the real API response has a different shape.
• A POST becomes a GET after a 301 or 302 redirect.
• A request fails because Authorization, Cookie, Content-Type, or a custom header is missing.
• A local app calls the wrong host, path, port, environment, or API version.
• A backend returns 400, 401, 403, 404, 409, 422, or 500, and the agent needs the real request body to understand why.
• A request is slow, and the agent needs timing data instead of guessing at performance bottlenecks.
• HTTPS interception is not working because the local certificate trust is incomplete.
• CORS, proxy, rewrite, or mock rules are changing the traffic in a way the code does not show.
• An SDK, CLI, package manager, or generated client sends hidden network calls that are outside your application code.

Install the Skill

Install the Skill from the public repository:

npx skills add HTTPeep/agent-skills --skill httpeep-cli

Prerequisites

Before asking an agent to debug traffic, make sure HTTPeep and httpeep-cli are available.

httpeep-cli --version

httpeep-cli proxy status
httpeep-cli proxy logs --lines 50

httpeep-cli cert status

Add it to an existing Agent workflow

After the Skill is installed, you do not need to explain HTTPeep command syntax every time. Ask the agent to use HTTPeep when the task needs network evidence:

Use HTTPeep / httpeep-cli to inspect the recent traffic before changing code.
Find the request related to this login failure and explain the root cause from the captured session.
After the fix, capture the flow again and compare the request and response with the previous run.

A good agent workflow is:

1. Confirm httpeep-cli --version.
2. Check httpeep-cli --format json proxy status.
3. Start or repair capture if needed.
4. Reproduce the bug.
5. Query sessions with narrow filters.
6. Inspect the relevant request and response.
7. Make the smallest code or configuration change.
8. Capture again and compare the result.

For machine-readable output, the agent should prefer JSON:

httpeep-cli --format json sessions list --keyword login
httpeep-cli --format json sessions watch --domain api.example.com

OpenClaw and Hermes

The same httpeep-cli Skill can be used from OpenClaw and Hermes when those agents support local Skills or can read project-level agent instructions.

Install the Skill once, then ask the agent to use HTTPeep as part of the debugging task:

Use the httpeep-cli Skill to inspect the latest API traffic. Do not guess from code only.
Find the failing request, summarize the method, URL, status, response body, and timing, then propose a fix.

Keep the integration simple:

• Make sure httpeep-cli is available in the same shell environment where the agent runs.
• Keep HTTPeep running, or allow the agent to start the proxy with httpeep-cli proxy start.
• Ask the agent to report session IDs and redacted evidence when it summarizes findings.
• For complex work, ask the agent to capture traffic before and after the fix so the result is verifiable.

Recommended agent commands

Start with status checks:

httpeep-cli --version
httpeep-cli proxy status
httpeep-cli proxy logs --lines 50
httpeep-cli cert status

If the proxy is not running:

httpeep-cli proxy start --port 8800
httpeep-cli proxy system status

Find captured traffic:

httpeep-cli --format json sessions list --keyword login
httpeep-cli --format json sessions list --status-code 500
httpeep-cli --format json sessions list --domain api.example.com
httpeep-cli --format json sessions list --process-name-like node

Watch new traffic while reproducing a bug:

httpeep-cli --format json sessions watch --keyword api

Replay or send requests:

httpeep-cli replay --id <session_id> --retry-times 3 --retry-interval-ms 800
httpeep-cli --format json request --method GET --url "https://api.example.com/v2/users"

Use temporary rules for reproducible tests:

httpeep-cli rules run \
  --map-remote "api.example.com=http://127.0.0.1:3000" \
  -- httpeep-cli request --method GET --url "https://api.example.com/users"

Use persistent commands like rules upsert, rules replace, or rules reset only when you explicitly want to modify the saved ruleset. Export existing rules first:

httpeep-cli rules export --output rules-backup.json

Example: capture curl from the terminal

Use hp shell when you want every command launched from one terminal session to inherit HTTPeep capture settings.

hp shell

Inside that child shell, verify capture:

echo "$HTTPEEP_INTERCEPT_ACTIVE"
echo "$HTTP_PROXY"
curl -v https://httpbin.org/get

Then ask the agent:

Use HTTPeep to inspect the curl request I just sent. Show the method, URL, status, headers that matter, and timing. Redact secrets.

The agent can query:

httpeep-cli --format json sessions list --process-name-like curl

Example: capture a Next.js dev server flow

This is useful when a Next.js route handler, server action, API route, or server component calls another API and the agent needs to see the real outgoing request.

Start the app inside hp shell:

hp shell
bun run dev

In another terminal, trigger the local route:

curl -v http://localhost:3000/api/search?q=test

If your app runs on a different port, use that port instead. You can also trigger the request from a browser or from the UI if that is how the bug reproduces.

Then ask the agent:

Use HTTPeep to inspect the traffic from the Next.js dev server. Find the request triggered by /api/search, check the upstream URL, method, status, response body, and timing, then explain whether the problem is in our code or the upstream API.

Helpful filters:

httpeep-cli --format json sessions list --process-name-like node
httpeep-cli --format json sessions list --keyword search
httpeep-cli --format json sessions watch --keyword api

Example: capture Node.js, Python, and Rust programs

Run the program from inside hp shell so it inherits proxy environment variables.

Node.js:

hp shell
node scripts/smoke-test.js

Python:

hp shell
python scripts/smoke_test.py

Rust:

hp shell
cargo run

Then filter sessions by process or keyword:

httpeep-cli --format json sessions list --process-name-like node
httpeep-cli --format json sessions list --process-name-like python
httpeep-cli --format json sessions list --process-name-like cargo
httpeep-cli --format json sessions list --keyword api.example.com

For Rust programs and other native binaries, make sure the HTTP client you use respects HTTP_PROXY, HTTPS_PROXY, or explicit proxy configuration. hp shell provides the environment, but the application or library still decides whether to use it.

Prompts you can give your agent

Use prompts that force observation before diagnosis:

Use HTTPeep to inspect recent failed requests. Do not edit code until you identify the failing session and summarize the evidence.

I reproduced the bug. Find the POST request related to checkout, check whether the body was sent, whether any redirect happened, and what the response body says.

Compare the captured traffic before and after your fix. Confirm that the method, URL, status code, response body, and timing changed in the expected way.

The app says the user has no plan. Use HTTPeep to inspect the account API response and decide whether the bug is in rendering code, API mapping, auth, or the upstream service.

Troubleshooting checklist

If an agent cannot see or debug traffic, check these in order:

1. CLI availability: httpeep-cli --version
2. Proxy engine: httpeep-cli --format json proxy status
3. Recent logs: httpeep-cli proxy logs --lines 100
4. App routing: HTTP_PROXY, HTTPS_PROXY, or httpeep-cli proxy system status
5. HTTPS trust: httpeep-cli cert status, then httpeep-cli cert install if needed
6. Terminal capture shell: httpeep-cli shell / hp shell
7. Machine output: rerun relevant commands with --format json

For complex debugging, ask the agent to leave a concise trace log:

• commands executed, with important flags
• session IDs used or produced
• relevant JSON fields from captured sessions
• proxy log summary when proxy behavior is involved
• rule IDs or temporary rule shortcuts applied
• what changed after the fix was verified

Related docs

• CLI Overview - command groups and common workflows
• Shell - capture terminal traffic with httpeep-cli shell or hp shell
• Proxy - start, stop, and inspect proxy state
• Sessions - list, filter, and watch captured traffic
• Rules - test and persist request/response manipulation rules
• MCP Overview - connect AI agents to HTTPeep through MCP when you need tool calls instead of a loaded Skill