Install claude-tap and Access Traces with Localtonet

What claude-tap does and where Localtonet fits

claude-tap is a local proxy and trace viewer for AI coding agents. Depending on the selected client integration, it can run a command-line agent through a proxy, use a forward proxy, or watch supported local application transcripts. Its browser viewer helps developers inspect the context involved in an agent run instead of relying only on what appeared in a terminal, editor, or chat panel.

Captured information can include system prompts, conversation history, messages, tool definitions, tool calls, tool results, reconstructed streaming responses, token usage, and differences between adjacent requests. This is useful when an agent behaves differently across turns, unexpectedly invokes a tool, loses context, or sends parameters that do not match the developer's assumptions.

The normal workflow is local. Install claude-tap, start a supported agent through the appropriate integration, generate a controlled request, and inspect the resulting session in the local viewer. A hosted dashboard is not required for this documented workflow, and trace sessions can be exported to a self-contained HTML viewer for review or archiving.

Localtonet is not required to capture or inspect traces on the development machine. It becomes relevant only when an authorized person needs to reach the live HTTP viewer from another location or device. Our client establishes an outbound connection to a Localtonet relay and routes a public HTTPS address to the configured local IP address and port. This does not require inbound router port forwarding, a public IP address, firewall changes, or VPN setup.

Creating a Localtonet tunnel does not start it. The tunnel becomes reachable only after it is started, and it remains available only while the selected Localtonet client is connected and the tunnel is running. That lifecycle is useful for short debugging sessions, but it is not a substitute for viewer authentication or another effective access restriction.

Version baseline and supported clients

This revision uses the primary claude-tap repository and its v0.1.145 release as the project baseline. Commands and client names were checked against the repository documentation on August 20, 2026. claude-tap changes rapidly, so compare this baseline with the current release before using the tutorial with a newer version.

The v0.1.145 documentation lists Claude Code, Codex CLI, Codex App, Gemini CLI, Grok Build CLI, DeepSeek Harness, Kimi CLI, Kimi Code CLI, MiMo Code, OpenCode, OpenClaw, Pi, Hermes Agent, Cursor CLI and IDE Agent, Qoder CLI, Antigravity CLI, and CodeBuddy CLI. Integrations do not all capture data the same way. Some launch a command through a proxy, some use forward proxy mode, and others watch local transcripts.

Prerequisites and decisions before installation

claude-tap requires Python 3.11 or newer and the coding agent you intend to trace. For the default workflow in this guide, that agent is Claude Code. Install and authenticate the agent through its normal supported process first. claude-tap does not replace the client or supply credentials for its upstream provider.

You also need either uv or pip. The project recommends installing claude-tap as a uv tool, while pip remains a documented alternative. Choose one method and use its corresponding upgrade path later. Maintaining uv and pip copies at the same time can make it unclear which executable the shell launches.

Check the available Python interpreter without changing your environment:

python --version

python3 --version

Use the command that exists on your system and confirm that it reports Python 3.11 or newer. If neither command exists or the version is too old, install or select a suitable Python environment before proceeding. Platform-specific Python installation commands are intentionally omitted because they vary across operating systems and package managers.

Remote access has additional prerequisites. Install the Localtonet client on the claude-tap machine or on another device that can reach the viewer's local IP address and port. You will need a device-specific Localtonet authentication token and a relay server or region offered by the current dashboard. Never copy a token into an article, screenshot, trace, public command example, or source repository.

Most importantly, decide how authorization will be enforced. The v0.1.145 evidence used for this guide does not establish a built-in viewer authentication feature. If you cannot confirm effective viewer authentication or put another tested access restriction in front of it, stop after local verification and do not start a publicly reachable tunnel.

Install claude-tap with uv or pip

Recommended method: uv tool installation

If uv is installed and available in the current shell, use the project's recommended command:

uv tool install claude-tap

Wait for the command to complete successfully. If the shell cannot find claude-tap afterward, follow the executable-path guidance printed by uv. You may need to open a new terminal after updating the shell path. The exact path depends on the operating system and uv installation, so use local installer output rather than a copied path.

Alternative method: pip installation

The documented pip alternative is:

pip install claude-tap

Confirm that this pip belongs to a Python 3.11 or newer environment. On systems with multiple Python installations, the pip, python, and claude-tap commands may resolve to different environments. If installation succeeds but the command is unavailable, inspect the package and scripts locations reported by the selected Python environment.

Do not treat a successful package installation as proof that capture or remote access works. The meaningful test is to start claude-tap, run a supported client, generate a non-sensitive request, locate the live viewer using observed runtime behavior, and confirm that the trace appears locally.

Start claude-tap and capture a controlled trace

For Claude Code, run claude-tap in place of the normal claude command:

claude-tap

The v0.1.145 documentation states that the live browser viewer is enabled by default. Keep the terminal open while tracing. Use the launched agent to submit a small, non-sensitive test request. A disposable directory and harmless prompt are preferable for the first run because they limit what can enter the resulting trace.

Pass Claude Code arguments through claude-tap

