Refined Vercel Deployment Monitor

Real-time Vercel deployment statusline with build status, time since last deployment, and clickable deploy link via OSC 8 hyperlinks.

When to Use This Setting

Apply this setting when you need to:

• Monitor your Vercel deployment status in real-time without switching to the Vercel dashboard
• Click directly through to your latest deployment URL using terminal hyperlinks (Cmd+click)
• Track build state transitions (queued, building, ready, error) with time-since-deployment context Consider alternatives when:
• You do not use Vercel for deployments and the API calls would always fail
• Your terminal emulator does not support OSC 8 hyperlinks for the clickable deploy link feature

Quick Start

Configuration

Copy
name: refined-vercel-deployment-monitor
type: setting
category: statusline

Example Application

Copy
claude setting:apply refined-vercel-deployment-monitor

Example Output

Setting applied. Changes:
- statusLine.type: command
- statusLine.command: bash vercel-deploy-monitor inline
- api_endpoint: api.vercel.com/v6/deployments
- auth: VERCEL_TOKEN environment variable
- project: VERCEL_PROJECT_ID environment variable
- status_icons: ready(check), building(cycle), queued(hourglass), error(x)

Core Concepts

Deployment Monitor Overview

Aspect	Details
Deployment Status	Fetches latest deployment state: READY, BUILDING, QUEUED, or ERROR
Time Tracking	Calculates minutes since last deployment using created timestamp
Clickable Link	Generates OSC 8 terminal hyperlink for Cmd+click navigation to deployment URL
Authentication	Uses VERCEL_TOKEN Bearer token for Vercel REST API authentication
Project Binding	Filters deployments by VERCEL_PROJECT_ID to show only relevant project data

Vercel Monitor Architecture

+-------------------+     +-----------------------+     +------------------+
| Credential Loader |---->| Vercel API Call       |---->| State Parser     |
| VERCEL_TOKEN      |     | /v6/deployments?      |     | .deployments[0]  |
| VERCEL_PROJECT_ID |     | projectId=X&limit=1   |     | .state, .url     |
+-------------------+     +-----------------------+     +------------------+
                                    |                          |
                                    v                          v
                          +---------------------+     +------------------+
                          | Time Calculator     |     | OSC 8 Link Gen   |
                          | now - created/1000  |---->| terminal hyperlink|
                          | result in minutes   |     | Cmd+click ready  |
                          +---------------------+     +------------------+

Configuration

Parameter	Type	Default	Description
vercel_token	string	""	Bearer token for Vercel API authentication from vercel.com/account/tokens
vercel_project_id	string	""	Project identifier from your Vercel dashboard settings
api_limit	integer	1	Number of recent deployments to fetch from the API
show_deploy_link	boolean	true	Generate OSC 8 clickable hyperlink to the deployment URL
show_time_ago	boolean	true	Display elapsed minutes since the deployment was created

Best Practices

1. Use environment variables rather than hardcoding tokens - Export VERCEL_TOKEN and VERCEL_PROJECT_ID in your shell profile or project .env file. Never hardcode these values in the statusline command where they could be exposed in process listings.
2. Test OSC 8 hyperlink support - Not all terminals support clickable hyperlinks. Test in your terminal by clicking the deploy link. iTerm2, Alacritty, and Windows Terminal support OSC 8. If unsupported, the link text still displays but is not clickable.
3. Increase API limit for deployment history - Set api_limit to 3 or 5 to fetch recent deployments when you want to quickly compare the state of your last few deploys. The statusline shows only the most recent, but the data is available for script extension.
4. Add notification on error state - Extend the script to trigger a desktop notification when the deployment state changes to ERROR. This ensures you catch deployment failures immediately even if the statusline is not visible.
5. Rotate tokens regularly for security - Vercel API tokens should be rotated periodically. Set a calendar reminder to generate a new token from vercel.com/account/tokens and update your environment variables quarterly.

Common Issues

1. Status shows unavailable - Either VERCEL_TOKEN or VERCEL_PROJECT_ID is not set, or the API returned an error. Verify both environment variables are exported and accessible in the shell that runs the statusline command.
2. Time ago shows unknown - The created timestamp field may be null for deployments that were cancelled or are still queued. This is expected for very recent deployments that have not yet received a creation timestamp.
3. Clickable link does not work - Your terminal does not support OSC 8 hyperlinks. The deployment URL text still appears but cannot be clicked. Switch to a terminal emulator that supports OSC 8 or copy the URL manually.