/thread - Conversation Threading (Message Relationship Tracing)

Visualize and trace conversation threads using UUID parent-child relationships for session continuity and agent conversation tracking. Part of the CODITECT anti-forgetting system.

Usage

# Show recent threading relationships
/thread

# Trace conversation from specific UUID
/thread UUID

# Show threads for specific session
/thread --session ID

# Show agent conversation threads
/thread --agents

# Show as JSON
/thread --json

System Prompt

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

You are querying the CODITECT context database for conversation threading analysis.

Database: context-storage/sessions.db (ADR-118 Tier 3) (SQLite with message_threading table)

Execute the context query with threading options:

python3 scripts/context-db.py --threading [OPTIONS]
# OR
python3 scripts/context-db.py --thread-from UUID [OPTIONS]

Threading Table Schema:

• uuid - Unique message identifier
• parent_uuid - Direct parent message
• logical_parent_uuid - Logical parent (for branching conversations)
• session_id - Session identifier
• agent_id - Agent identifier (for multi-agent conversations)
• entry_type - Message type (user, assistant, system, etc.)
• timestamp - When message occurred

Quick Reference

Basic Operations

Command	Description
/thread	Show recent threading relationships
/thread UUID	Trace thread from specific UUID
/thread --agents	Show agent conversation threads
/thread --session ID	Filter by session ID
/thread --json	Output as JSON

Analysis

Command	Description
/thread --limit N	Show N recent threads (default: 20)
/thread --type TYPE	Filter by entry type
/thread --full	Show full UUID (not truncated)

Examples

Show Recent Threading Relationships

/thread

Output:

Message Threading (20 entries):

UUID         Parent       Type       Agent      Timestamp
----------------------------------------------------------------------
a1b2c3d4e5   f6g7h8i9j0   user       main       2025-12-23T10:30:00
f6g7h8i9j0   None         assistant  main       2025-12-23T10:29:45
...

Trace Conversation Thread

/thread a1b2c3d4e5f6-g7h8-i9j0-k1l2-m3n4o5p6q7r8

Output:

Thread from a1b2c3d4e5... (5 messages):

├─ [user] a1b2c3d4 @ 2025-12-23T10:25:00
  ├─ [assistant] f6g7h8i9 @ 2025-12-23T10:25:15
    ├─ [user] j0k1l2m3 @ 2025-12-23T10:26:00
      ├─ [assistant] n4o5p6q7 @ 2025-12-23T10:26:30
        ├─ [tool_result] r8s9t0u1 @ 2025-12-23T10:26:45

Filter by Session

/thread --session abc123

Shows only threads from session abc123.

Show Agent Conversations

/thread --agents

Shows multi-agent conversation threads with agent identifiers.

JSON Output (Programmatic Use)

/thread --json

Output:

[
  {
    "uuid": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "parent_uuid": "f6g7h8i9-j0k1-l2m3-n4o5-p6q7r8s9t0u1",
    "logical_parent_uuid": null,
    "session_id": "abc123",
    "agent_id": "main",
    "entry_type": "user",
    "timestamp": "2025-12-23T10:30:00Z"
  }
]

Trace with Full UUIDs

/thread UUID --full

Shows complete UUIDs without truncation.

Options

Option	Description
UUID	Trace thread from specific UUID
--session ID	Filter by session ID (partial match)
--agents	Show agent conversation threads
--type TYPE	Filter by entry type (user, assistant, system, etc.)
--limit N	Number of threads to show (default: 20)
--full	Show full UUIDs (not truncated)
--json	Output as JSON

Use Cases

Session Continuity

# Find where conversation started
/thread --session current-session

# Trace back to root message
/thread ROOT_UUID

Multi-Agent Conversation Analysis

# See how agents communicated
/thread --agents

# Trace specific agent's conversation
/thread --agents --session agent-session-id

Debugging Message Flow

# Find parent-child relationships
/thread

# Trace specific message lineage
/thread MESSAGE_UUID --full --json

Context Reconstruction

# Get full thread for context
/thread LATEST_UUID

# Find all messages in session
/thread --session SESSION_ID

Integration

Works with:

• /cxq - Query individual messages in thread
• /cx - Extract and index messages with threading
• /export - Export sessions with thread preservation

Threading Workflow:

# 1. Extract sessions with threading
/cx

# 2. View threading relationships
/thread

# 3. Trace specific conversation
/thread UUID

# 4. Query messages in thread
/cxq --search-entries "query" --thread-from UUID

Anti-Forgetting Benefits

Conversation Continuity:

• Reconstruct full conversation context
• Follow branching conversations
• Track multi-agent interactions

Session Recovery:

• Resume conversations from any point
• Find related discussions
• Understand conversation evolution

Agent Coordination:

• Trace agent handoffs
• Debug multi-agent workflows
• Analyze agent conversation patterns

---

Related Commands

• /cxq - Query messages with --threading and --thread-from UUID
• /cx - Extract messages with threading metadata
• /cxq --search-entries - Search within specific thread

---

Action Policy

<default_behavior> This command queries and displays without making changes. Provides:

• Threading relationship visualization
• Conversation trace from UUID
• Agent conversation threads
• JSON output for analysis

Read-only operation on context database. </default_behavior>

After execution, verify: - Threading data retrieved - Trace displayed correctly - Parent-child relationships shown - Agent threads visible (if --agents)

Success Output

When threading query completes:

✅ COMMAND COMPLETE: /thread
Query: <UUID or "recent">
Messages: N in thread
Depth: D levels
Agents: M involved

Completion Checklist

Before marking complete:

• Database connected
• Threading query executed
• Relationships visualized
• Output formatted

Failure Indicators

This command has FAILED if:

• ❌ Database not found
• ❌ UUID not found
• ❌ No threading data
• ❌ Visualization failed

When NOT to Use

Do NOT use when:

• Need message content (use /cxq)
• Need to index sessions (use /cx)
• No sessions have been extracted

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip /cx first	No threading data	Run /cx to index
Truncated UUID	No match	Use --full or complete UUID
Ignore agents	Miss coordination	Use --agents for multi-agent

Principles

This command embodies:

• #6 Clear, Understandable - Visual thread tree
• #9 Based on Facts - Actual conversation data

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Script: scripts/context-db.py --threading or --thread-from UUID Database: context-storage/sessions.db (ADR-118 Tier 3) (message_threading table) Version: 1.0.0 Last Updated: 2025-12-23 Related ADRs: ADR-025 (Comprehensive Entry Schema)