ConvoManager Documentation

ConvoManager is a robust desktop application designed specifically for exploring, viewing, and editing chat conversation datasets stored in JSONL format.

Built for high-performance navigation and manual manipulation - ideal for curating fine-tuning data for large language models, or inspecting synthetic chat outputs.

---

Table of Contents

• 1. Features
• 2. Supported Conversation Formats
  • Standard OpenAI Format
  • Gemini Format
  • Chain-of-Thought Reasoning
  • Tool Calls & Function Calling
  • Tool Results & Execution Logs
  • Other Supported Schema Features
• 3. The File Browser (Left Pane)
• 4. The Dataset Panel (Right Pane)
  • 4a. Dataset Mode - Working with datasets
    • The Filter Bar
    • Metadata Columns
    • Extracting columns from the 1st (JSON system) message
  • 4b. Single Conversation Mode - Viewing and Editing Conversations
    • Navigation & Local Search
    • Chat View
    • Text View
    • JSON View
• 5. Settings & Maintenance

---

1. Features

• Intelligent schema detection: Automatically detects and parses all common OpenAI-compatible conversation schemas, including standard OpenAI, Gemini, Llama, Deepseek, Qwen, Anthropic and others.
• Massive file support: Seamlessly open, navigate and edit .jsonl files containing millions of lines without crashing or consuming excessive memory, thanks to byte-offset indexing and lazy-loading architecture.
• Smart caching: Scanned dataset data is remembered and constantly updated by the application, enabling files to load significantly faster in subsequent sessions without re-scanning the file.
• JSON syntax issue detection and highlighting: ConvoManager can automatically scan every conversation for JSON validity, as well as validity of escaped JSON in message content. It can also highlight these issues separately in Dataset Table Mode.
• Dataset Mode or Single Conversation Mode: Switch between a table of all conversations in a dataset, where you can do bulk actions, or a single conversation mode where you can view and edit the contents and metadata of individual conversations.
• Three views for individual conversations: Flawlessly switch between visual Chat Bubbles, text (with Raw/Pretty-print modes), and an interactive JSON Tree editor for the same conversation. Edit your conversations in any view.
• Dataset filtering: Instantly filter the entire dataset based on search keywords or the presence of JSON syntax issues.
• Bulk actions: Select rows and use the Action Strip for bulk deletion and exporting of selected conversations. Or filter the dataset and export the filtered results from the menu.
• Dynamic metadata columns: Column names can be automatically extracted from embedded metadata objects or from the first message's JSON content.
• Role & turn counting customization: Tailor canonical role mappings (System, Assistant, and User) and configure custom turn-counting settings (handling of initial assistant and final unfinished turns) to support any custom schema on a per-file basis, ensuring accurate turn-counting.

---

2. Supported Conversation Formats

ConvoManager natively understands a wide range of real-world LLM conversation schemas — without any configuration. It automatically detects the format of each conversation when the file is opened, and renders every message type with appropriate visual styling in the Chat View.

Supported File Formats

ConvoManager reads JSONL (JSON Lines) files line-by-line. A comprehensive overview of all supported schemas is covered below.

Handling Nested JSON Strings

When embedding raw JSON inside a message string value, you must properly escape internal quotes (\") so the outer JSON structure stays valid.

Incorrect (Breaks JSONL structure): {"messages": [{"role": "assistant", "content": "Output: {"key": "value"}"}]}

Correct (Escaped for JSON string): {"messages": [{"role": "assistant", "content": "Output: {\"key\": \"value\"}"}]}

---

Standard OpenAI Format

The most common format. A conversation object has a "messages" key containing an array of messages, each with a "role" and "content". An optional "metadata" object can be added at the root level for per-conversation metadata.

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi there! How can I help?"}
  ],
  "metadata": {"category": "greeting", "split": "train"}
}

Any additional keys on a message object (e.g. "custom_meta", "model_id") are preserved without modification when saving.

---

Gemini Format

