# How to Set Up ADR Sensor with Custom Output Directories: Configuration and CLI Guide

> Learn to set up ADR Sensor with custom output directories using the --output-dir flag or Python's AgentObserver. Configure ADR for your project's needs.

- Repository: [Uber Open Source/ADR](https://github.com/uber/ADR)
- Tags: how-to-guide
- Published: 2026-08-07

---

**Use the `--output-dir` flag when running `adr-sensor` to specify any writable directory, or instantiate `AgentObserver` directly with a `Path` object in Python.**

The ADR Sensor from Uber's ADR repository provides flexible output management for system telemetry data. Whether you're integrating into CI pipelines, managing multiple environments, or organizing archival storage, controlling where the sensor writes its files is essential. This guide covers the command-line interface, Python API, and internal mechanics that govern output directory configuration.

## CLI Configuration with `--output-dir`

The `adr-sensor` command accepts a `--output-dir` argument that overrides the default `./output` directory. In [`Sensor/adr_sensor/cli.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/cli.py) (lines 68-71), the CLI parses this flag and passes it directly to the `AgentObserver` constructor:

```bash

# Default behavior: creates and writes to ./output

adr-sensor

# Custom directory for all output files

adr-sensor --output-dir ./my-adr-output

# Absolute path for system-wide logging

adr-sensor --output-dir /var/log/adr

```

The argument accepts any valid filesystem path. The sensor creates the directory if it doesn't exist and verifies write permissions before processing begins.

## incremental Processing and Session Files

When using `--save-sessions` mode, the sensor writes individual JSON files per session. According to the source code in [`Sensor/adr_sensor/observer.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/observer.py) (lines 23-31), these session files respect the `--output-dir` flag rather than using the hidden cache directory:

```bash

# Save each session to its own file in a custom location

adr-sensor --save-sessions --output-dir /tmp/adr_sessions

# Subsequent runs skip existing sessions in that directory

adr-sensor --save-sessions --output-dir /tmp/adr_sessions

```

The incremental mode checks for existing files in the specified output directory, making it safe to resume interrupted collections.

## Combining with Output Formats

The `--output-dir` flag works with any supported format. The `save_to_file` method in [`Sensor/adr_sensor/observer.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/observer.py) (lines 59-66) handles format-specific serialization after directory resolution:

```bash

# JSON-L format to custom directory

adr-sensor --output-format jsonl --output-dir /data/adr/jsonl

# Standard JSON with explicit path

adr-sensor --output-format json --output-dir /backup/adr/$(date +%Y-%m-%d)

```

## Python API: Direct AgentObserver Configuration

For embedded usage, instantiate `AgentObserver` with a `Path` object. The constructor in [`Sensor/adr_sensor/observer.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/observer.py) (lines 43-61) stores this path for all subsequent operations:

```python
from pathlib import Path
from adr_sensor.observer import AgentObserver

# Configure custom output directory

results_dir = Path("/home/user/adr_results")
observer = AgentObserver(output_dir=results_dir)

# Process and save data

entries, system_cfg = observer.ingest_all()
observer.save_to_file(entries, system_cfg, output_format="jsonl")

```

Method-level overrides are available if you need exceptions to the default:

```python

# Most files go to results_dir, but sessions go elsewhere

observer.save_sessions_to_individual_files(
    entries, 
    output_dir=Path("/tmp/session_cache")  # Override per-call

)

```

## Key Implementation Details

The output directory logic spans several source files:

- **[`Sensor/adr_sensor/cli.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/cli.py)** (lines 68-71): CLI argument parsing and `AgentObserver` instantiation
- **[`Sensor/adr_sensor/observer.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/observer.py)**: Core directory handling in `AgentObserver.__init__` (lines 43-61), file writing in `save_to_file` (lines 59-66), and session management in `save_sessions_to_individual_files` (lines 35-41)
- **[`Sensor/adr_sensor/utils/timestamp_utils.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/utils/timestamp_utils.py)**: Safe filename generation for timestamped session files

The `AgentObserver` creates the output directory during initialization and uses `Path.mkdir(parents=True, exist_ok=True)` to ensure the path is ready before any data collection begins.

## Common Configuration Patterns

| Use Case | Command |
|----------|---------|
| Daily log rotation | `adr-sensor --output-dir /var/log/adr/$(date +%Y%m%d)` |
| CI artifact collection | `adr-sensor --output-dir $CI_PROJECT_DIR/artifacts/adr` |
| Shared team storage | `adr-sensor --output-dir /shared/adr/$(hostname)` |
| Ephemeral testing | `adr-sensor --output-dir $(mktemp -d)` |

## Summary

- **`--output-dir`** controls where ADR Sensor writes all output files
- Default fallback is `./output` when the flag is omitted
- **Incremental mode** (`--save-sessions`) respects the same directory setting
- **Python API** accepts `Path` objects via `AgentObserver(output_dir=...)`
- Directory creation and validation happen automatically at initialization

## Frequently Asked Questions

### What happens if the custom output directory doesn't exist?

The `AgentObserver` constructor creates the directory automatically using `mkdir(parents=True, exist_ok=True)`. No manual setup is required.

### Can I change the output directory between sessions in incremental mode?

Yes. The sensor reads the output directory at startup and checks for existing session files there. Changing `--output-dir` between runs starts a fresh collection in the new location.

### Does the cache directory respect `--output-dir`?

Session cache files in `$XDG_CACHE_HOME/adr_sensor` are separate from output files. However, when using `--save-sessions` with `--output-dir`, the individual session JSON files are written to the specified output directory, not the cache.

### What permissions does ADR Sensor need for custom directories?

The running user needs **write and execute permissions** on the target directory. The sensor validates this during `AgentObserver` initialization and raises `PermissionError` if unavailable.