Arguments after -- are passed to Claude Code. The project documents this model-selection example:

claude-tap -- --model claude-opus-4-6

Model availability depends on the underlying Claude Code account and configuration. claude-tap passes the argument through but does not grant model access.

The project also documents continuing the previous Claude Code conversation:

claude-tap -c

Claude Code permission flags can also be passed after --. Flags that skip permission prompts are unrelated to observability and may allow tools to run without interactive approval. Do not weaken agent permissions merely to test trace capture.

Select another documented client

Use --tap-client for non-default integrations. These examples are documented for the v0.1.145 baseline:

claude-tap --tap-client codex
claude-tap --tap-client codexapp
claude-tap --tap-client gemini -- -p "hello"
claude-tap --tap-client grok -- -p "hello"
claude-tap --tap-client dsh -- --profile headless "Reply OK"
claude-tap --tap-client kimi
claude-tap --tap-client kimi-code
claude-tap --tap-client mimo
claude-tap --tap-client pi
claude-tap --tap-client cursor
claude-tap --tap-client qoder -- -p "hello" --permission-mode dont_ask
claude-tap --tap-client agy
claude-tap --tap-client codebuddy

Install and configure the selected client independently. The examples do not imply that every integration uses the same capture mechanism or exposes identical information.

For Cursor, the documented default can launch cursor-agent, watch live transcripts, and provide the dashboard. To watch Cursor IDE Agent transcripts without launching the CLI, use:

claude-tap --tap-client cursor --tap-no-launch

Disable the live viewer when it is not needed

The documented option for capture without the live viewer server is:

claude-tap --tap-no-live

This mode cannot be used for the Localtonet HTTP workflow because it intentionally removes the live HTTP service that would otherwise be the tunnel target.

Custom Claude Code upstreams

claude-tap can detect custom Claude Code upstreams from ANTHROPIC_BASE_URL, ANTHROPIC_BEDROCK_BASE_URL, or ANTHROPIC_VERTEX_BASE_URL in the environment or Claude settings. Local proxy upstreams are also supported. The project recommends using --tap-target only when intentionally overriding the detected target.

Avoid changing upstream configuration during the first installation test. Verify the normal detected path first. If Claude Code works without claude-tap but fails while tracing, inspect the existing environment and Claude settings for an unexpected upstream value.

Discover and verify the live viewer endpoint

This is the critical handoff between claude-tap and Localtonet. The available v0.1.145 documentation confirms that the live browser viewer is enabled by default, but it does not establish a fixed port, universal bind address, guaranteed startup message, or one required endpoint-discovery method. Therefore, do not assume that claude-tap prints a particular URL or that a port copied from another installation is valid.

Determine the endpoint from behavior you can directly observe in your own environment. If claude-tap opens the viewer automatically, use the complete address shown in that browser's address bar. If the running release prints a viewer address, use that output. If neither occurs, consult the current project documentation or release behavior before proceeding. Do not guess a port merely to make the Localtonet form accept a value.

The Localtonet client must be able to reach the recorded host and port. Running claude-tap and our client on the same machine is the simplest topology. If they run on different devices, the viewer must listen on an address reachable from the Localtonet client device. The supplied project evidence does not document a claude-tap bind-address option, so this guide does not invent one.

Configure a Localtonet HTTP tunnel

Proceed only after the viewer loads locally, captures a controlled request, and has an effective access-control plan. A browser-based HTTP viewer belongs in the Localtonet HTTP tunnel family. HTTP tunnels can use a random subdomain, a custom subdomain where supported, or a custom domain. Available options can vary by plan and current dashboard configuration.

The current documented sequence is to run the Localtonet client, open the HTTP Tunnel configuration, select the process type, select the device authentication token and relay server, enter the local IP address and port, and then start the tunnel. Use the options offered by the current dashboard rather than hardcoding an old server code or unavailable process type.

Creating the configuration does not make it active. The Start action is a separate lifecycle step. For current interface details, see the Localtonet HTTP tunnel documentation. If you choose a custom domain, take exact DNS requirements from the current documentation and dashboard rather than applying instructions from an unrelated tunnel.

Verify the remote path

Open the assigned HTTPS address from an authorized remote browser. Confirm that the expected viewer loads, then generate another harmless local request and verify that it appears remotely. Test the access restriction from an unauthorized browser or session as well. A successful authorized request and a denied unauthorized request are both required security checks.

If an unauthorized client can retrieve the viewer, stop the tunnel immediately. Do not distribute the address or rely on its obscurity. Correct the access-control design and repeat both tests before starting the tunnel again.

Protect remotely accessible traces

The safest default is to keep the viewer local. Remote access should have a defined purpose, approved recipients, and a short lifetime. Examples include reviewing an agent failure from another trusted device or allowing an authorized teammate to inspect a specific debugging session.

HTTPS protects data in transit to the public endpoint, but it does not decide who may view the content. If the application accepts every request, anyone who obtains the address may be able to retrieve traces. The available claude-tap evidence does not establish a built-in authentication feature, so verify the installed release directly.

