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

> Discover Instagits progress tracking system. It streams real-time client feedback via MCP notifications with animated progress bars and live token counts for instant updates.

- Repository: [Instalabs AI/instagit](https://github.com/instalabsai/instagit)
- Tags: internals
- Published: 2026-02-16

---

**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`](https://github.com/instalabsAI/instagit/blob/main/src/types.ts) [`L15-L23`](https://github.com/instalabsAI/instagit/blob/main/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`](https://github.com/instalabsAI/instagit/blob/main/src/kitt.ts) [`L56-L84`](https://github.com/instalabsAI/instagit/blob/main/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`](https://github.com/instalabsAI/instagit/blob/main/src/kitt.ts) [`L87-L111`](https://github.com/instalabsAI/instagit/blob/main/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`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) [`L76-L86`](https://github.com/instalabsAI/instagit/blob/main/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`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) [`L73-L74`](https://github.com/instalabsAI/instagit/blob/main/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`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts) [`L73-L81`](https://github.com/instalabsAI/instagit/blob/main/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`](https://github.com/instalabsAI/instagit/blob/main/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`](https://github.com/instalabsAI/instagit/blob/main/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`](https://github.com/instalabsAI/instagit/blob/main/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.