Codex + HTTPeep CLI Skill: Debug API Calls from Real Network Sessions

AI-assisted coding is already good at reading code, explaining logic, modifying implementations, and running tests. But when it comes to debugging API calls, it often misses a critical input: real network sessions.

The code might look like it's hitting the right URL with the correct parameters — but the actual request going out could be something entirely different.

For example:

• The Authorization header is missing.
• The token has expired, but the frontend state still shows it as valid.
• Query parameters are formatted incorrectly.
• The request body doesn't match the backend schema.
• The request is actually hitting a staging, test, or local server instead of the environment you expect.
• The backend returns a business error, but the frontend only surfaces a generic Network Error.

If Codex can only read code, it can only infer what the request should look like based on the source. It might make reasonable guesses, but they're still guesses.

The value of the HTTPeep CLI Skill is delivering real HTTP/HTTPS sessions to Codex — so the agent can see not just the intent in the code, but what the request actually looked like and what the server actually returned.

hp is an alias for httpeep-cli. Using hp instead of httpeep-cli is shorter and easier to remember and type.

Without Network Context, AI Can Only Guess

The traditional AI debugging workflow usually goes like this:

1. You tell Codex: “This endpoint returns 401, help me figure it out.”
2. Codex reads the login, authentication, request wrapper, and state management code.
3. It speculates: maybe the token wasn't written, the request interceptor didn't fire, the backend session expired, or the environment variable is misconfigured.
4. You go copy more information from browser DevTools, terminal logs, or backend logs.
5. Codex continues reasoning based on the extra context you provided.

The problem with this workflow isn't that Codex isn't smart enough — it's that it can't see the key evidence.

API debugging is often not a question of “is this line of logic in the code?” but rather “did this line of logic actually take effect in the real request?” Looking only at source code, Codex struggles to confirm:

• What the final request URL is.
• Whether headers were actually injected.
• Whether the body was serialized as expected.
• Whether cookies were sent by the browser.
• What the server actually returned in status, headers, and body.
• Whether the failure happened at the application layer, proxy layer, TLS layer, or upstream service.

Without real session context, AI responses tend to stay at the level of directional suggestions like “it might be an auth issue,” “suggest checking CORS,” or “confirm if the token has expired.”

The direction might not be wrong — but it's not enough.

With Real Session Context, Codex Can Inspect the Evidence

Once you connect the HTTPeep CLI Skill, the debugging approach becomes more direct.

Codex can first check the sessions captured by HTTPeep, then go back to the code to pinpoint the problem:

1. List recent API requests.
2. Find sessions with 4xx, 5xx, or abnormal responses.
3. Read the request and response of specific sessions.
4. Compare against the request construction logic in the code.
5. Give a judgment based on the real request/response.
6. After modifying the code, trigger the request again and verify with new sessions.

This is fundamentally different from “pasting the error into AI.”

You no longer need to copy headers, payloads, and response bodies from DevTools piece by piece to Codex. Codex can see the actual network context through the HTTPeep CLI, and then analyze that context alongside the code.

This significantly reduces two common types of misdiagnosis:

• Code intent vs. actual request mismatch: The code has header injection, but the real request doesn't.
• Frontend assumption vs. backend response mismatch: The frontend expects { user } to be returned, but the actual response is { data: { user } } or an error structure.

HTTPeep here isn't replacing Codex — it's supplementing the network evidence that Codex lacks by default.

Install the HTTPeep CLI Skill

The HTTPeep CLI Skill is a skill description for Codex / agents. It helps the agent reliably know how to call the HTTPeep CLI, how to view sessions, how to check proxy status, and how to troubleshoot certificate-related issues.

Install command:

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

After installation, Codex will prefer to use the HTTPeep CLI when debugging network issues, rather than relying entirely on code inference.

If your project uses AGENTS.md, consider adding an explicit prompt:

When debugging APIs, network requests, proxies, certificates, or real HTTP sessions, prefer using the HTTPeep CLI Skill to inspect actual sessions.

This kind of prompt is very useful. It causes the agent to check real requests first when encountering API issues, rather than immediately starting to guess about application code.

First Use: Install and Trust the Certificate

If you need to debug HTTPS requests, HTTPeep needs to install and trust a local CA certificate. This allows HTTPeep to decrypt HTTPS traffic in the local proxy chain and display plaintext requests and responses.

On first use, a single command does it:

httpeep-cli cert install

After installation, confirm the proxy status:

httpeep-cli proxy status

If the proxy isn't running, start it:

httpeep-cli proxy start

If you can only see CONNECT but not the HTTPS request's path, headers, and body, it usually means the certificate trust or HTTPS MITM chain isn't ready yet. First confirm the local CA is installed and trusted by the system, then re-trigger the target request.

The certificate is only for local debugging. When handling production tokens, cookies, user data, or third-party sensitive responses, you should still follow the principle of minimal exposure — don't send unnecessary sensitive content to public conversations or external systems.

Capture a Real API Call

With the HTTPeep proxy ready, reproduce an API call in your application.

This could be a frontend page in a browser, a desktop app, mobile device, CLI tool, SDK, local service, or test process. The key is that the target traffic needs to go through the HTTPeep proxy.

Then check recent sessions with the CLI:

httpeep-cli sessions list

If you want Codex or scripts to parse the output more easily, use JSON output:

httpeep-cli sessions list --format json

In real debugging scenarios, you typically have Codex do two things:

• First, find recent failed or abnormal requests.
• Then read the detailed request/response of specific sessions.

Here's a screenshot or GIF of HTTPeep capturing API sessions:

![HTTPeep capturing API sessions example](./images/codex-httpeep-cli-sessions.gif)

You can later replace this with real demo footage — for example, the full process of Codex calling the HTTPeep CLI, listing sessions, and selecting a failed request.

Have Codex Read Failed Requests

When HTTPeep has already captured sessions, don't just tell Codex “the endpoint failed.” A better approach is to have it directly inspect the HTTPeep sessions.

You can prompt like this:

Use the HTTPeep CLI to check recent failed API requests and find common patterns among 4xx/5xx responses.

Or:

Read this session and determine whether the failure is more likely caused by frontend parameters, authentication, environment routing, or the backend response.

Going further:

Based on the real request body, check if the payload construction logic in the code is consistent.

When Codex reads sessions, the focus isn't “did a request happen” — it's whether these fields match expectations:

• Whether the method and URL are correct.
• Whether query parameters are complete.
• Whether request headers include key fields like authentication, content type, and trace ID.
• Whether the request body conforms to the backend API protocol.
• Whether the response status is a business failure, auth failure, gateway failure, or network error.
• Whether the response body is consistent with the frontend parsing logic.
• Whether timing shows slow upstream responses, connection failures, or proxy rule interference.

This information directly determines the fix direction.

If the real request doesn't have an Authorization header, you shouldn't start by modifying the backend. If the real response body structure doesn't match the frontend type definitions, you shouldn't keep suspecting browser cache. If the request hits the wrong domain, you should first check the environment, DNS Override, proxy, or base URL configuration.

These judgments all come from real sessions — not guesses.

After the fix, trigger the request again and have Codex verify with the HTTPeep CLI using the new session:

Check the latest /api/me request again and confirm it now has the Authorization header and the response status is 200.

Here's a GIF of Codex reading an HTTPeep CLI session and identifying a 401:

![Codex reading HTTPeep CLI session and identifying 401](./images/codex-debug-401-with-httpeep.gif)

This kind of demo is great for showing “the AI isn't analyzing in a vacuum — it's reading real network evidence.”

Going Further: Use HTTPeep Rules to Reproduce and Verify Issues

HTTPeep isn't just a session viewer. Its core capability is turning network debugging actions into reusable rules.

