Set Up Claude Tap and Share Traces with Localtonet

What Claude Tap captures and how the workflow fits together

Claude Tap is a local proxy and browser-based trace viewer for AI coding agents. You run a supported command-line client through Claude Tap, or use one of its documented transcript-listening or application-specific modes, and then inspect the resulting requests in a local browser. The viewer can show system prompts, conversation history, messages, tool definitions, tool calls, tool results, reconstructed streaming responses, token usage, and differences between adjacent requests.

This visibility is valuable when an agent behaves differently between turns, selects an unexpected tool, receives an incorrect parameter, or appears to lose relevant context. Instead of inferring what happened from the terminal's final answer, you can examine the request evidence and compare how prompts, messages, tools, or parameters changed.

Claude Tap does not require a hosted trace dashboard. Each run writes a local trace session, and the project documents redaction of common authentication headers before recording. That is a useful safeguard, but it is not a guarantee that a trace is safe to distribute. Prompts, source fragments, tool inputs, tool results, filenames, local paths, error messages, conversation history, and model responses can still expose confidential information.

The primary project documentation is maintained in the Claude Tap repository. Check that repository when behavior differs from this tutorial, particularly after an upgrade or when using a client other than the Claude Code example covered here.

Supported clients extend well beyond Claude Code

The current Claude Tap repository lists support for Claude Code, Codex CLI, Codex App, Gemini CLI, Grok Build CLI, DeepSeek Harness, legacy Kimi CLI, Kimi Code CLI, MiMo Code, OpenCode, OpenClaw, Pi, Hermes Agent, Cursor CLI and IDE Agent transcripts, Qoder CLI, Antigravity CLI, and CodeBuddy CLI. These integrations do not all operate identically. Some launch a CLI through a proxy, some use forward-proxy behavior for an application, and some watch local transcripts.

This article deliberately keeps the worked procedure focused on Claude Code, with one verified Codex CLI command for reference. For another client, use the exact selector and mode in the current Claude Tap repository rather than assuming that the Claude Code launch command applies. Client availability and invocation details can change between releases.

Prerequisites and a safe test environment

Prepare the underlying agent and Python environment before installing Claude Tap. This separation matters because a tracing tool cannot repair a broken agent installation, an expired login, or a shell that is using the wrong Python environment.

Python 3.11 or newer

Claude Tap requires Python 3.11 or newer. Check the interpreter selected by your shell:

python --version

Some systems expose the intended interpreter under python3 instead:

python3 --version

Continue only when the reported version is 3.11 or later. If both commands exist, make sure the installation tool you select uses the environment you intend. A system Python, virtual environment, pip installation, and uv tool installation can place executables in different locations.

A working supported agent client

Install and configure the client you want to trace before adding Claude Tap. For this tutorial, that client is Claude Code. Its official CLI provides commands for checking authentication and installation health:

claude auth status
claude doctor

According to the Claude Code CLI reference, claude auth status reports the authentication state and exits successfully when logged in, while claude doctor performs read-only installation and settings diagnostics. If authentication is required, use the login workflow documented for your environment:

claude auth login

Also start a normal Claude Code session in a low-risk test directory before introducing Claude Tap. If Claude Code itself cannot launch or complete a simple interaction, resolve that problem first. The broader Claude Code commands documentation explains session commands and diagnostic options available inside Claude Code.

An appropriate Python installation method

The Claude Tap project recommends installation as a uv tool and also documents pip as an alternative. A uv tool installation is isolated from project dependencies and is often easier to reason about for a command-line application. A pip installation can also work, but the executable will be associated with the Python environment into which pip installed the package.

If you intentionally use a virtual environment, activate it before installing with pip and again before running Claude Tap. If you need the command from arbitrary directories without activating that environment, use an installation approach designed to expose the executable globally for your user account, such as the documented uv tool method.

A low-risk test project

Begin in a small test directory that does not contain production source code, customer data, credentials, deployment files, confidential prompts, or private environment configuration. Ask the agent to perform a harmless task that produces at least one request without requiring access to sensitive files. This gives you a trace to validate while minimizing the consequences of accidental sharing.

The Localtonet client on a device that can reach the viewer

For the remote-access portion, run our Localtonet client on the same device as Claude Tap or on another device that can reach the viewer's actual local IP address and port. Running both processes on the same device is the simplest topology when Claude Tap listens only on a loopback address such as 127.0.0.1.

Keep the Localtonet device token private. Tokens identify client devices and must not be placed in trace output, screenshots, terminal recordings, documentation, issue reports, or chat messages.

Install Claude Tap and verify a local trace

Complete the local workflow from end to end before creating a Localtonet tunnel. The important checkpoint is not merely that the package installed. Claude Tap must launch the intended agent, the agent must generate a trace, and the runtime-provided viewer URL must load in a browser.

