Skip to main content
Glama
terminal-progress-bar

terminal-progress-bar

by marceloxp

terminal-progress-bar

One progress, two interfaces: terminal for you, MCP for the AI.

Shared terminal progress bars for parallel scripts and processes. Track multiple jobs from different terminals or scripts and watch them update in real time.

Install

uv tool install -e .

Or from a clone of this repository:

git clone https://github.com/you/terminal-progress-bar.git
cd terminal-progress-bar
uv tool install -e .

Editable install (-e) keeps tpb linked to the source tree, so local changes take effect without reinstalling.

Related MCP server: Terminally MCP

Usage

Run tpb --help for an overview, or tpb <command> --help for command details (e.g. tpb create --help).

Create a progress bar

tpb create backup-db 0 100 "Database backup"

Update progress

tpb backup-db 35        # set absolute value
tpb backup-db +5        # increment
tpb backup-db -2        # decrement
tpb message backup-db "Importing users table"

Finish or fail

tpb done backup-db "completed in 2m"
tpb error backup-db "connection timeout"

List, status, remove

tpb                     # visual progress bars (Rich)
tpb list                # plain text: slug, current, max, status, label
tpb status backup-db    # machine-readable plain text output for one bar
tpb rm backup-db        # remove a bar

Monitor in real time

tpb monitor

The monitor redraws the screen when any progress bar changes. Bars stay visible until removed with tpb rm. Press q to exit.

Storage

Each progress bar is stored as a separate JSON file:

~/.config/terminal-progress-bar/<slug>.json

Example:

{
  "slug": "backup-db",
  "label": "Database backup",
  "current": 35,
  "max": 100,
  "status": "active",
  "status_text": "",
  "created_at": "2026-07-30T12:00:00Z",
  "updated_at": "2026-07-30T12:05:00Z"
}

Bars are listed in creation order (created_at).

List output

tpb list prints one tab-separated line per bar:

import-data	25	100	active	Import data
backup-db	100	100	done	Database backup

Columns: slug, current, max, status, label, and status_text (only when set).

Status output

tpb status <slug> prints plain key: value lines for scripting and AI agents:

slug: backup-db
label: Database backup
current: 35
max: 100
status: active
status_text:
created_at: 2026-07-30T12:00:00Z
updated_at: 2026-07-30T12:05:00Z

MCP Server

The package includes an MCP server (tpb-mcp) for AI clients to manage progress bars programmatically over stdio.

Run

After install:

tpb-mcp

From a clone without global install:

uv run tpb-mcp

Client configuration

Example MCP client config:

{
  "mcpServers": {
    "terminal-progress-bar": {
      "command": "tpb-mcp",
      "args": []
    }
  }
}

From the repository:

{
  "mcpServers": {
    "terminal-progress-bar": {
      "command": "uv",
      "args": ["run", "tpb-mcp"],
      "cwd": "/path/to/terminal-progress-bar"
    }
  }
}

Tools

Tool

Description

tpb_create

Create a progress bar

tpb_update

Set absolute progress value

tpb_increment

Increment or decrement progress

tpb_message

Set status message below the bar

tpb_done

Mark as completed

tpb_error

Mark as failed

tpb_remove

Remove a progress bar

tpb_list

List all bars (structured JSON)

tpb_get

Get one bar by slug

Example flow: tpb_create → tpb_update / tpb_increment → tpb_message → tpb_done.

Tools return structured JSON (bar fields as dict). The human tpb monitor view updates automatically when bars change on disk.

Development

uv sync --group dev
uv run pytest

License

MIT

Available Tools

9 tools
tpb_createC

Create a new progress bar.

Inputs: slug (required), current (required), max_value (required), label. Returns: object

tpb_doneC

Mark a progress bar as completed.

Inputs: slug (required), status_text. Returns: object

tpb_errorC

Mark a progress bar as failed.

Inputs: slug (required), status_text. Returns: object

tpb_getB

Get structured status for a single progress bar.

Inputs: slug (required). Returns: object

tpb_incrementB

Increment or decrement progress by delta (use negative values to decrement).

Inputs: slug (required), delta (required). Returns: object

tpb_listA

List all progress bars in creation order.

Inputs: no named parameters. Returns: result

tpb_messageB

Set or update the status message shown below a progress bar.

Inputs: slug (required), text (required). Returns: object

tpb_removeC

Remove a progress bar.

Inputs: slug (required). Returns: object

tpb_updateB

Set the absolute progress value for a bar.

Inputs: slug (required), value (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: create, update absolute value, increment delta, set message, mark done, mark error, remove, list, and get status. There is no overlap; even 'update' and 'increment' are differentiated by absolute vs. relative progress.

    Naming Consistency5/5

    All tool names follow the same 'tpb_' prefix with a verb (create, update, increment, message, done, error, remove, list, get). The pattern is perfectly consistent and predictable.

    Tool Count5/5

    With 9 tools, the server is well-scoped for managing progress bars. Each tool serves a necessary function in the lifecycle of a progress bar without unnecessary bloat.

    Completeness5/5

    The tool set covers the full lifecycle: create, update, increment, message, complete, error, remove, and query. There are no obvious gaps for a progress bar utility; all common operations are included.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that lets agents and humans monitor and control long-running processes, reducing copy-pasting between AI tools and enabling multiple agents to interact with the same process outputs.
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that enables AI coding agents to communicate, share state, and coordinate work in real time via MCP tools or REST API.
      79 npm
      10
      MIT