▶ runcommand

Never hunt for the run command again.

Juggling a dozen repos? runcommand works out how to start each one (pnpm dev, cargo run, docker compose up) and shows it next to the localhost ports it's actually serving, right in your status bar and prompt.

See how it worksView on GitHub
Package manager
pnpm add -g @amabush/runcommand && runcommand init

init finds supported tools, updates their config, and backs up changed files. It needs Node and one supported AI CLI for detection. Read the setup guide →

Features

What runcommand does

  • Detects the command

    An installed AI CLI reads the project and returns the command it expects: pnpm dev, uvicorn main:app, bin/rails server, cargo run, go run ., mix phx.server, dotnet run, ./gradlew bootRun, docker compose up, and more.

  • Reads from a cache

    Each project is detected once. Status lines read a machine-managed JSON cache; a miss starts detection in the background. A cache entry looks like this:

    // Usually: ~/.cache/runcommand/<project-hash>.json
{
  "root": "/Users/you/Code/app",
  "commands": [
    {
      "command": "pnpm dev"
    }
  ],
  "source": "llm",
  "agent": "claude",
  "signalsHash": "7cf0d4…",
  "detectedAt": 1786924800000
}

  • Refreshes after changes

    The cache key includes the project's manifests. Change a script or Make target and the next render schedules a new detection.

  • Finds project ports

    Lists listening ports owned by processes inside the current project. Ports from databases and other projects are excluded.

  • Fits existing tools

    One binary, rendered by whatever status bar or prompt you already run. runcommand init wires up what it finds and keeps the status line you already had.

  • Handles multiple services

    Labels each command in a monorepo and assigns distinct colours. The labels keep services identifiable without relying on colour alone.

Integrations

Status lines, prompts, and terminal links.

runcommand writes the cached command to each tool's available UI, and leans on whichever AI CLI you already have to work that command out in the first place. Ports use OSC 8 linksAn escape sequence that makes terminal text a real hyperlink, so a short :5173 is clickable without printing the whole URL. Not every terminal supports it — those get the full address instead. Opens the reference ↗ where the terminal supports them. Click a terminal or tool to open its screenshot when one is available.

* Apple Terminal does not support OSC 8. There, the url port style prints http://localhost:PORT so the terminal can detect the link. Konsole, foot, and other OSC 8 terminals work as well.

Screenshot

Reference

Commands

CommandWhat it does
runcommand initFind supported tools and configure them · --dry-run --yes --surfaces
runcommand statuslinePrint the command and live ports for Claude Code or Qwen Code
runcommand promptPrint the cached command for a shell prompt
runcommand promptlinePrint a styled command and clickable ports for starship
runcommand portsList this project's live localhost ports · --links --urls --json --all
runcommand jsonReturn { commands, ports } for integrations such as OpenCode
runcommand detectRun detection now, then print and cache the result
runcommand getPrint the cached command; detect it if missing
runcommand refreshRun detection again · --hint "correction" --clear-hint
runcommand pathPrint the cache file path for a project
runcommand agentsList detection agents · --probe tests each one
runcommand uninstallRemove runcommand's config and restore backups

Project overrides

Overrides take precedence over cached detection and skip the detection agent. Commit them — everyone cloning the repo gets the pinned command.

SourceFormatExample
.runcommandOne command per line. Add a label: prefix to name multiple services.web: pnpm dev
Run: in CLAUDE.mdOne command, outside fenced code examples.Run: docker compose up

Environment variables

VariableWhat it does
RUNCOMMAND_MODELSelects the detection model. Claude uses haiku by default; other agents keep their own default.
RUNCOMMAND_PORT_STYLEUses url for full localhost URLs or compact for short OSC 8 links such as :5173.
RUNCOMMAND_COLORSSets the comma-separated ANSI colour codes used for multiple services, for example 36,33,35.
NO_COLORRemoves ANSI colour from all output.