Inspect AI coding-agent traffic locally, then provide controlled browser access to the trace viewer
Claude Tap is a local proxy and browser-based trace viewer for inspecting traffic generated by AI coding agents such as Claude Code and Codex CLI. This guide starts with the supported installation methods, shows how to launch the appropriate client, and explains how to verify the viewer using the HTTP address printed at runtime. After the local service works, we show how to expose that specific HTTP endpoint with Localtonet. Because traces can contain prompts, conversation history, tool activity, and other sensitive development context, remote access should be temporary and tightly controlled.
What Claude Tap captures and why the viewer is useful
Claude Tap is a local proxy and trace viewer designed for AI coding agents. Instead of relying only on the final text shown by an agent, it lets developers inspect the traffic and context associated with a run. The viewer can display system prompts, conversation history, tool schemas, tool calls, tool results, reconstructed streaming responses, token usage, and differences between requests.
This level of visibility is useful when an agent behaves differently between turns, chooses an unexpected tool, receives an incorrect parameter, or appears to lose important context. Comparing adjacent requests can help identify whether a prompt, message, tool definition, or request parameter changed. A trace therefore provides evidence about what the agent received and produced rather than requiring developers to infer behavior solely from the visible terminal response.
Claude Tap runs locally and does not require a hosted dashboard. Each run writes a local trace session, and the project also supports exporting a session as a self-contained HTML viewer for review or archiving. Its documentation states that common authentication headers are redacted before recording. That redaction is helpful, but it does not make every trace safe to publish. Prompts, source fragments, file paths, tool results, error messages, model output, and conversation history can still reveal confidential information.
Prerequisites
Claude Tap requires Python 3.11 or newer. You also need the client you intend to trace, such as Claude Code or Codex CLI, installed and configured independently. Claude Tap does not replace the agent client or its normal authentication process. Confirm that the selected client works on its own before adding the tracing layer, since this makes installation and runtime problems easier to isolate.
If you plan to use Localtonet later in the guide, install and run our client on the same device as Claude Tap, or on a device that can reach the viewer's local HTTP endpoint. The local viewer must be running and reachable before a tunnel can provide useful remote access.
Agent traces can include prompts, conversation history, tool schemas, tool inputs, tool results, code fragments, file paths, and model responses. Common authentication-header redaction does not guarantee that a trace contains no secrets. Review the captured session, apply appropriate access controls, share only with intended reviewers, and stop the tunnel when remote access is no longer required.
Install and verify Claude Tap locally
Confirm Python and the agent client are available
Verify that the environment has Python 3.11 or newer and that the client you want to inspect is already installed. Test Claude Code or Codex CLI through its normal workflow first so that any later failure can be separated from the underlying client installation.
Install Claude Tap
Use the recommended uv tool installation command, or use the documented pip alternative if that better matches your Python environment. Only one installation method is necessary.
Launch the selected coding agent through Claude Tap
Run Claude Tap without a client selector for Claude Code. For Codex CLI, use the documented codex client option. The live browser viewer is enabled by default for the normal launch.
Generate a small test trace
Start a low-risk test interaction in a project that does not contain confidential material. This gives the viewer an initial session to display while reducing the chance that sensitive production information is captured during setup.
Read the viewer address from runtime output
Inspect Claude Tap's terminal output for the local browser-viewer URL. The available evidence does not establish a fixed hostname, port, or exact URL, so do not assume one. Record the actual local host and port reported by the running version.
Open and verify the local viewer
Open the runtime-provided URL from a browser that can reach the service. Confirm that the viewer loads and that the test session appears. Complete this local check before configuring Localtonet, since a tunnel cannot correct a viewer that is not running or locally reachable.
Recommended installation with uv
uv tool install claude-tapAlternative installation with pip
pip install claude-tapThe uv command is the project's recommended installation method, while pip is the documented alternative. Avoid running both unless you intentionally manage separate Python environments, since multiple installations can make it unclear which executable your shell is launching.
Start Claude Code with the live viewer
claude-tap
For Claude Code, Claude Tap is used in place of the normal claude command. The live browser viewer is enabled by default. If you need to pass Claude Code arguments, the project documents placing them after --, but only pass flags you understand and would normally use with Claude Code.
Start Codex CLI with the live viewer
claude-tap --tap-client codex
The explicit codex client selection launches the Codex CLI tracing workflow. As with the Claude Code workflow, confirm normal client authentication and operation independently before diagnosing Claude Tap.
This guide intentionally does not provide a default hostname, port, or URL for Claude Tap. Those details are not established by the supplied official evidence and may vary by version or environment. Use the address printed by the running application, verify it locally, and enter that observed host and port when configuring the Localtonet target.
Choose between a live tunnel and a portable export
A live HTTP tunnel is useful when another authorized person or device needs to inspect an active viewer. It preserves the interactive browser experience and can make current traces available while Claude Tap remains running. It also creates a public route to sensitive development information, so the tunnel should exist only for the required review window.
A self-contained HTML export can be preferable when the session is complete and does not need live updates. The exported artifact can be reviewed or archived without keeping the local viewer server available. It still contains trace data, so it needs the same careful handling as any other sensitive development artifact.
| Access approach | Best suited to | Important behavior |
|---|---|---|
| Local live viewer | Review on the machine running Claude Tap | No remote tunnel is needed, and the viewer remains limited to whatever interfaces the local service actually uses. |
| Live viewer through Localtonet | Temporary browser access from another authorized device | The HTTP tunnel points to the verified local host and port and works only while the selected Localtonet client and tunnel are running. |
| Self-contained HTML export | Completed-session review or archiving | The artifact is portable and does not require a live viewer, but its trace contents must still be protected. |
Share the verified viewer with Localtonet
Once the Claude Tap viewer works locally, an HTTP tunnel can make that web endpoint reachable through a public HTTPS address. With Localtonet, our client establishes an outbound connection to a relay server, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
The tunnel must target the actual IP address and port reported by Claude Tap. Do not copy a guessed port from another tutorial or from a different installation. If the Localtonet client runs on another device, that device must be able to reach the viewer over the local network, and the address shown only as a loopback endpoint might not be reachable from it. The simplest arrangement is generally to run both applications on the same device, provided that arrangement fits your environment and security policy.
Install and run the Localtonet client
Run our client on the device hosting Claude Tap or on a device that can reach its verified HTTP endpoint. Keep Claude Tap running so the target remains available during configuration and testing.
Authenticate or select the device
Use the device-specific authentication token associated with the client that will run the tunnel. Never paste a token into documentation, screenshots, trace sessions, chat messages, or shared configuration examples.
Select an available relay server
Choose from the server or region values currently available in the dashboard. Availability can vary, so this guide does not hardcode a server code or geographic location.
Create an HTTP tunnel to the viewer
Configure the HTTP tunnel with the local IP address and port discovered from Claude Tap's runtime output. HTTP tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain. Check current documentation before configuring custom-domain DNS.
Start the tunnel and test the public URL
Creating a tunnel does not start it. Use the Start button, then open the assigned public HTTPS URL from the intended remote device. Confirm that the correct viewer appears and that no unintended local service was selected.
Stop or delete access after the review
Stop the tunnel as soon as remote access is no longer required, or delete it if the configuration will not be reused. The public route is available only while the selected client is connected and the tunnel is running.
For the current dashboard workflow and available options, consult the Localtonet HTTP tunnel documentation. Exact relay choices, domain settings, and subscription availability should always be confirmed in the current product rather than inferred from an example.
A locally reachable viewer and a publicly routed viewer have different risk profiles. Before starting the tunnel, review the trace for secrets, confirm any viewer-side authentication controls available in your installed Claude Tap version, limit access according to your environment's policies, and avoid leaving the URL active as a permanent dashboard. Do not assume that an unguessable-looking URL is an authorization mechanism.
Troubleshooting the complete path
The Claude Tap command is not found
Confirm that the uv tool or pip installation completed successfully and that the environment's executable location is available to your shell. If multiple Python environments exist, verify which environment received the package. Do not install repeatedly into unrelated environments without first identifying which executable path is active.
The agent starts, but no trace appears
Make sure you launched the intended client through Claude Tap rather than starting the original agent command separately. For Claude Code, use claude-tap. For Codex CLI, use claude-tap --tap-client codex. Generate a simple test interaction and then recheck the viewer.
The viewer does not open locally
Return to the terminal and use the exact address printed by the running application. Confirm that the Claude Tap process remains active. Do not proceed to tunnel configuration until a browser that can reach the local endpoint successfully loads the viewer.
The tunnel starts, but the public page does not load
Recheck the local target entered in the HTTP tunnel. The host and port must match the working Claude Tap endpoint. Also confirm that the selected Localtonet client is connected and can reach that target. A tunnel configuration can exist without running, so verify that you explicitly started it.
Frequently asked questions
What version of Python does Claude Tap require?
Claude Tap requires Python 3.11 or newer. You also need the AI coding-agent client you want to trace, such as Claude Code or Codex CLI.
Should I install Claude Tap with uv or pip?
The project recommends uv tool install claude-tap. The documented alternative is pip install claude-tap. Use the method appropriate for your Python environment rather than installing both by default.
How do I run Claude Code through Claude Tap?
Run claude-tap in place of the normal claude command. The live browser viewer is enabled by default for this workflow.
How do I run Codex CLI through Claude Tap?
Use claude-tap --tap-client codex. Confirm that Codex CLI already works in its normal configuration before adding the tracing layer.
What port does the Claude Tap viewer use?
This guide does not assume a port because the supplied official evidence does not establish a fixed value. Read the local viewer URL from Claude Tap's runtime output and use the host and port actually reported by your installation.
Does creating a Localtonet tunnel make it active immediately?
No. Creating a tunnel does not mean it is running. Start it with the Start button. The public route remains available only while the selected Localtonet client is connected and the tunnel is running.
Is a Claude Tap trace safe to share publicly?
It should not be treated as public by default. Although Claude Tap documents redaction of common authentication headers, traces can still contain prompts, conversation history, code, paths, tool activity, and other confidential context. Review the data and use appropriate access controls before sharing it.
Provide temporary access to your verified trace viewer
After Claude Tap is installed, running, and confirmed locally, use an HTTP tunnel with Localtonet to reach that specific viewer from an authorized remote browser. Keep the exposure limited to the review window and stop the tunnel when the work is complete.
Get Started Free →
