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

The ADR (Agentic AI Detection and Response) Sensor normalizes raw Cline (Claude Dev) extension logs from 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, which guarantees a consistent parse_all() entry point across implementations.

The concrete Cline implementation resides in 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, while timestamp normalization utilities in 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 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:

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:

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 normalizes Cline extension logs into the unified AgentEvent schema.
• Processing targets the 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. 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.

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