Google Gemini datasets use a "contents" key instead of "messages", and messages use "parts" arrays instead of a single "content" string. The model role is "model" instead of "assistant".

{
  "contents": [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "The capital of France is Paris."}]}
  ]
}

Any extra keys on either the message object or the individual parts (e.g. "custom_parts_meta") are preserved without modification.

---

Chain-of-Thought Reasoning

ConvoManager supports all major chain-of-thought and reasoning formats used across model families. Reasoning content is rendered in a collapsible grey "Thinking Process" box above the assistant's final response in Chat View.

DeepSeek R1 / OpenAI o-series (reasoning_content field)

Used by DeepSeek R1, OpenAI o1/o3, and any model following the reasoning_content convention:

{
  "role": "assistant",
  "reasoning_content": "The user is asking about the speed of light. I know it's approximately 299,792,458 m/s.",
  "content": "The speed of light is approximately 299,792 km/s."
}

Qwen / Llama (Inline <think> or <thought> XML tags)

Used by Qwen reasoning models, some Llama instruct variants, and any format that embeds thoughts inline:

{
  "role": "assistant",
  "content": "<thought>\nThe derivative of x^2 by the power rule is 2x.\n</thought>\nThe derivative of x^2 is 2x."
}

Both <think> and <thought> tag names are supported interchangeably.

Anthropic Claude (thinking content block)

Used by Claude 3.5+ extended thinking datasets, where reasoning is a structured block inside the content array:

{
  "role": "assistant",
  "content": [
    {"type": "thinking", "thinking": "The user wants to add 15 and 27. Let me calculate: 15 + 27 = 42."},
    {"type": "text", "text": "15 + 27 = 42."}
  ]
}

Google Gemini 2.0 ("thought": true part)

Used by Gemini 2.0 Flash Thinking and similar reasoning-capable Gemini models:

{
  "role": "model",
  "parts": [
    {"text": "Let me think about this step by step...", "thought": true},
    {"text": "The answer is 42."}
  ]
}

---

Tool Calls & Function Calling

ConvoManager supports all major tool/function calling schemas. Tool calls are rendered in Chat View as parameter tables showing the function name and arguments.

OpenAI / Qwen (tool_calls array)

The most common format, used by OpenAI, Qwen, and many fine-tuned models. The "tools" key at the root (listing the available function definitions) is also supported and preserved:

{
  "messages": [
    {"role": "user", "content": "What's the weather in Paris?"},
    {
      "role": "assistant",
      "tool_calls": [{
        "id": "call_1",
        "type": "function",
        "function": {"name": "get_weather", "arguments": {"city": "Paris"}}
      }]
    }
  ],
  "tools": [
    {"type": "function", "function": {"name": "get_weather", "description": "Get weather for a city", "parameters": {}}}
  ]
}

Anthropic Claude (tool_use content block)

{
  "role": "assistant",
  "content": [
    {"type": "thinking", "thinking": "I should search for this."},
    {"type": "tool_use", "id": "toolu_abc", "name": "search", "input": {"query": "standard model physics"}}
  ]
}

Google Gemini (function_call part)

{
  "role": "model",
  "parts": [{
    "function_call": {"name": "query_db", "args": {"query": "SELECT * FROM users"}}
  }]
}

---

Tool Results & Execution Logs

ConvoManager renders tool results and execution outputs as terminal-style monospace log boxes in Chat View.

OpenAI (tool role)

{"role": "tool", "tool_call_id": "call_1", "content": "{\"temperature\": 18, \"unit\": \"celsius\"}"}

Anthropic (tool_result content block)

{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_abc",
    "content": "The Standard Model of particle physics describes..."
  }]
}

Google Gemini (function_response part)

{
  "role": "user",
  "parts": [{
    "function_response": {
      "name": "query_db",
      "response": {"rows": [{"id": 1, "username": "alice"}]}
    }
  }]
}

Llama / Code Interpreter (ipython or environment role)

Used by Llama instruct models when executing code via the built-in Python interpreter:

{"role": "ipython", "content": "56088\n"}

---

