---
title: "Set Up Agent Traces"
source: https://docs.autohand.ai/tutorials/set-up-agent-traces
---

# Set up agent traces

Install the trace companion, enable metadata sync, confirm it is running, and view cross-agent activity in Autohand Console.

Beginner 10 min

## What you'll do

-   Install release-matched `autohand` and `ahtraces` binaries.
-   Choose explicit metadata sync while keeping full content off.
-   Verify the local daemon and supported coding-agent discovery.
-   Open the correct personal or Team account in Autohand Console.
-   Stop future sync or delete your uploaded trace data.

## Before you start

-   You need a paid Autohand Code plan. Team members can use the Team plan's Console trace view.
-   You need permission to install or upgrade a command-line tool on your computer.
-   Have at least one supported coding agent installed, such as Autohand, Claude Code, Cursor, Codex, or GitHub Copilot.
-   Know which personal or Team account should receive the cloud metadata.

The monitor is off by default. Nothing in this tutorial starts monitoring until Step 3.

## Step 1: Install the trace companion

The official shell and PowerShell installers include the separately built `ahtraces` executable.

### macOS or Linux

```bash
curl -fsSL https://autohand.ai/install.sh | sh
```

### Windows PowerShell

```powershell
iwr -useb https://autohand.ai/install.ps1 | iex
```

If Autohand is already installed, running the installer again upgrades both binaries. Confirm the companion is available:

```bash
autohand --version
ahtraces --version
```

## Step 2: Sign in to the paid account

Cloud sync needs an authenticated Autohand account. Start Autohand and run `/login`, or use the standalone command:

```bash
autohand login
```

Complete the browser authorization. Team users should later confirm that the intended Team is selected in the Console account switcher.

## Step 3: Enable metadata sync

Enable local monitoring and metadata only cloud sync:

```bash
autohand --traces-on
```

The equivalent commands are `autohand traces on`, `ah traces on`, and `ahtraces on`. This mode sends pseudonymous timing, agent, model, provider, reasoning, token, relationship, and outcome metadata. Trace ingestion and storage does not count against Autohand API usage.

Full content is a separate choice

Do not select redacted full traces unless you intend to upload bounded prompts, responses, reasoning, and tool parts. Change modes from `/settings`. The command above selects metadata only.

## Step 4: Verify the daemon

```bash
ahtraces status
# You can also run either CLI alias:
ah traces status
autohand traces status
```

The status should report that `ahtraces` is running. Run a short session in one or more supported agents, then check status again if you are troubleshooting collection.

## Step 5: Inspect the local Work Map

Before checking the cloud view, confirm the local adapters can derive aggregate activity:

```bash
autohand discovery map --since 30d
autohand discovery map --agent autohand,codex --json
```

This local scan makes no network request and excludes prompts, responses, reasoning, code, paths, repository identities, commands, tool input and output, session IDs, and credentials.

## Step 6: View traces in Console

1.  Open [console.autohand.ai/traces](https://console.autohand.ai/traces).
2.  Use the account switcher to select the personal or Team account you signed in with.
3.  Review the cross-agent summary by harness, model, provider, and reasoning effort.
4.  Open a synchronized Autohand session to inspect its ordered trace when one is available.

Sync is incremental. If a newly completed session is missing, wait briefly, refresh, and confirm that `ahtraces status` still reports a running daemon.

## Use traces with a Team plan

Each teammate makes their own local consent choice. In Console, select the Team account before reviewing account-scoped activity. A member can remove only trace data uploaded by their own identity; the deletion action leaves other Team members' traces in place.

Team owners and admins can pair this workflow with the [Team member management guide](https://docs.autohand.ai/guides/manage-team-members) when onboarding or offboarding a teammate.

## Stop future sync or delete existing data

Disable monitoring and remove derived local trace data:

```bash
autohand --traces-off
# Equivalent:
autohand traces off
ah traces off
ahtraces off
```

Turning tracing off does not delete data already uploaded. To delete it:

1.  Open [Account in Console](https://console.autohand.ai/account).
2.  Find **Agent trace data** and select **Delete agent trace data**.
3.  Type `DELETE TRACES` and confirm.

This permanently removes your trace metadata and any uploaded full content from the selected account. Source session files on your device remain.

## Completion checkpoint

-   `autohand --version` and `ahtraces --version` both work.
-   `ahtraces status` reports a running daemon.
-   The local Work Map shows at least one recognized harness after you run a session.
-   [Autohand Console](https://console.autohand.ai/traces) shows the cross-agent summary for the intended account.

See [Agent traces and Work Map](https://docs.autohand.ai/working-with-autohand-code/agent-traces) for all 19 supported agents, consent details, command behavior, and troubleshooting.