If the viewer does not provide adequate authorization, place an authenticated layer in front of it before public exposure. The exact setup depends on the reverse proxy, identity provider, operating system, and organizational policy, so this guide does not prescribe an unverified universal configuration. The required outcome is clear: unauthenticated requests must be denied, authorized users must receive only the access they need, and both outcomes must be tested.

Routine operation, shutdown, exports, and upgrades

Start a review session

Start claude-tap before the agent activity you need to inspect. Confirm that the local viewer still works and that its observed endpoint has not changed. Review the access-control layer, then start the existing Localtonet tunnel only if remote access is required.

Monitor both processes during the session. If claude-tap stops, capture and the local viewer stop. If the Localtonet client disconnects or the tunnel is stopped, the public endpoint becomes unavailable even while the local viewer continues to run.

End the session in the safe order

Stop the Localtonet tunnel first so remote access ends immediately. Close the remote browser session, then finish the coding-agent activity and terminate claude-tap according to the normal terminal behavior of your environment. Delete the tunnel configuration if it will not be reused.

Review retained trace artifacts and handle them under the same data-classification rules used for source code, logs, prompts, debugging captures, and customer information. Ending the live tunnel does not delete files already stored locally or copies made by authorized viewers.

Use an export when live access is unnecessary

claude-tap documents self-contained HTML export for trace sessions. A fixed artifact may be preferable when another person needs to review completed evidence rather than observe a live run. The export can still contain sensitive trace data, so share and retain it only through an approved mechanism.

Upgrade claude-tap

The project documents a built-in update command:

claude-tap update

For a uv tool installation, it also documents:

uv tool upgrade claude-tap

For a pip installation, use:

pip install --upgrade claude-tap

Use the command that corresponds to the active installation. After upgrading, repeat the complete local test. Start the client, observe how the new release exposes its viewer, load it locally, generate a controlled request, and confirm that the trace appears. Recheck authentication behavior before restarting the public tunnel because viewer output, integrations, or runtime behavior can change between releases.

Claude Code editor integration

For the Claude Code Visual Studio Code extension, the project documents setting Claude Code: Claude Process Wrapper to claude-tap. On Windows, use the full claude-tap.exe path if Visual Studio Code cannot locate the executable.

Test editor capture locally before remote access. Start a controlled interaction from the extension, confirm that it creates a trace, and then use only the verified viewer host and port as the Localtonet target.

Troubleshooting installation, capture, and tunnel problems

The claude-tap command is not found

Confirm that the selected installation command completed successfully. For uv, inspect its tool path guidance and verify that the executable directory is available to the current shell. For pip, confirm that the expected Python environment is active and that its scripts directory is included in the executable search path.

Avoid repeatedly reinstalling through different package managers. Identify the intended executable and keep one installation authoritative.

Python is too old

claude-tap requires Python 3.11 or newer. Select or install a newer environment and repeat installation with the package manager associated with that interpreter.

No viewer address can be identified

Confirm that --tap-no-live was not used. Review the browser and all runtime output produced by the active process. The v0.1.145 documentation does not guarantee a fixed port or a specific reporting message. If the release does not expose enough information to identify a working local endpoint, stop the tunnel procedure and consult the current project documentation or issue tracker. Do not guess.

The viewer loads but remains empty

Generate a fresh request after starting claude-tap. Confirm that the intended client was selected and that it successfully contacted its provider. The viewer can be healthy while the agent is idle, unauthenticated, launched through an unsupported path, or configured with an unexpected upstream.

For Claude Code custom upstreams, inspect ANTHROPIC_BASE_URL, ANTHROPIC_BEDROCK_BASE_URL, and ANTHROPIC_VERTEX_BASE_URL in the environment and Claude settings. Use --tap-target only for an intentional override.

The local viewer works but the public URL does not

Check each layer in order. Confirm that claude-tap is still running. Reopen the local viewer from the device running the Localtonet client. Confirm that our client is connected and associated with the intended token. Verify that the HTTP target exactly matches the observed local host and port. Finally, confirm that the tunnel was explicitly started.

If the Localtonet client runs on another machine, a viewer bound only to the claude-tap machine's loopback interface may not be reachable. The available project evidence does not establish a supported bind-address option. Running both processes on the same device avoids this cross-device target problem in the simplest setup.

The public page loads but assets or updates fail

Test the same action through the local viewer. If it fails locally, troubleshoot claude-tap first. If it works locally but fails remotely, record the failed browser request and application output. Confirm that the tunnel type is HTTP and still points to the endpoint that passed local testing.

An unauthorized browser can load traces

Stop the tunnel immediately. Do not rely on changing or hiding the URL. Add or correct an effective authorization layer, inspect the exposed traces for confidential data, and follow the incident-handling process required by your organization.

The tunnel stops unexpectedly

A Localtonet tunnel is available only while the selected client is connected and the tunnel is running. Check the Localtonet client process, device connectivity, and tunnel state. Also confirm that claude-tap is running. Restoring the tunnel will not restore a local HTTP target that has exited.

Frequently asked questions