Other Supported Schema Features

• Direct message array: The root of the JSON line can be a bare array of messages: [{"role": "user", ...}, ...]
• Single standalone message: A single message object without a wrapper: {"role": "user", "content": "Hello"}
• Mixed-content messages: A single message can combine multiple block types in the same content array (e.g. a tool_result block and a text block together in a user message).
• JSON object as message content: If a message's "content" field is a JSON object (a dict) rather than a string, ConvoManager automatically parses and renders it as an interactive JSON table. This is common in system messages used to pass structured persona data or configuration.

---

3. The File Browser (Left Pane)

The File Browser allows you to navigate your local folders and select datasets for viewing.

• Browsing a Folder: Go to File > Browse Folder... (or press CTRL+O) to select the directory containing your JSONL files, which will show in the File Browser.
• Recent Folders: Access your recently opened directories via the File > Recent Folders menu to quickly jump back to different data collections.
• Loading JSONL Dataset Files: Click on any .jsonl file in the File Browser to instantly load the dataset into the Dataset Panel, on the right.
• Creating a New Dataset: Go to File > New Dataset (or press CTRL+N) to create a completely new, empty JSONL dataset file.
• Saving a Dataset as a Copy: Go to File > Save Dataset As... (or press CTRL+SHIFT+S) to clone the active dataset file under a new name.
• Exporting Selected Conversations: Go to File > Export Selection (or press CTRL+SHIFT+E), or click on Export Selection on the Action Strip to save only your currently selected conversations to a new JSONL file.
• Exporting a Filtered Dataset: Go to File > Export Filtered Results (or press CTRL+E) to save only the conversations matching your current filter results to a brand-new JSONL file.
• Deleting a Dataset: Right-click on any .jsonl file in the File Browser to see a context menu allowing you to delete the dataset file.

---

4. The Dataset Panel (Right Pane)

The Right Pane is where you interact with your data. It switches between a high-level Dataset Mode (table with all conversations in the dataset) and a detailed Single Conversation Mode.

4a. Dataset Mode - Working with datasets

When you select a file, ConvoManager defaults to the Dataset Mode. It shows all conversations in the loaded file, and allows you to filter the conversations, make selections, show special columns, etc.

The Filter Bar

The filter bar at the top of the table allows you to filter and validate your dataset in real-time.

• Keyword Filter: Typing text here instantly hides all rows that do not contain the matching text within the message content.
• Validity Filters: Use the radio buttons (All / Valid Only / Invalid Only) to quickly isolate records with issues. Filtering combines with keywords for precise data cleaning.

Validation & Data Integrity

During loading of a dataset, ConvoManager automatically scans every conversation for data integrity.

• Corrupt JSON: If a line cannot be parsed as JSON, it is highlighted with a light red background in the table, and the exact position of the issue is highlighted with a red background in Single Conversation Mode (both in Chat, Text and JSON View). This cannot be disabled as it is essential for proper functioning of the application.
• Syntax Issues in Escaped JSON Content: JSON syntax of escaped JSON strings in the content of a message can also be parsed for syntax issues. This parsing can be disabled in the settings. If the content of a message appears to be JSON, but cannot be parsed as JSON, it will then be highlighted in the table with a yellow background, and the position of the issue will be highlighted with a red background in Single Conversation Mode (both in Chat, Text and JSON View). This highlighting can be disabled individually per dataset in Dataset Mode.

Bulk Manipulation & Selection

The Dataset Mode features a checkbox-driven selection system for performing operations on multiple rows at once.

• Checking Rows: Click the checkbox in the leftmost column to select conversations.

• Action Strip: When one or more rows are checked, an Action Strip appears at the top of the table:

  • Inverse Selection: Rapidly flip the selection state of all visible rows.
  • Export Selection: Save the checked rows to a brand-new JSONL file.
  • Delete Selected: Permanently remove the checked rows from the current file.