Recommended installation with uv

uv tool install claude-tap

Alternative installation with pip

pip install claude-tap

Verify the installed command

claude-tap --help

A successful help response confirms that the shell can find and execute Claude Tap. It does not yet prove that the selected coding agent can launch, that traffic will be captured, or that the browser viewer is reachable. Those checks happen next.

Start Claude Code with the live viewer

claude-tap

Use Claude Tap in place of the normal claude command. If you need to pass ordinary Claude Code arguments, the project documents placing them after --. Keep initial validation simple rather than adding model, permission, or upstream overrides before the basic path works.

Claude Tap also documents claude-tap -c for continuing the most recent Claude Code conversation. For first-time validation, a new low-risk session is easier to inspect and less likely to include older sensitive context.

Codex CLI reference command

claude-tap --tap-client codex

This selector launches the documented Codex CLI tracing workflow. Other supported clients have their own selectors and, in some cases, additional launch or transcript-watching behavior. Use the current repository for those exact commands.

Update, stop, restart, and manage trace data

Use one documented update path

Claude Tap documents three update options. Choose the one matching how you installed it:

claude-tap update

uv tool upgrade claude-tap

pip install --upgrade claude-tap

Do not run all three automatically. If you installed with uv, the uv upgrade command keeps the update associated with that tool installation. If you installed with pip, run the pip upgrade through the same Python environment that owns the existing package. The project also provides the claude-tap update option.

After updating, repeat the executable check, launch a low-risk trace, and verify the runtime-provided viewer URL again. Do not assume an existing process changes version while it is running.

Stop and restart the live process

When Claude Tap is running in the foreground, end the active agent session and interrupt the process from its terminal, commonly with Ctrl+C. Confirm that the command exits before treating the viewer as stopped. If an agent child process remains active in your environment, close it through its normal process controls rather than assuming that closing a browser tab stopped the underlying session.

To restart the live viewer, return to the intended project and run the same verified launch command again:

claude-tap

Read the newly printed viewer address after every restart. If the host or port changes, update the Localtonet target before restarting remote access. Test the local page before testing the public URL.

Trace storage and cleanup

The primary evidence confirms that each run writes a local trace session, but the supplied documentation extract does not establish one universal storage path or a verified cleanup command. Storage details can depend on the installed version and operating environment. Do not invent a directory, delete broad Python application folders, or assume that uninstalling the package removes trace data.

Before cleanup, inspect the current repository documentation and the runtime output of your installed version for its trace location and supported retention behavior. If the application identifies a session directory, close Claude Tap before modifying it, preserve anything required for an approved investigation, and delete only the specific reviewed sessions according to your organization's retention policy. Treat backups and copied trace artifacts as sensitive too.

If no authoritative cleanup procedure is available for your version, leave the data in place until you can identify the correct session files safely. Removing unknown files from a Python environment or user configuration directory can damage unrelated settings without proving that all trace copies were erased.

Choose between local review, a live tunnel, and export

Local review is the lowest-exposure option. Use it whenever the person investigating the trace can work on the machine running Claude Tap. No public route is required, and you avoid making an active development viewer reachable from the internet.

A live HTTP tunnel is appropriate only when an authorized remote reviewer needs the interactive viewer and your environment provides suitable access controls. The Localtonet route works while our selected client is connected, the tunnel is running, and the upstream Claude Tap viewer is available. Stopping any one of those components ends the usable path.

Claude Tap's repository states that a trace session can be exported to a self-contained HTML viewer for review or archiving. However, the supplied primary evidence does not include the exact export command, its arguments, output location, or a validation procedure. For that reason, this tutorial does not provide a guessed command or present export as a completed step.

If you want to use export, consult the current Claude Tap repository documentation for the command supported by your installed release. Validate any resulting artifact offline by confirming that it opens in a browser, displays the intended session, does not depend on the live viewer process, and contains no unapproved sensitive material. Until those checks are complete, treat export as an available project capability rather than a verified outcome of this procedure.

Share a verified live viewer with Localtonet

Proceed only after the local viewer works and the exposure decision has been approved. With Localtonet, our client establishes an outbound connection to a relay server. This lets you expose the selected local HTTP service without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

An HTTP tunnel points to a local IP address and port on, or reachable from, the Localtonet client device. The tunnel then provides a public HTTPS address. This is a transport path to the Claude Tap viewer. It does not automatically add user accounts, passwords, identity checks, authorization rules, or trace-specific permissions.

The Localtonet HTTP tunnel documentation contains the current dashboard workflow. Confirm current server choices, domain options, and plan availability in the product rather than inferring them from this example.

Understand loopback binding before choosing the client device

