# Processing Cline Logs from JSON Task Files in ADR: A Technical Deep Dive

> Learn how ADR processes Cline logs from JSON task files. Our ClineParser normalizes raw logs into AgentEvent objects for unified AI assistant security detection.

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

---

**The ADR (Agentic AI Detection and Response) Sensor normalizes raw Cline (Claude Dev) extension logs from [`api_conversation_history.json`](https://github.com/uber/ADR/blob/main/api_conversation_history.json) files into standardized `AgentEvent` objects through the `ClineParser` class, enabling unified security detection across AI coding assistants.**

The uber/ADR open-source project provides telemetry collection infrastructure for agentic AI tools. Its **Sensor** component specifically handles the ingestion and normalization of conversation logs generated by the Cline (formerly Claude Dev) VS Code extension. By processing these JSON task files, ADR converts proprietary log formats into a unified schema that downstream security detectors can analyze without agent-specific logic.

## Architecture of the Cline Log Processing Pipeline

The **Sensor** component implements a layered architecture for collecting and normalizing Cline telemetry. All agent-specific parsers inherit from `BaseParser` defined in [`Sensor/adr_sensor/parsers/base_parser.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/parsers/base_parser.py), which guarantees a consistent `parse_all()` entry point across implementations.

The concrete Cline implementation resides in [`Sensor/adr_sensor/parsers/cline_parser.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/parsers/cline_parser.py). This parser transforms raw conversation histories into `AgentEvent` objects defined in [`Sensor/adr_sensor/schemas/agent_event_schema.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/schemas/agent_event_schema.py), while timestamp normalization utilities in [`Sensor/adr_sensor/utils/timestamp_utils.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/utils/timestamp_utils.py) ensure temporal consistency.

## Step-by-Step Processing of api_conversation_history.json

The `ClineParser` executes an eight-stage pipeline to extract actionable intelligence from Cline session files.

### Locating Task Directories

The parser automatically resolves platform-specific storage locations. On macOS, it targets `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/tasks`, while Linux systems use `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/tasks`. The implementation selects the appropriate path by checking filesystem existence.

### Reading Conversation History

Each task subfolder contains an [`api_conversation_history.json`](https://github.com/uber/ADR/blob/main/api_conversation_history.json) file storing serialized message arrays. The parser loads these arrays, where each object contains a `role` field (either "user" or "assistant") and nested content structures.

### Extracting Textual Content

The `extract_text_from_content()` method filters environment-detail blocks and parses inner `<task>` markup to produce clean text strings. This step separates meaningful prompts from metadata wrappers, yielding normalized user queries and assistant responses.

### Detecting MCP Tool Usage

Assistant messages undergo scanning for the custom `<use_mcp_tool>` XML-like tag via `extract_mcp_tools()`. A regular expression extracts `server_name`, `tool_name`, and JSON-encoded arguments, which the parser converts into `ToolUsage` dataclasses for security analysis.

### Building Agent Events

For each processed task folder, the parser constructs an `AgentEvent` with:

- `timestamp`: Derived from file modification time and converted to UTC via `normalize_timestamp()`
- `source`: Set to `"cline"`
- `session_id`: Formatted as `cline_<folder-name>`
- `chat_history`: A list of `ChatMessage` objects including any discovered `ToolUsage` instances

### Filtering Noise

The `has_meaningful_content()` method evaluates each `AgentEvent` to discard empty conversations or error-only exchanges. This ensures downstream detectors receive only actionable telemetry containing substantive agent interactions.

## Working with ClineParser: Code Examples

Initialize the parser and process all available Cline sessions:

```python
from adr_sensor.parsers.cline_parser import ClineParser

# Initialize the parser (handles OS-specific path resolution)

parser = ClineParser()

# Parse every available Cline session on the host

events = parser.parse_all()

# Example: iterate and print a concise summary

for ev in events:
    print(ev.get_summary())

```

Serialize events for storage or transmission to detection pipelines:

```python
import json

# Serialize the first event

json_payload = events[0].to_json()
print(json_payload)

```

## Summary

- The **ClineParser** in [`Sensor/adr_sensor/parsers/cline_parser.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/parsers/cline_parser.py) normalizes Cline extension logs into the unified `AgentEvent` schema.
- Processing targets the [`api_conversation_history.json`](https://github.com/uber/ADR/blob/main/api_conversation_history.json) files stored in platform-specific task directories under `saoudrizwan.claude-dev/tasks`.
- The parser extracts **MCP tool usage** via XML tag detection and converts these into structured `ToolUsage` objects.
- **Timestamp normalization** ensures UTC-aware temporal ordering across heterogeneous environments using file modification times.
- The `has_meaningful_content()` filter eliminates noise before events reach downstream security detectors.

## Frequently Asked Questions

### How does ADR locate Cline log files across different operating systems?

The `ClineParser` implements automatic path resolution by checking platform-specific directories. It first attempts the macOS path at `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/tasks`, then falls back to the Linux path at `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/tasks` based on filesystem existence checks.

### What information is extracted from the api_conversation_history.json files?

The parser extracts user prompts and assistant responses from the message array, specifically filtering content through `extract_text_from_content()` to remove environment wrappers. It additionally scans assistant messages for `<use_mcp_tool>` tags to identify Model Context Protocol invocations, capturing server names, tool names, and arguments as structured data.

### Why does ADR use file modification times instead of timestamps within the JSON?

ADR uses file modification times converted to UTC-aware datetime objects via `normalize_timestamp()` in [`Sensor/adr_sensor/utils/timestamp_utils.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/utils/timestamp_utils.py). This approach guarantees temporal ordering integrity across heterogeneous environments, as internal JSON timestamps may lack timezone information or consistent formatting, whereas filesystem metadata provides reliable sequence data for replay-style analysis.

### How can I integrate Cline log processing into my own security pipeline?

Import `ClineParser` from `adr_sensor.parsers.cline_parser` and invoke `parse_all()` to retrieve a list of `AgentEvent` objects. Each event exposes `to_json()` for serialization and `get_summary()` for human-readable inspection. The unified schema ensures these events integrate seamlessly with existing ADR detectors or custom analysis tools expecting `AgentEvent`, `ChatMessage`, and `ToolUsage` structures.