• Keyboard Shortcuts, Edit & Selection Menus: Manage your dataset even faster using the dedicated menus or keyboard shortcuts:

  • Select All (In Selection menu, or CTRL+A): Checks all currently visible rows.
  • Deselect All (In Selection menu, or CTRL+SHIFT+A): Unconditionally clears the selection of all rows.
  • Inverse Selection (In Selection menu, or CTRL+I): Inverts the checkbox state of all visible rows.
  • Export Selection (In Selection or File menu, or CTRL+SHIFT+E): Saves the checked rows to a brand-new JSONL file.
  • Insert New Conversation (In Edit menu, or CTRL+SHIFT+I): Instantly inserts a new empty conversation skeleton at the current position.
  • Delete Selected Rows (In Edit menu, or Delete key): Permanently deletes checked rows after confirmation.

Structural Editing & Empty Datasets

You can modify the structure of the dataset itself by adding new entries directly from the table:

1. Empty Datasets: When opening a completely empty dataset, a beautiful Empty State placeholder is shown. Simply click the "➕ Add First Conversation" button to append your first conversation skeleton to the file.
2. Right-click Insertion: Right-click any conversation row in the table view to choose Insert New Conversation Before #... or Insert New Conversation After #.... You can also right-click on empty viewport space to append a new conversation to the end of the file.
3. Edit Menu / Shortcut: Choose Edit > Insert New Conversation (or press CTRL+SHIFT+I) to instantly insert a new conversation. If a row is selected, it inserts before the selected row; if no row is selected, it appends to the end.
4. Automatic Updates: A blank conversation template (skeleton) is instantly added to the file, and the Dataset Mode table updates automatically, allowing you to draft conversations immediately.

Metadata Columns & Root Properties

Some datasets contain additional information stored outside the main messages array. ConvoManager automatically supports and extracts two types of metadata:

1. Metadata Dictionary: A dedicated "metadata" object at the root level.
2. Root Properties: Any standalone keys at the root level (e.g., "reward", "weight", "source").

  {
    "messages": [],    
    "metadata": { "category": "support", "split": "train" },
    "reward": 0.85,
    "weight": 1.0
  }

These are useful for storing information about the conversation that is not part of the conversation content itself. For example, a dataset of customer support tickets might store the customer's name and the date the ticket was created.

If your JSONL records contain a "metadata" object or any other root-level properties, all of those keys automatically become sortable columns in the dataset table:

Extracting columns from the 1st message JSON

For some specific use cases, the first message of each conversation in a dataset contains JSON data. In this case, it can be useful to see this data as separate columns in Dataset Mode. Note that the first message's role name does not matter; as long as the first message contains valid JSON content, the app will parse and display it as columns.

This feature must first be enabled globally in Settings → Metadata → "Enable 1st conversation 1st message JSON columns". Once enabled, a toggle appears in the top right corner of the Right Pane, labeled "Show columns from 1st conversation's 1st message JSON", which allows you to show or hide those columns per file.

• How it works: When enabled, the app parses the content of the first message in the very first conversation of the dataset. If it detects valid JSON, it automatically transforms those JSON keys into sortable columns in Dataset Mode.
• The Result: The entire table re-renders, reading that data from the first message of every other conversation and populating the new columns.

---

Role Customization

If a dataset uses customized role names in its schemas (e.g., "developer" instead of "system", "customer" instead of "user", or "agent" instead of "assistant"), ConvoManager allows you to map those values to the correct canonical categories. Since thinking processes and tool calls are natively and automatically identified, customization is kept extremely simple.

• Role Mapping Fields: Inside the Dataset Options card under the "Role customization" section, you can customize mappings for standard message roles:
  • System (default: system, developer)
  • Assistant (default: assistant, model, gpt, bot)
  • User (default: user)