A viewer advertised on 127.0.0.1 or localhost is normally reachable only from the same device. If the Localtonet client runs on that device, target the exact locally verified loopback endpoint. If our client runs on another computer, that computer cannot use its own 127.0.0.1 to reach Claude Tap because loopback refers back to itself.

The supplied Claude Tap evidence does not establish a supported command for changing the viewer's bind interface. Do not invent one. If the viewer is loopback-only, place the Localtonet client on the same host or consult current Claude Tap documentation for an approved binding option. Do not weaken host firewall or network controls merely to make the topology convenient.

Security and shutdown checklist

Trace inspection can reveal the exact context supplied to an agent. Apply the same care you would use for source archives, diagnostic bundles, terminal recordings, or incident evidence.

When the review ends, close the remote browser, stop the Localtonet tunnel, verify that it is no longer running, end the Claude Tap process, and apply the approved trace-retention procedure. Deleting the tunnel is appropriate when the configuration will not be reused. Remember that copied screenshots or exported files are separate artifacts and remain available until handled independently.

Troubleshooting the complete request path

claude-tap is not found

Confirm that installation completed in the environment currently used by the shell. If you installed with pip inside a virtual environment, activate that environment before running the command. If you installed with uv, ensure the uv tool executable directory is available on your PATH. Open a new terminal after changing PATH configuration, then retry:

claude-tap --help

Avoid repeatedly installing into different environments. Multiple copies can make upgrades unpredictable because the shell may execute a different installation from the one you updated.

The Python version is too old or inconsistent

Compare python --version and python3 --version if both exist. Then confirm that pip belongs to the intended interpreter or use the isolated uv tool installation. Claude Tap requires Python 3.11 or newer, so an older interpreter cannot be corrected by changing the tunnel configuration.

Claude Code does not launch through Claude Tap

Run claude auth status and claude doctor, then test the ordinary claude command without Claude Tap. If the underlying client fails, fix its installation, authentication, settings, or network access first. Once Claude Code works normally, return to the low-risk project and run claude-tap.

The agent starts, but no trace appears

Confirm that you interacted with the client launched through Claude Tap rather than opening a separate normal agent session. Generate a new harmless prompt and wait for it to complete. Use the live viewer created by that same running process. If you selected another client, verify its current --tap-client value against the repository because integrations use different modes.

The viewer does not start or its page does not load locally

Keep the Claude Tap terminal open and inspect its output for startup errors and the actual viewer address. Make sure the process has not exited. Enter the printed URL exactly in a browser on the same device. If the browser cannot load it locally, stop troubleshooting Localtonet because the upstream service is not yet healthy.

The viewer works only through localhost

This indicates a loopback-reachability constraint. Run the Localtonet client on the same device and use the exact verified loopback target. If the Localtonet client is on another device, its localhost refers to that other device, not to the Claude Tap host. The available evidence does not verify a Claude Tap bind-address command, so consult the current project documentation rather than guessing a flag.

The Localtonet tunnel exists but no public URL is active

Creation and startup are separate lifecycle actions. Select the tunnel and use the Start button. Confirm that the associated Localtonet client is connected. A saved configuration does not carry traffic until it is started.

The tunnel starts, but the public page fails

Work from the inside out. First reload the Claude Tap viewer locally. Next compare the Localtonet target host and port with the current runtime URL. Then confirm that the selected Localtonet client is the device that can reach that endpoint and remains connected. Finally, confirm that the tunnel is running rather than merely configured.

If Claude Tap was restarted, it may have printed a different endpoint. Update the tunnel target to match the newly verified address before trying the public URL again.

The public URL opens the wrong application

Stop the tunnel immediately. A wrong local port can route to an unrelated service on the same device. Recheck the complete runtime-provided Claude Tap URL, correct the HTTP target, verify the viewer locally once more, and only then restart the tunnel.

The page loads, but traces are stale or incomplete

Confirm that the displayed session belongs to the current Claude Tap process and test project. Generate one distinctive, non-sensitive interaction and verify that it appears. If it does not, ensure the agent session was launched through the same Claude Tap instance rather than through an ordinary client terminal.

A trace contains sensitive information

Stop the Localtonet tunnel immediately and end sharing. Do not rely on changing or hiding the URL. Follow your incident-handling and retention requirements for any person, screenshot, browser cache, export, or copied artifact that may have received the data. Common authentication-header redaction does not remove every possible secret or confidential value.

An update appears not to take effect

Check whether the shell is finding a uv installation, a virtual-environment executable, or a different pip installation. Update through the method that owns the active executable, stop the old running process, start Claude Tap again, and repeat local verification. A running process does not become the new version merely because package files were updated elsewhere.

Frequently asked questions