After Codex has identified the problem through real sessions, it can further suggest or operate HTTPeep rules to help you reproduce and verify.

For example:

• Use Map Local to return local JSON, simulating a backend endpoint that hasn't been completed yet.
• Use Map Remote to route matching requests to a local or staging service.
• Use Modify Response to simulate missing fields, error statuses, or edge-case responses.
• Use Delay / Throttle to reproduce slow endpoints, weak networks, and timeout behavior.
• Use Breakpoint to pause requests or responses, manually inspecting and modifying traffic as it passes through.

At this point, Codex's role isn't “automatically deciding everything for you” — it's providing inspectable debugging actions based on real sessions.

For example:

Based on the session that just failed, help me design an HTTPeep rule that uses local JSON to simulate the same error response, so I can verify frontend error handling.

Or:

Based on this request, create a Map Remote debugging scheme to temporarily forward api.example.com's /api/me to the local service.

The benefit of rules is that they're visible, toggleable, and reusable. You don't have to scatter one-off debugging state across hosts files, temporary code, environment variables, and memory.

How Skill, CLI, and MCP Relate to Each Other

These concepts can be easily confused — here's a simple distinction:

• HTTPeep CLI is the command-line tool for starting the proxy, viewing sessions, managing rules, handling certificates, and executing terminal workflows.
• HTTPeep CLI Skill is the usage guide for Codex / agents, telling them how to use the HTTPeep CLI when encountering network debugging tasks.
• HTTPeep MCP is the tool interface that agents can connect to, letting tools like Codex and Claude directly read and operate HTTPeep's runtime state.

You can use just the CLI, or give agents more direct access to HTTPeep through MCP. The CLI Skill's role is to help Codex proactively think of and correctly use these capabilities at the right time.

FAQ

What if httpeep-cli is not found?

First confirm you've installed and launched the HTTPeep desktop app. The desktop app includes the CLI.

Then check in your terminal:

httpeep-cli --version

If the command isn't found, go to HTTPeep's settings to repair the CLI / PATH installation, then restart your terminal.

The Skill is installed, but Codex doesn't use it proactively?

Add a clear instruction in AGENTS.md:

When debugging APIs, network requests, proxies, certificates, or real HTTP sessions, prefer using the HTTPeep CLI Skill to inspect actual sessions.

You can also directly ask in the conversation:

Please first use the HTTPeep CLI to check real network sessions before diagnosing this API issue.

HTTPS only shows CONNECT?

This usually means the certificate trust chain isn't ready yet. First run:

httpeep-cli cert install

Then restart the target application or browser, and trigger the request again.

No requests captured?

Prioritize checking three things:

1. Whether the HTTPeep proxy is running.
2. Whether the target application's traffic goes through HTTPeep.
3. Whether there are Bypass rules, system proxy, application proxy, or upstream proxy configurations affecting the path.

Browsers can usually rely on the system proxy. Mobile devices, CLI tools, SDKs, or service processes may need explicit proxy configuration.

Can I send tokens, cookies, and production responses directly to AI?

Not recommended.

HTTPeep is a local-first debugging tool, but you should still control the exposure scope of sensitive information. When debugging production issues, try to redact tokens, cookies, user IDs, emails, order numbers, and business-sensitive fields.

A better approach is to have Codex read the necessary structure locally and only summarize the problem in its output, without copying complete sensitive values.

From Describing Problems to Inspecting Evidence

Codex excels at reading code, reasoning, modifying implementations, and organizing verification steps.

HTTPeep CLI provides real requests and responses.

The HTTPeep CLI Skill connects the two, letting Codex check network evidence first when debugging APIs, then go back to the code to identify the root cause.

This is the most important change in this workflow: AI is no longer just guessing API behavior from code — it can debug based on actual network sessions.

When real requests, responses, status codes, headers, bodies, and timing can all be inspected by the agent, API debugging shifts from “you describe the problem” to “AI and you look at the evidence together.”