Architecture

Tracybot consists of three components that work together:

• opencode-plugin - Plugin for opencode CLI that records snapshots during AI interactions
• vscode-extension - VS Code extension to view AI blame information
• tracybot-tracking - Git hooks and scripts for state tracking using hidden commits and synced git notes

Find the requirements that resulted in these architectural decisions here.

How Components Communicate

1. opencode-plugin invokes tracy.py (from tracking/) after each AI interaction to create a snapshot
2. tracy.py (tracking) stores snapshots as hidden commits in the Git repository (using refs/tracy-local/* namespace)
3. vscode-extension queries Git to build a history timeline and displays blame information in VS Code

Information Flow Scenarios

sequenceDiagram
    autonumber
    actor D as Developer
    participant O as OpenCode
    participant P as OpenCode Plugin
    participant T as tracy.py
    participant G as Git (Repository)

    Note over O, G: Snapshot Creation Flow
    D->>O: Prompts
    
    rect transparent
        Note over O, G: Pre-Edit Snapshot (Tool Interception)
        O->>P: Event: tool.execute.before<br>(e.g., "edit", "write")
        P->>T: Invoke tracy.py<br>(baseline before edits)
        T->>G: Write tree & commit to<br>refs/tracy-local/{uuid}
    end

    O->>O: AI generates code<br>& applies file changes
    
    O->>P: Event: session.idle
    activate P
    Note over P: Check tool activity counter.<br/>If > 0, proceed to capture AI state.
    
    P->>O: Fetch session<br>messages & metadata
    O-->>P: Return message history
    
    P->>P: Parse messages into Tasklet JSON
    P->>T: Invoke tracy.py
    deactivate P
    
    activate T
    T->>G: Get/Set identifier<br>from git config
    
    rect transparent
        Note over T, G: Isolated Git Tree Construction
        T->>T: Generate temporary index file
        T->>G: Stage changes only to temp index
        G-->>T: Return target tree hash
    end
    
    T->>G: Resolve parent commit<br>(refs/tracy-local/{uuid} or HEAD)
    G-->>T: Return hidden commit hash
    
    T->>G: git update-ref<br>refs/tracy-local/{uuid} <hash>
    deactivate T

Loading

sequenceDiagram
    autonumber
    actor D as Developer
    participant V as VS Code Extension
    participant G as Git (Repository)

    note over V,G: Display Flow

    D->>V: Trigger "AI Blame" Command<br>(Ctrl/Cmd+Shift+0 or Status Bar)
    activate V
    
    V->>G: Query hidden ref<br>updates (refs/tracy/*<br>and refs/tracy-local/*)
    G-->>V: Return commit tree<br>history hashes & notes
    
    V->>G: Query WORKDIR uncommitted<br>changes & file diff hunks
    G-->>V: Return active<br>unstaged line diffs
    
    V->>V: Parse Git metadata<br>(JSON strings into Tasklet objects)
    
    rect transparent
        Note over V: Internal Trace Building Logic
        Note over V: 1. Map historical lines to commit trees<br/>2. Apply consumeAndShift() to adjust for local user edits<br/>3. Run deduplicateAILines() to resolve collisions
    end
    
    V->>V: Compile lineMap & fileTaskletsMap
    V->>V: Capture current file contents<br>& initial line cursor position
    
    V->>V: Generate HTML document
    V-->>D: Present populated blame panel
    
    deactivate V

Loading

sequenceDiagram
    actor D as Developer
    participant G as Git
    participant H as Git Hooks

    note over G,H: On Commit
    D->>G: git commit
    H->>G: Promote to refs/tracy/{uuid}
    H->>G: Add tracy-id note

Loading

sequenceDiagram
    actor D as Developer
    participant G as Git
    participant H as Git Hooks

    note over G,H: On Push
    D->>G: git push
    H->>G: Fetch remote notes
    H->>G: Merge notes
    H->>G: Push refs/tracy/* and notes

Loading

sequenceDiagram
    actor D as Developer
    participant G as Git
    participant H as Git Hooks

    note over G,H: On Rebase
    D->>G: git rebase
    H->>G: Merge refs/tracy/*
    H->>G: Update tracy-id note

Loading