Instagit Progress Tracking System: How It Streams Real-Time Feedback to Clients

Instagit implements a token-based progress tracking system that streams real-time status updates to clients through the Model-Context-Protocol (MCP) notifications/progress channel, featuring a 250ms heartbeat, animated KITT-style progress bars, and live token counters.

The progress tracking system in Instagit provides transparent, real-time feedback during repository analysis operations. Implemented in the instalabsAI/instagit codebase, this lightweight server-side mechanism ensures clients receive continuous status updates through standardized MCP notifications, eliminating uncertainty during long-running AI operations.

Core Architecture of the Progress Tracking System

The ProgressTracker State Container

At the heart of the progress tracking system lies the ProgressTracker type defined in src/types.ts L15-L23. This interface holds mutable state for the current analysis run, including:

• Start time for elapsed time calculations
• Animation frame for the KITT-style progress bar
• Token counters (inputTokens, outputTokens) tracking LLM usage
• Last status text describing the current operation
• Done flag indicating completion

Factory Initialization

The createProgressTracker() factory function in src/kitt.ts L56-L84 initializes a fresh tracker with sensible defaults. Upon creation, the tracker sets the initial status to "Connecting…" and records the current timestamp, establishing the baseline for all subsequent progress calculations.

How the Progress Tracking System Formats Updates

Message Serialization with formatMessage

The formatMessage() function in src/kitt.ts L87-L111 serializes the tracker state into a human-readable string. This method accepts optional status updates or token deltas, updates the internal tracker state, and constructs a formatted message combining:

• An animated progress bar (KITT-style block characters)
• Elapsed time since start
• Current token counts (e.g., "1.2k tokens")
• Descriptive status text

The KITT-Style Animated Progress Bar

The progress tracking system generates a retro-futuristic animated bar using block characters (█ and ░) that shift across the display, reminiscent of the KITT car from Knight Rider. This animation updates on each formatMessage call, providing visual confirmation that the analysis is actively processing even when token counts remain static.

Streaming Progress to Clients via MCP

The sendProgress Notification Wrapper

In src/index.ts L76-L86, the sendProgress callback wraps the MCP notification mechanism. This function receives the formatted message string and forwards it to the client using extra.sendNotification() with the method "notifications/progress", ensuring compatibility with the Model-Context-Protocol specification.

Token Generation and Request Isolation

The progress tracking system maintains isolation between concurrent clients through unique progress tokens. As implemented in src/index.ts L73-L74, the system first checks for a client-supplied token in extra._meta?.progressToken, falling back to a generated token formatted as ask_repo_<timestamp>. This token identifies the specific request in all subsequent notifications, preventing cross-contamination of progress updates between simultaneous analyses.

The 250ms Heartbeat Mechanism

Inside src/api.ts L73-L81, the streaming API analyzeRepoStreaming implements a heartbeat mechanism that invokes the progressCallback every 250 milliseconds. This ensures clients receive regular updates even during periods of low token activity, maintaining the animated progress bar and elapsed time counter. The callback receives the latest output from formatMessage(tracker), creating a continuous stream of status information.

Client-Side Feedback Loop

When the progress tracking system emits a notification, the MCP client receives a JSON payload containing { progressToken, progress, message }. The client matches the progressToken against the active request, then renders the message string—complete with the animated KITT-style bar, elapsed time, and token counts—directly in the user interface. This creates an immediate feedback loop where users observe real-time progress from "Connecting…" through "Downloading repository…" to final completion.

Summary

• Stateless per request: Each analysis run receives an isolated ProgressTracker instance, ensuring concurrent operations never interfere.
• MCP-compliant streaming: Updates flow through the standard notifications/progress channel using unique tokens for request identification.
• Rich visual feedback: The formatMessage function generates animated KITT-style progress bars combined with elapsed time and live token counters.
• Reliable heartbeat: A 250ms interval guarantees continuous updates even during network or processing delays.
• Factory initialization: createProgressTracker() establishes consistent baseline states starting with "Connecting…".

Frequently Asked Questions

How does Instagit isolate progress updates between concurrent clients?

The progress tracking system generates a unique progress token for each request, either extracted from extra._meta?.progressToken or constructed as ask_repo_<timestamp> in src/index.ts. This token accompanies every notifications/progress message, allowing clients to match updates to their specific analysis run and preventing cross-contamination between simultaneous operations.

What information is included in each progress notification?

Each notification contains a formatted message string produced by formatMessage() in src/kitt.ts, which includes an animated KITT-style progress bar, elapsed time since analysis start, current input/output token counts, and a descriptive status text such as "Downloading repository…" or "Writing response…". The payload also carries the progressToken and the numeric progress value representing output tokens.

How frequently does the progress tracking system send updates?

The system implements a 250ms heartbeat mechanism inside src/api.ts that invokes the progressCallback at regular intervals, ensuring clients receive updates even when token counts remain static. Additionally, the callback triggers immediately whenever token usage changes or status text updates, creating a responsive stream that balances real-time feedback with network efficiency.

What protocol does Instagit use to stream progress to clients?

Instagit utilizes the Model-Context-Protocol (MCP) standard, specifically the notifications/progress method defined in the MCP specification. The server sends JSON-RPC notifications through extra.sendNotification() with the method string "notifications/progress", ensuring compatibility with any MCP-compliant client that can listen for and render these standardized progress events.

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