• Restoring Defaults: Next to each text input, a small "Default" button allows you to instantly reset that specific role category back to its system standard.
• Save & Revert Mappings: When you type a change or click a default reset, a "Save Mappings" and "Revert" button group appears at the bottom. The new settings are only committed and applied once you click "Save Mappings". Clicking "Revert" restores your last saved mappings.
• Synonyms Support: Multiple options can be provided as a comma-separated list. Any of these values occurring in your dataset's conversations will be correctly identified as the canonical role (e.g., for bubble styling, collapsible rendering, and accurate turn-counting).
• Unrecognized Roles: If a message in a conversation uses a role name that is not specified in any of these mapping fields, it will be treated as an unmapped role. These messages will fall back to a default grey styling in the Chat View, and their label will be appended with a red "(Unrecognized)" indicator to make them instantly obvious.

Turn Counting Configurations

Directly next to the Role Customization box, the Turn counting options panel allows you to configure exactly how incomplete or trailing turns contribute to the total turn count: * Initial Assistant turn: How a leading assistant response (without user prompt) is counted (0.0 for don't count, 0.5 for half a turn, or 1.0 for a full turn). * Final incomplete turn: How a trailing user/system message that lacks a concluding assistant response is counted (0.0, 0.5, or 1.0).

---

4b. Single Conversation Mode - Viewing and Editing Conversations

Double-click any row in Dataset Mode to enter Single Conversation Mode.

Within Single Conversation Mode, three distinct editing sub-modes are available via the top tabs: Chat, TEXT, and JSON. When editing the contents of a conversation in any of these modes, the conversation also updates automatically in the other two modes.

Repairing Corrupt Data

If you open a row flagged as invalid (e.g., corrupt JSON): 1. The viewer automatically forces TEXT mode. 2. The Chat and JSON tabs are disabled to prevent crashes or loss of data from unparseable structures. 3. Fix the syntax in the TEXT editor and click Save. 4. The application re-validates the fixed line. If successful, all view modes are instantly unlocked, and the table highlight is removed.

Navigation & Local Search

The top navigation bar provides tools to move through the file:

• Back to Dataset Mode: Click the "Back to Dataset Mode" button to return to Dataset Mode.
• Previous / Next: Step through conversations one by one.

• Jump to index: Type a record number (e.g., 500) into the box and press Enter to jump straight to that conversation in the file.

• Local Search (Find): Use the 'Find' box to highlight matches only within the currently open conversation. Matches are highlighted in yellow across all view modes (Chat, TEXT, and JSON).

Chat View

The default mode for human-readable review, rendering messages as colored bubbles.

• Metadata Panel

  If a conversation has any metadata or root-level properties, a Metadata Panel appears at the top of the view. The panel cleanly visually separates Root Properties (standalone keys) from the Metadata Dictionary (keys inside the "metadata" object):

  

  If you want to edit the metadata:

  1. Click the Edit button (✏️) in the Metadata Panel.
  2. The panel expands to show a JSON Tree Editor containing a combined view of both your root properties and the metadata dictionary.
  3. Make your changes and click Save. The panel automatically collapses after saving to disk, correctly routing your changes back to their respective root or dictionary locations in the JSONL file.

  

• Smart JSON Content Parsing: If the text content of any message is valid JSON, ConvoManager parses it and builds a structured, multi-colored HTML table instead of showing a wall of unreadable text.

  

  

• Collapsible System Messages: System instructions are rendered distinctively and are collapsible via a toggle arrow, allowing you to hide massive system directives to focus on the dialogue.

  

• Collapsible Grey Thinking Bubbles: Chain-of-Thought reasoning steps are styled in a sleek grey box labeled "Thinking Process" which is collapsible, letting you clean up your workspace. All major reasoning formats are supported: DeepSeek R1 / OpenAI o-series (reasoning_content), Qwen / Llama inline <think> or <thought> XML tags, Anthropic Claude thinking blocks, and native Gemini 2.0 "thought": true parts.

• Sleek Tool Parameter Tables: Model requests for external function/tool execution are rendered as high-readability parameter tables showing the target function name and all its arguments. Supported across all formats: OpenAI/Qwen tool_calls, Anthropic tool_use blocks, and Gemini function_call parts.

• Terminal Monospace Logs: Tool results and execution outputs are displayed inside robust terminal-style log boxes. This covers OpenAI tool role messages, Anthropic tool_result blocks, Gemini function_response parts, and Llama code interpreter outputs (ipython / environment roles).

• Visual Action Step Rendering: Empty messages or messages containing custom metadata fields (like "custom_edge") are displayed with a 🎬 Action header. Any custom metadata keys inside the message object are parsed and rendered recursively as clean, nested tables inside the bubble.

• Inline Message Editing: Hover your mouse over any chat bubble and a quick-action menu appears.

  

• Editing text bubbles:

  1. Hover your mouse over any message bubble.
  2. Click the Edit button (✏️) that appears.
  3. Type your changes and click Save (or press CTRL+ENTER).

  

• Editing JSON content (Inline): If the message is a JSON object, the hover menu offers an Edit icon (✏️) that launches a visual JSON tree editor directly inside the chat bubble.

  1. Hover over a JSON-parsed message and click on the Edit icon (✏️).
  2. A visual tree editor will open directly inside the bubble.
  3. Click values to edit, or use arrows to expand/collapse structures.

  

• Editing Action, Tool Call, Tool Result, & Multi-Part Messages (Inline): Hovering over any structural or multi-part message block (an Action, Tool Call, Tool Result, or complex multi-part content list — whether Anthropic-style blocks or Gemini-style parts) reveals the Edit icon (✏️). Clicking it opens the visual JSON tree editor populated with the entire raw message JSON object, allowing you to inspect and modify all parameters (like id, name, input/arguments, content, or custom metadata keys) cleanly and safely.

• Inserting and Appending Messages:

  • To Insert: Hover over any message turn (either a system message, or a combination of user/assistant message). An Insertion Line will appear with buttons to + Add Turn or + Add System.

  

  • To Append to the Top: Scroll to the very top of the chat view to find the initial insertion line.

  

Text View

Displays the text of the current conversation on disk. This mode features a dual-toggle bar for switching between its two sub-modes:

• Sub-mode: Raw: Displays the exact, raw JSONL string as it exists in the file. Best for precise, line-by-line syntactical debugging.
• Sub-mode: Pretty-print: Automatically reformats the JSON with proper indentation and syntax highlighting for much better readability.

Features:

• Syntax Highlighting: In Pretty-print mode, the editor uses color-coding to make the JSON structure easy to follow.
• Live Error Detection: As you type, the editor validates your JSON syntax. If an issue is found, a clear error message appears below the editor pinpointing the exact line and column where the syntax is broken.
• Automatic Compacting: Edits made in Pretty-print mode are automatically compacted back into a single-line JSONL format when you save to ensure file compatibility.
• When to use: Use this for quick structural fixes or visual inspection of raw strings where the visual tree editor might be too abstract.
• Editing: You can type directly into the editor. A Save button and a Revert button will appear when you make changes.

JSON View

An industrial-grade tree editor for manipulating the entire JSON tree structure of the conversation object (including root properties, message arrays, and metadata definitions) as a collapsible, color-coded structure for deep structural editing.

Right-click any key or value to open the structural context menu:

• Edit Key / Edit Value: Rename fields or change individual values directly.
• Insert Before / After: Add a new entry at the same level as the selected item.
• Convert To: Instantly switch a value's type (e.g., change a String to an Object or Array).
• Duplicate / Remove: Efficiently clone or delete entire sections of the conversation.
• Transform: Apply powerful JMESPath queries to filter or reshape the data.
• Extract: Focus the editor on a specific nested object or array.
• Sort / Reverse: Reorder keys in an object or items in a list.

Advanced Features:

• Undo / Redo: Every action can be reversed with standard shortcuts (CTRL+Z).
• Drag & Drop: You can drag keys or items to move them within the structure.

---

5. Settings & Maintenance

• Clearing the indexing cache: If you experience issues or just want to free up space, you can clear the app's internal maps via Settings > Clear Index Cache. The app will re-index your files the next time you open them.
• Theme Management: Toggle between Dark and Light mode via the Settings menu to match your environment.