dash0-configure

---
name: dash0-configure
description: 'Set up or finish setting up the Dash0 → Claude Code telemetry integration by writing ~/.claude/dash0-agent-plugin.local.md (or the project-local equivalent). Use when the user wants to configure Dash0, enable telemetry, paste credentials, fix an inactive plugin install, or act on a "dash0: no team configured" message — spans carry no dash0.team.name until the team name is set.'
---

# Configure Dash0

Write the config file the plugin reads on session start. The file holds every plugin option in YAML frontmatter.

## Trigger

The user wants to configure or reconfigure the Dash0 plugin. Two common shapes:

- **First-time setup.** They have an OTLP URL and an auth token, or the session said `dash0: telemetry is not active`.
- **Finishing setup.** Telemetry works, but the session said `dash0: no team configured`. Offer this once per session, then leave it alone unless the user brings it up.

## Before you start

When telemetry is connected and only `TEAM_NAME` is missing, use **Team-only recovery** below and stop. Do not enter the full setup workflow.

If the user prefers OS keychain–backed storage for the auth token over a plaintext file, direct them to `/plugin` → **Installed** → **dash0** → **Configure** instead of running this skill, then stop.

Note the precedence order (highest first) so the user isn't surprised when a value doesn't apply:

1. `pluginConfigs` in enterprise-managed settings — users cannot override these
2. `pluginConfigs` in user-level `~/.claude/settings.json`, which is what `/plugin → Configure` writes
3. Project-level config file (`.claude/dash0-agent-plugin.local.md`)
4. User-level config file (`~/.claude/dash0-agent-plugin.local.md`)
5. `DASH0_*` environment variables

If the user already has values set via the UI or managed settings, the file this skill writes is ignored for those keys. Ask them to clear the UI config first, or use the UI directly.

> [!IMPORTANT]
> `auth_token` follows that list like every other key: a token in `pluginConfigs` or managed settings wins over one in the file. Earlier releases were the other way round, because the wrapper loaded the file's token into the variable the UI writes. So writing `auth_token` for a user on a managed rollout does not override the org token — it has no effect until the UI value is cleared. Say that rather than promising an override.

## Team-only recovery

Use this path when telemetry is already connected and only the team name is missing, including in Claude Desktop. Keychain-backed authentication does not prevent this file edit. Do not redirect this recovery to Plugin UI. This path does not establish Desktop support for the full setup workflow or identify its reporter client.

1. Respect higher-precedence `team_name` values in managed or user `pluginConfigs`. If one is set, a file edit cannot override it. Explain that conflict and stop without clearing or changing those settings. Values for other keys do not prevent a team-only edit.
2. Select the active project file, `.claude/dash0-agent-plugin.local.md`, if it exists. Otherwise select `~/.claude/dash0-agent-plugin.local.md`, or `%USERPROFILE%\.claude\dash0-agent-plugin.local.md` on Windows. Do not ask for a scope or create a project file. The project file completely shadows the user file, so editing the user file while a project file exists has no effect.
3. Ask only for the team name. Do not ask about dataset, other options, or credentials. Do not retrieve, copy, move, or display credentials from another file, Plugin UI, managed settings, environment, or keychain.
4. Do not read the whole selected file, because that puts `auth_token` into the transcript. Inspect only the frontmatter markers and `team_name` lines, for example `grep -nE '^(---|team_name:)' <file>`, or `Select-String -Pattern '^(---|team_name:)' <file>` in PowerShell. Make the edit with a line-level command, not the Edit tool, which requires a full Read first. Use `sed -i ''` on macOS, `sed -i` on Linux, and a PowerShell read-modify-write that prints nothing on Windows. Preserve all other settings and content verbatim. Update the first `team_name` entry inside the YAML frontmatter, since the reader uses the first occurrence, or add it before the closing `---` if absent. If the file is empty or has no frontmatter, add a `---` block at the top that holds the `team_name` line. If no file exists, create a user-level file containing only YAML frontmatter with `team_name: "<TEAM_NAME>"`. Do not add credential keys.
5. Show only the target path and the proposed `team_name` change. Ask for confirmation, then apply that edit. Preserve existing file permissions. For a new file, restrict it to its owner as described in full workflow step 6.
6. Tell the user the team name was saved. In Claude Code, tell them to run `/reload-plugins`, and that the `dash0: no team configured` warning should be gone next session. Do not say you reloaded the plugins or verified the warning. Do not promise that reopening a Desktop session reloads the file. Stop here.

## Scope

Ask whether to write user-level (`~/.claude/dash0-agent-plugin.local.md`, applies to all projects) or project-level (`.claude/dash0-agent-plugin.local.md`, only the current project — overrides the user-level file entirely, does not merge). Default to user-level unless the user asks for project-only.

On Windows the user-level file is `%USERPROFILE%\.claude\dash0-agent-plugin.local.md`; the project-level path is the same as everywhere else.

