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

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 (lines 68-71), the CLI parses this flag and passes it directly to the AgentObserver constructor:

# 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 (lines 23-31), these session files respect the --output-dir flag rather than using the hidden cache directory:

# 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 (lines 59-66) handles format-specific serialization after directory resolution:

# 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 (lines 43-61) stores this path for all subsequent operations:

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:

# 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 (lines 68-71): CLI argument parsing and AgentObserver instantiation
• 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: 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}