Building Statuslines

Create persistent terminal widgets that surface what matters — build health, test coverage, deploy state, open issues. Real-time project intelligence, visible at a glance.

Statuslines solve a friction that every team feels but rarely names: important project state is scattered across browser tabs, CI dashboards, and Slack notifications. A Statusline brings it into Claude Code's terminal, persistent and immediate. No context switching. No hunting for dashboards. The information you need to make decisions is right there, updating in real time.

If you've ever wished you could see your build status, sprint progress, or key metrics without leaving your working environment — that's a Statusline. And if you've built a display that works for you, others will pay for the same visibility.

What is a Statusline?

A Statusline is a configuration file installed into .claude/statuslines/. It defines what data to surface, how to display it, and how often to refresh. Claude Code renders the Statusline in the terminal UI — a persistent bar or panel that updates alongside your work.

The difference between a Statusline and a dashboard: a dashboard is a separate tool you visit. A Statusline is always present, ambient — it doesn't require a decision to check. Important state enters peripheral awareness.

Who creates Statuslines?

You don't need to be a developer. You need to know what matters in a project.

• Team leads — surface sprint progress, open blockers, and team capacity in one view
• Developers — show build health, test coverage, and deployment status without leaving the terminal
• Engineering managers — track key engineering metrics: cycle time, PR queue depth, incident status
• Product managers — display feature flag states, A/B test results, and release status
• Agency owners — create client-project statuslines that show delivery health at a glance
• DevOps engineers — monitor service health, error rates, and infrastructure costs live

If you can answer "the five numbers I check every morning before starting work" — you can build a Statusline.

Create your first Statusline

Let's build a development health Statusline. The kind that shows you exactly what you need before writing a single line of code.

Scaffold the project

$ myclaude init dev-health-status --type statusline
$ cd dev-health-status

You now have a starter statusline.yaml and vault.yaml.

Define your display configuration

The core of a Statusline is statusline.yaml — what to show, where to get it, and how to display it:

# statusline.yaml

name: dev-health-status
display:
  layout: bar              # bar | panel | compact
  position: bottom         # top | bottom
  refresh: 30              # seconds between updates

sections:
  - id: build
    label: "BUILD"
    source:
      type: ci
      provider: github-actions   # github-actions | circleci | vercel
      watch: [main, develop]
    display:
      passing: { icon: "●", color: green, text: "passing" }
      failing: { icon: "●", color: red, text: "failing" }
      running: { icon: "○", color: yellow, text: "running" }

  - id: tests
    label: "TESTS"
    source:
      type: coverage-file
      path: coverage/coverage-summary.json
      field: total.lines.pct
    display:
      format: "{{ value }}%"
      thresholds:
        green: ">= 80"
        yellow: ">= 60"
        red: "< 60"

  - id: deploy
    label: "DEPLOY"
    source:
      type: vercel
      environment: production
    display:
      ready: { icon: "↑", color: green, text: "live" }
      building: { icon: "↻", color: yellow, text: "deploying" }
      error: { icon: "✗", color: red, text: "failed" }

  - id: issues
    label: "ISSUES"
    source:
      type: github
      query: "is:issue is:open label:bug"
    display:
      format: "{{ value }} open"
      thresholds:
        green: "== 0"
        yellow: "<= 3"
        red: "> 3"

  - id: prs
    label: "PRs"
    source:
      type: github
      query: "is:pr is:open review:required"
    display:
      format: "{{ value }} waiting"
      thresholds:
        green: "== 0"
        yellow: "<= 2"
        red: "> 2"

What this renders in the Claude Code terminal:

BUILD ● passing  |  TESTS 94%  |  DEPLOY ↑ live  |  ISSUES 0 open  |  PRs 1 waiting

Every metric in a single glance. Everything green means you can ship. Anything red tells you what to fix first.

Define alert behavior

Statuslines become genuinely useful when they interrupt attention for things that matter:

alerts:
  - trigger: "build.status == failing"
    severity: critical
    message: "Main branch build is failing"

  - trigger: "tests.coverage < 70"
    severity: warning
    message: "Test coverage dropped below 70%"

  - trigger: "issues.count > 5"
    severity: warning
    message: "Bug backlog growing"

Alerts appear in the Claude Code notification area — not as popups that demand immediate action, but as ambient signals that inform the next decision.

Wire vault.yaml

