---
title: "Add Caveman to a Helicone workflow"
description: "Keep Helicone as the baseline while you test one Caveman optimization. This avoids losing the visibility you need to evaluate the change. The first experiment can happen at a command-output boundary, "
canonical: https://caveman.so/switch/helicone
last-updated: 2026-09-07
---

# Add Caveman to a Helicone workflow

Keep Helicone as the baseline while you test one Caveman optimization. This avoids losing the visibility you need to evaluate the change. The first experiment can happen at a command-output boundary, with Helicone still receiving your normal model requests.

A later telemetry migration is separate. There is no documented automatic import of Helicone sessions and logs into Caveman Platform in this guide.

## Capture the current behavior

Save the client setup and identify whether you use Helicone's gateway or a logging integration. Record how session IDs, user identifiers, custom properties, and model names appear in the dashboard. Keep one successful task and one failed task as reference examples.

Write down what is retained. If prompts or tool results contain sensitive data, the trial must follow the same capture permissions. Running a second tool is not authorization to copy every historical message into it.

## Start at one expensive tool

Install the Caveman CLI and binaries on your test machine:

```bash
npm install -g @caveman-ai/cli
caveman setup --install
caveman setup
```

Wrap a command whose output your agent normally reads:

```bash
caveman shrink -- npm test
```

Use the same command in the baseline and candidate. This changes the tool output, while the agent can retain its existing Helicone gateway configuration. Confirm that the agent has a supported way to call Caveman recovery before using a lossy view.

For a saved transcript, validate the store directly:

```bash
caveman shrink --file test-output.txt
caveman retrieve YOUR_RECOVERY_HANDLE > recovered.txt
cmp test-output.txt recovered.txt
```

Replace the handle placeholder with the actual value from the first command. A no-op result may not produce a handle. The [recovery reference](https://docs.caveman.so/docs/proxy/recoverable) explains that distinction.

## Keep the two runs easy to find

Use your existing Helicone session or custom-property mechanism to distinguish the baseline and candidate. Do not reuse one run identifier for both. The model-call logs should still connect to the application task and its outcome.

Check whether the gateway records the transformed request. That is the request the provider saw. Preserve the original task fixture separately for the experiment, rather than pretending the compressed request is the original source.

Run the task's correctness check and inspect the complete session. A low-input request followed by repeated retries may cost more overall. Follow [cost per completed task](/guides/measure-agent-cost) to include those attempts.

## Test a direct-provider path only if needed

If the goal includes replacing gateway access, create a separate development client with the destination provider's key. Helicone's own gateway key does not authenticate to that provider.

For a caller using the OpenAI Python client:

```python
import os
from openai import OpenAI

candidate = OpenAI(
    base_url="http://127.0.0.1:8787/openai/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)
```

Start the loopback listener first:

```bash
caveman tools config set think.mode compress
caveman start
```

Use the direct provider's model ID and keep the application on the same host as the listener. This path does not inherit Helicone's gateway logging, fallbacks, or account billing. Recreate any required application instrumentation before considering a production move.

Validate streaming and tool calls on the actual protocol. Proxy-side recovery has narrower eligibility than a native wrapped agent; pass-through is an expected result where recovery cannot be proven.

## Plan a Platform pilot with a sample

For Caveman Platform, agree on an ingestion contract before exporting data. Send a permitted sample and verify parent-child relationships, model identity, usage, and final task status in the destination. Compare counts with the source over the same time window.

Preserve historical Helicone records until you have a retention and access plan. A successful sample does not prove that all custom properties or archived sessions transfer.

## Roll back

Use the original command output or restore the Helicone client configuration. Start a fresh session if the candidate introduced recovery handles. Keep the local store for in-flight tasks and disable only the test integration you added.

Sources: [Helicone quickstart](https://docs.helicone.ai/getting-started/quick-start), [Caveman provider routes](https://docs.caveman.so/docs/proxy/providers), and [the comparison](/compare/helicone).