Coding Agent Configuration

Coding agent tracing reads its settings from two places: a JSON file written by the installer, and environment variables that override it. This page lists every setting and explains how they combine.

How settings are resolved

For any setting, the first source that provides a value wins:

An environment variable, if set.
The stored value in ~/.atatus/harness/config.json.
The built-in default.

Boolean environment variables must be the exact string true to turn something on. Any other value, including 1, yes, and TRUE with a trailing space, is read as false. This matters most for ATATUS_TRACE_ENABLED, where a typo turns tracing off silently.

The configuration file

The installer writes ~/.atatus/harness/config.json. A typical file looks like this:

{
  "harnesses": {
    "claude-code": {
      "api_key": "lic_xxxxxxxxxxxxxxxx",
      "project_name": "acme-backend-team",
      "target": "atatus"
    }
  },
  "user_id": "your.name@example.com",
  "logging": {
    "_v": 2
  }
}

Settings are stored per tool under harnesses, so two tools on one machine can report to different projects. Values outside harnesses, such as user_id, apply to every tool.

Key	Description
`harnesses.<tool>.api_key`	Your Atatus license key.
`harnesses.<tool>.project_name`	The project the data is grouped under.
`harnesses.<tool>.endpoint`	Where traces are sent. The installer fills this in, so the file may show it even though you never set it. Change it only if you are running Atatus on-premise.
`user_id`	Identifies who produced the trace. Optional.
`logging`	The three capture settings. See Privacy.

Core environment variables

These are the settings you are most likely to use:

Variable	Default	Description
`ATATUS_API_KEY`	none	Your Atatus license key. Required.
`ATATUS_PROJECT_NAME`	none	The project name. Required.
`ATATUS_OTLP_ENDPOINT`	set by the installer	Where traces are sent. Set it only if you are running Atatus on-premise.
`ATATUS_USER_ID`	none	Identifies the person producing traces.
`ATATUS_TRACE_ENABLED`	`true`	Set to any other value to stop sending traces.

Capture settings

These three control what content is recorded. Privacy explains them in full:

Variable	Default	Description
`ATATUS_LOG_PROMPTS`	`true`	Record the text of your prompts.
`ATATUS_LOG_TOOL_DETAILS`	`true`	Record commands, file paths, and URLs.
`ATATUS_LOG_TOOL_CONTENT`	`false`	Record file contents and command output.

Troubleshooting settings

Use these when something is not working:

Variable	Default	Description
`ATATUS_DRY_RUN`	`false`	Write spans to the log instead of sending them.
`ATATUS_VERBOSE`	`false`	Print progress to stderr as hooks run.
`ATATUS_TRACE_DEBUG`	`false`	Dump full span payloads to the log.
`ATATUS_LOG_FILE`	per tool	Override the log file path.
`ATATUS_TRANSCRIPT_WAIT_MS`	`300`	How long to wait for the tool to finish writing its transcript. Set to `0` to disable the wait.

ATATUS_TRANSCRIPT_WAIT_MS exists because some tools write their transcript file just after the hook fires. Without a short wait, the last response is occasionally missing its token counts. Raise it if you see turns with no token data on a slow machine.

Project naming

The project name is the grouping key, so it decides how your data is organised. Pick a convention before rolling tracing out to a team.

Goal	Convention	Example
See one combined view for a team	One shared name	`acme-platform-team`
Compare usage between developers	Name plus person	`acme-platform-alice`
Separate work by repository	Name plus repository	`acme-checkout-service`

Changing the project name creates a new project rather than renaming the old one, and past traces stay with the old name. Decide the convention first, because splitting or merging history later is not possible.

If you want per-developer attribution inside a single shared project, set ATATUS_USER_ID instead of changing the project name. That keeps one project while still letting you filter by person.

Set variables per tool

Environment variables apply to whatever process reads them, so where you set them decides their scope. To trace one session differently, export the variable in that shell before starting the tool:

export ATATUS_LOG_TOOL_CONTENT=true
claude

To change a setting permanently, edit ~/.atatus/harness/config.json or re-run the installer.

Next steps

Privacy explains the capture settings in detail.
Uninstall covers removing tracing.

​How settings are resolved

​The configuration file

​Core environment variables

​Capture settings

​Troubleshooting settings

​Project naming

​Set variables per tool

​Next steps

How settings are resolved

The configuration file

Core environment variables

Capture settings

Troubleshooting settings

Project naming

Set variables per tool

Next steps