name: dev-health-status
version: 1.0.0
type: statusline
title: "Dev Health Status — Build, Tests, Deploy, Issues at a Glance"
description: "A persistent Statusline showing build health, test coverage, deploy state, open bugs, and PR queue. All in one line, always visible, updating every 30 seconds."
price: 14.99
tags:
  - statusline
  - build-status
  - ci-cd
  - github
  - test-coverage
  - developer-tools

Write an INSTALL.md

Statuslines require configuration — the buyer needs to connect their data sources. A clear setup guide is the difference between a product that works and one that generates support requests:

# Installation

## Required: configure your data sources

Edit `statusline.yaml` and fill in your project details:

### GitHub (issues and PRs)
1. Generate a GitHub Personal Access Token with `repo` scope
2. Add to your environment: `export GITHUB_TOKEN=ghp_your-token`
3. Update the `query` fields with your repository name

### GitHub Actions (build status)
No token needed if your repo is public.
For private repos: use the same GITHUB_TOKEN.
Update `watch` with your branch names.

### Vercel (deploy status)
1. Generate a Vercel token at vercel.com/account/tokens
2. Add to your environment: `export VERCEL_TOKEN=your-token`
3. Set your project name in the Vercel section

### Test coverage
Works automatically if your project generates
`coverage/coverage-summary.json` (Jest default location).
Update `path` if yours is different.

## Start using

```bash
myclaude install dev-health-status

Then start a new Claude Code session — your Statusline appears immediately.

### Test locally

```bash
$ mkdir -p .claude/statuslines/dev-health-status
$ cp -r . .claude/statuslines/dev-health-status/

Start a new Claude Code session. Does the Statusline appear? Does it show your project's real data? Try triggering an alert — break your build intentionally and confirm it updates. If everything is showing correctly, you're ready to publish.

Publish

$ myclaude validate
$ myclaude publish

Your Statusline is now live on MyClaude.

What makes a great Statusline

The difference between a Statusline that becomes essential and one that gets disabled:

The best Statuslines are invisible when everything is fine and unmissable when it isn't. Green metrics disappear into the background. A red alert demands attention without demanding action right now. This balance — ambient when healthy, urgent when critical — is what makes a Statusline genuinely useful.

Advanced: Sprint and team Statuslines

Statuslines aren't only for technical metrics. Team leads often find the most value in process-oriented displays:

sections:
  - id: sprint
    label: "SPRINT"
    source:
      type: linear         # linear | jira | github-projects
      project: current-sprint
      metric: completion-pct
    display:
      format: "{{ value }}% done"
      thresholds:
        green: ">= 80"
        yellow: ">= 50"
        red: "< 50"

  - id: blockers
    label: "BLOCKED"
    source:
      type: linear
      query: "is:issue label:blocked"
    display:
      format: "{{ value }} blocked"
      thresholds:
        green: "== 0"
        yellow: "== 1"
        red: "> 1"

  - id: review
    label: "IN REVIEW"
    source:
      type: linear
      status: "In Review"
    display:
      format: "{{ value }} items"

This gives a team lead the sprint's health in one line. No Jira tab. No status meeting to find out if anything is blocked.

Common questions

Do buyers need technical skills to configure a Statusline?

Some data sources require tokens or API keys, which involves a few setup steps. Write your INSTALL.md assuming a buyer who understands their tools but hasn't done this specific setup before. Clear, numbered steps with example values make the difference.

How fast do Statuslines update?

The recommended refresh range is 15-120 seconds depending on the data type. Build status: check every 30 seconds. Sprint metrics: every 5 minutes is fine. Don't refresh faster than necessary — it adds noise without adding signal.

Can a Statusline connect to custom internal tools?

Yes, if the internal tool exposes an HTTP API. Add a type: http data source with the endpoint URL and authentication headers. The buyer configures their internal tool URL in the INSTALL.md setup step.

Can I sell a Statusline for a specific tech stack?

Absolutely. A Statusline tailored to "Next.js on Vercel" or "React Native with Fastlane CI" will outperform a generic one. Specificity is a feature — buyers are more likely to purchase something that was clearly built for their setup.

Related pages

• Product Categories — all 12 categories compared
• vault.yaml Reference — every field explained
• Publishing Guide — the full publishing process
• Monetization — pricing strategies for paid products
• What People Build — real examples from MyClaude creators