> [!WARNING]
> A wrong or differently scoped token in either file fails as a silent 401, with no error in the session. A project-level file is the riskier one, because it is the level a user is most likely to point at a one-off token, and it replaces the user-level file whole rather than merging with it. Prefer user-level unless the user needs a different dataset or team for one project.

## Workflow

1. If the target file already exists, read it and show the user the current values with the `auth_token` masked (show only the last 4 chars). Ask whether to overwrite. If they decline, stop.

2. Decide whether credentials are part of this run. Telemetry is off when the session said `dash0: telemetry is not active`; it already works when the session said `dash0: connected`, and the user needs only the missing options.

   **When telemetry is off,** ask for both of these, one at a time. Do not invent a value the user did not give.

   - **OTLP URL** (required) — Dash0 OTLP ingress, e.g. `https://ingress.us-west-2.aws.dash0.com`
   - **Auth token** (required) — treat as a secret; do not echo it back in later messages

   **When telemetry already works,** never ask the user for the token again. Find out where it currently comes from, because the answer decides what the target file must contain. Read the target file, and read the other level's file too (the user-level one if the target is project-level, and the reverse).

   | Where the credentials are now | What to write |
   |---|---|
   | In the target file | Carry its `otlp_url` and `auth_token` lines over verbatim. |
   | In the other level's file, and the target is a different level | Copy that file's `otlp_url` and `auth_token` into the target verbatim. The two files do not merge, so a target without them turns telemetry off on the next session. Tell the user the token will exist in a second file, and stop if they would rather set the option user-level instead. |
   | In neither file | They come from the plugin UI, managed settings, or the keychain. Write neither key. A file token would replace a working credential with a plaintext copy, and a wrong or differently scoped one fails as a silent 401. |

3. Ask for the recommended values. These are what most installs are missing, so ask explicitly rather than defaulting past them.

   - **Team name** (`team_name`) — tags every span with `dash0.team.name`. Without it, spans cannot be attributed to a team. Suggest the user's team as they would name it in Dash0.
   - **Dataset** (`dataset`) — which Dash0 dataset the data lands in. Leave it out and the backend picks its default. There is no literal `default` value to write; an empty value means "no dataset header".

4. Offer the remaining options as one batch the user can decline in a single answer. Only ask about them if the user wants to change a default.

   | Key | Effect | Default |
   |---|---|---|
   | `agent_name` | Reported as `service.name` | `claude-code` |
   | `omit_io` | Omit prompt content and tool inputs/outputs | `true` |
   | `omit_user_info` | Hash `user.name` and drop `user.email` | `false` |
   | `omit_identity_fallback` | Report only a real `git config user.name`, never the OS account | `false` |
   | `enabled` | Set to `false` to turn the plugin off for this scope without uninstalling | `true` |
   | `auth_token_keychain_service` | macOS keychain service to read the token from instead of storing it | — |
   | `auth_token_keychain_account` | Optional account for that keychain item | — |

   For every key above except `enabled`, `true` and `1` are true and any other non-blank value is false, so write `true` or `false` and nothing else. `enabled` is the one key the binary reads strictly: only the literal `false` turns the plugin off.

5. Show the user the exact file you are about to write, with `auth_token` masked to its last 4 chars, and ask them to confirm. Write it only after they agree. Omit every key whose value is blank, and include the `otlp_url` and `auth_token` lines exactly as step 2 settled them.

   ```
   ---
   otlp_url: "<OTLP_URL>"
   auth_token: "<AUTH_TOKEN>"
   dataset: "<DATASET>"
   team_name: "<TEAM_NAME>"
   # plus any keys the user chose in step 4, in the same key: "value" form
   ---
   ```

6. Restrict the file to its owner, so the token isn't readable by other accounts.

   - macOS and Linux: `chmod 600 <file>`
   - Windows: `powershell -NoProfile -Command 'icacls "<file>" /inheritance:r /grant:r "$($env:USERNAME):(F)" "SYSTEM:(F)"'`

   Do not use `chmod` on Windows, even though the Bash tool runs under Git Bash. It sets the read-only bit and leaves the NTFS permissions untouched, so the token stays readable by every account on the machine.

   Keep the PowerShell wrapper and the single quotes. Git Bash rewrites the bare `/inheritance:r` and `/grant:r` flags as file paths, and `%USERNAME%` expands in `cmd.exe` only.

7. Tell the user:

   > Configuration written. Run `/reload-plugins` to apply. On next session start you should see `dash0: connected`.

   Re-running this skill later takes effect on the next `/reload-plugins` — no Claude Code restart needed.

   The `dash0: no team configured` warning cannot be silenced. If the user deliberately runs without a team, say so plainly rather than looking for a way to hide it.

From dash0hq/dash0-agent-plugin at 7753ecc, shown as plain text under its license: Apache-2.0 (permissive). The license text is in LICENSE.

• SKILL.md11 KB · 0acccc91b195

1 file, 11 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.