---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: agent_data
excerpt: |
  DuckDB Community Extensions
  A DuckDB extension written in Rust for querying, analysing and inspecting AI coding agents history. Read conversations, plans, todos, history, and usage stats directly from your local agent data directories.

extension:
  name: agent_data
  description: A DuckDB extension written in Rust for querying, analysing and inspecting AI coding agents history. Read conversations, plans, todos, history, and usage stats directly from your local agent data directories.
  version: 0.4.0
  language: Rust
  build: cargo
  license: MIT
  excluded_platforms: "wasm_mvp;wasm_eh;wasm_threads;linux_amd64_musl"
  requires_toolchains: "rust"
  maintainers:
    - axsaucedo
    - asubbarao

repo:
  github: axsaucedo/agent_data_duckdb
  ref: 54d875a303e3269bff3bba2aa86bc2b188bcf48e

docs:
  hello_world: |
    -- How many conversations have I had with Claude?
    SELECT COUNT(DISTINCT session_id) AS sessions,
           COUNT(*) AS total_messages
    -- Calling the functions without params defaults to Claude folder.
    FROM read_conversations();

    -- What did I work on this week?
    SELECT date, message_count, tool_call_count
    FROM read_stats()
    ORDER BY date DESC
    LIMIT 7;

    -- Which tools does github copilot use most?
    SELECT tool_name, COUNT(*) AS uses
    FROM read_conversations('~/.copilot')
    WHERE tool_name IS NOT NULL
    GROUP BY tool_name
    ORDER BY uses DESC
    LIMIT 10;

    -- What are my active todos in my custom claude path?
    SELECT content, status
    FROM read_todos('~/work_folder/.claude')
    WHERE status != 'completed'
    ORDER BY item_index;

    -- Compare activity across Claude and Copilot
    SELECT source, COUNT(DISTINCT session_id) AS sessions, COUNT(*) AS messages
    FROM (
        SELECT * FROM read_conversations(path='~/.claude')
        UNION ALL
        SELECT * FROM read_conversations(path='~/.copilot')
    )
    GROUP BY source;

  extended_description: |

    **Supported agents:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`~/.claude`), Claude Desktop, [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) (`~/.copilot`), [Cursor](https://cursor.com) (`source='cursor'`), [OpenAI Codex](https://openai.com/codex) (`~/.codex`), [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`~/.gemini`), and [xAI Grok](https://x.ai) (`~/.grok`, `source='grok'`).

    Written in 🦀 Rust.

    ### Default Behavior

    When called **without arguments**, each function reads from its provider's default path:

    | Function | Default path | Detected as |
    |----------|-------------|-------------|
    | `read_conversations()` | `~/.claude` | Claude Code |
    | `read_plans()` | `~/.claude` | Claude Code |
    | `read_todos()` | `~/.claude` | Claude Code |
    | `read_history()` | `~/.claude` | Claude Code |
    | `read_stats()` | `~/.claude` | Claude Code |

    To read another agent's data, pass the path explicitly:

    ```sql
    FROM read_conversations(path='~/.copilot');
    FROM read_conversations(path='~/.codex');
    FROM read_conversations(path='~/.gemini');
    FROM read_conversations(path='~/.grok');
    ```

    ### Available Functions

    All functions accept two optional parameters:
    - **`path`** — data directory path (default: `~/.claude`). Auto-detected from folder structure (`projects/` → Claude, `session-state/` → Copilot, dated `sessions/` → Codex, `tmp/` + `installation_id` → Gemini).
    - **`source`** — explicit provider override: `'claude'`, `'claude-desktop'`, `'copilot'`, `'cursor'`, `'codex'`, `'gemini'`, or `'grok'`. Use when auto-detection fails or for non-standard directory layouts.

    Every table includes a **`source`** column (`'claude'` or `'copilot'`) as the first column.

    > `read_conversations([path (opt)], [source (opt)])`

    ## Join Keys

    Tables can be joined within the same source:

    ```sql
    -- Conversations ↔ History (via session_id)
    SELECT c.*, h.display
    FROM read_conversations(path='~/.claude') c
    JOIN read_history(path='~/.claude') h ON c.session_id = h.session_id;

    -- Cross-source: always filter by source
    SELECT * FROM (
        SELECT * FROM read_conversations(path='~/.claude')
        UNION ALL
        SELECT * FROM read_conversations(path='~/.copilot')
    ) WHERE source = 'copilot';
    ```

    | Join | Left Key | Right Key | Notes |
    |------|----------|-----------|-------|
    | conversations <-> history | `session_id` | `session_id` | Same source only |
    | conversations <-> todos | `session_id` | `session_id` | Same source only |
    | conversations <-> plans | `slug` | `plan_name` | Claude only |
    | conversations <-> history | `project_path` | `project` | Claude only |

    For full documentation, see the [GitHub repository](https://github.com/axsaucedo/duckdb-claude-ext).

extension_star_count: 31
extension_star_count_pretty: 31
extension_download_count: 15142
extension_download_count_pretty: 15.1k
image: '/images/community_extensions/social_preview/preview_community_extension_agent_data.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

<div class="extension_compatibility_table"></div>

| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ✅ | ❌ | ✅ | ✅ | ❌ |
| Linux ARM64 | ✅ | ❌ | ✅ | ✅ | ❌ |
| macOS AMD64 | ✅ | ❌ | ✅ | ✅ | ❌ |
| macOS ARM64 | ✅ | ❌ | ✅ | ✅ | ❌ |
| Windows AMD64 | ✅ | ❌ | ✅ | ✅ | ❌ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ❌ | ❌ | ❌ | ❌ | ❌ |

### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

|   function_name    | function_type |                               description                               |                             comment                             |                                 examples                                 |
|--------------------|---------------|-------------------------------------------------------------------------|-----------------------------------------------------------------|--------------------------------------------------------------------------|
| read_conversations | table         | Read conversation messages and tool calls from AI coding agent sessions | Supports Claude Code and GitHub Copilot CLI with auto-detection | [SELECT * FROM read_conversations(path='~/.claude') LIMIT 10;]           |
| read_plans         | table         | Read plan and strategy markdown files from agent sessions               | Claude: plans/*.md, Copilot: session-state/*/plan.md            | [SELECT plan_name, file_size FROM read_plans();]                         |
| read_todos         | table         | Read todo and checklist items with status tracking                      | Claude: todos/*.json, Copilot: checkpoint markdown checklists   | [SELECT content, status FROM read_todos() WHERE status != 'completed';]  |
| read_history       | table         | Read command and prompt history                                         | Claude: history.jsonl, Copilot: command-history-state.json      | [SELECT display FROM read_history() ORDER BY line_number DESC LIMIT 10;] |
| read_stats         | table         | Read daily activity statistics (message, session, and tool call counts) | Currently Claude only — returns empty for Copilot               | [SELECT date, message_count FROM read_stats() ORDER BY date DESC;]       |
| read_events        | table         | NULL                                                                    | NULL                                                            | NULL                                                                     |

### Overloaded Functions

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

This extension does not add any types.

### Added Settings

<div class="extension_settings_table"></div>

This extension does not add any settings.