recipe catalog · 9 configs
Signals you can pin.
9 standalone TOML recipes for small, useful signals. Search the catalog, read the source, and see the shape of each item before you copy it into your own config.
9 recipes
TOML
# Recipe: ai-quota (optional third-party tool)
# Category: AI
#
# Purpose: show a coding-agent provider's remaining weekly quota
# percentage in the menu bar. This is the same pattern documented as the
# flagship example in the main README, provided here standalone so it can
# be copied without pulling in the rest of `example/pinchos.toml`.
#
# Dependencies (both optional, neither ships with macOS or with pinchos):
# - `quota-axi`: reads local provider auth sources and reports quota
# windows as JSON. Source / install: https://github.com/kunchenguid/quota-axi
# - `jq`: a JSON processor. Install: https://jqlang.org/ (Homebrew: `brew
# install jq`).
# Account/auth requirement: `quota-axi` reads whatever local credentials
# the named provider's own CLI or app already stores (e.g. an existing
# Claude Code or Codex CLI login) — no credential belongs in this file.
#
# Expected output: "42" when the provider has an active auth session and
# a "week" quota window; the underlying provider response is
# `{"providers":[{"windows":[{"label":"week","percentRemaining":42}]}]}`.
# Locale-independent, but account- and provider-state-dependent: a
# signed-out or rate-limited provider reports `windows: []` (see below).
# Limitations: when `quota-axi` has no windows for a provider, the command
# produces an empty value. This recipe uses a shell pipeline (`|`), so
# review the command before installing it.
#
# Copy this file's [item.*] table(s) into your pinchos.toml, replace
# "claude" with any provider quota-axi supports (see quota-axi --help),
# then:
# .build/release/pinchos validate
# .build/release/pinchos doctor
# .build/release/pinchos run claude
[item.claude]
run = "quota-axi --provider claude --json | jq -r '.providers[0].windows[] | select(.label==\"week\") | .percentRemaining'"
interval = "5m"
timeout = "15s"
format = "{output}%"
canonical item
claude42%
- claude
- 5m · {output}%
Copy the item table into your config, replace placeholders, then validate before running it. Add ordered menu rows when the item needs a submenu.
TOML
# Recipe: aws-profile (optional third-party tool)
# Category: Cloud
#
# Purpose: show which AWS account a named CLI profile currently resolves
# to, so you notice immediately if a terminal or script is pointed at the
# wrong account.
# Dependencies: the AWS CLI (`aws`), which does not ship with macOS.
# Source / install: https://aws.amazon.com/cli/ (Homebrew:
# `brew install awscli`).
# Account/auth requirement: a working AWS CLI profile, already configured
# with `aws configure --profile <name>` (or SSO via `aws configure
# sso`), with permission to call `sts:GetCallerIdentity`. `AWS_PROFILE`
# below is a profile *name* placeholder, not a credential — replace
# "default" with whichever profile you configured; no access key,
# secret key, or session token belongs in this file or in Pinchos.
#
# Expected output: "123456789012" (a 12-digit AWS account ID, from
# `aws sts get-caller-identity --query Account --output text`).
# Account-dependent by design — that is the point of the recipe. An
# account ID is not a secret, but it does identify which AWS account
# your shell is pointed at; treat the rendered menu-bar text with the
# same care you'd give any visible account identifier on your screen.
# Limitations: an expired SSO session, a missing profile, or no network
# route to AWS all make `aws` exit non-zero with a message on stderr;
# credentials or network. This recipe is not exercised in CI (no AWS
# account or network there); it is syntax-checked only.
# This is a single command (no shell pipeline), so it is easy to review.
#
# Copy this file's [item.*] table(s) into your pinchos.toml, replace
# "default" with your own profile name, then:
# .build/release/pinchos validate
# .build/release/pinchos doctor
# .build/release/pinchos run aws_account
[item.aws_account]
run = "aws sts get-caller-identity --query Account --output text"
interval = "10m"
timeout = "10s"
format = "AWS {output}"
canonical item
aws_accountAWS 123456789012
- aws_account
- 10m · AWS {output}
Copy the item table into your config, replace placeholders, then validate before running it. Add ordered menu rows when the item needs a submenu.
TOML
# Recipe: battery
# Category: Power
#
# Purpose: show battery charge percentage and power source in the menu bar.
# Dependencies: none beyond the macOS base system (/usr/bin/pmset).
# Expected output: "80%" while running on battery or AC power.
# The value is machine-dependent (desktops and battery-less machines
# report no matching line, see limitations) and reflects whatever
# `pmset -g batt` reports at the moment the command runs.
# Limitations: on a Mac with no battery (e.g. a desktop, or a VM), the
# `grep` finds nothing and `run` exits 1. This recipe uses a shell pipeline
# (`|`), so review the command before installing it.
#
# Copy this file's [item.*] table(s) into your pinchos.toml, then:
# .build/release/pinchos validate
# .build/release/pinchos doctor
# .build/release/pinchos run battery
[item.battery]
run = "pmset -g batt | grep -Eo '[0-9]+%' | head -1"
interval = "1m"
format = "🔋 {output}"
canonical item
battery🔋 80%
- battery
- 1m · 🔋 {output}
Copy the item table into your config, replace placeholders, then validate before running it. Add ordered menu rows when the item needs a submenu.
TOML
# Recipe: clock
# Category: Time
#
# Purpose: show the current local time in the menu bar.
# Dependencies: none beyond the macOS base system (/bin/date).
# Expected output: "14:07" (24-hour HH:MM, updates every 30 seconds).
# The value is locale- and timezone-dependent: it reflects the format
# string below and the machine's current timezone, not a fixed locale.
# Limitations: `date` is available on the macOS base system. Change the format
# string (see `man strftime`) to show seconds, a date, or a timezone
# abbreviation, e.g. "+%H:%M:%S %Z".
#
# Copy this file's [item.*] table(s) into your pinchos.toml, then:
# .build/release/pinchos validate
# .build/release/pinchos doctor
# .build/release/pinchos run clock
[item.clock]
run = "date '+%H:%M'"
interval = "30s"
# {output} is the trimmed last stdout line of `run` (here, the whole line).
format = "{output}"
canonical item
clock14:07
- clock
- 30s · {output}
Copy the item table into your config, replace placeholders, then validate before running it. Add ordered menu rows when the item needs a submenu.
TOML
# Recipe: disk-free
# Category: System
#
# Purpose: show the human-readable free space on the root volume.
# Dependencies: none beyond the macOS base system (/bin/df and awk).
# Expected output: "412Gi" or another machine-specific free-space value.
# Limitations: this checks only `/`; external volumes and per-user quotas
# are outside its scope.
# This recipe uses a shell pipeline. Review the command before installing it.
[item.disk_free]
run = "df -h / | awk 'NR==2{print $4}'"
interval = "5m"
format = "free {output}"
canonical item
disk_freefree 412Gi
- disk_free
- 5m · free {output}
Copy the item table into your config, replace placeholders, then validate before running it. Add ordered menu rows when the item needs a submenu.
TOML
# Recipe: github-open-prs (optional third-party tool)
# Category: GitHub
#
# Purpose: show the number of open pull requests visible to the GitHub CLI.
# Dependencies: the GitHub CLI (`gh`), install from https://cli.github.com/.
# Authenticate with `gh auth login`; no token belongs in this file.
# Expected output: "7" for seven open pull requests in the default scope.
# Limitations: `gh pr list` defaults to the current repository when run from
# one, and to its configured context; replace the command with `--repo`
# when you need a fixed repository.
[item.github_open_prs]
run = "gh pr list --state open --limit 100 --json number --jq 'length'"
interval = "5m"
timeout = "15s"
format = "PRs {output}"
canonical item
github_open_prsPRs 7
- github_open_prs
- 5m · PRs {output}
Copy the item table into your config, replace placeholders, then validate before running it. Add ordered menu rows when the item needs a submenu.
TOML
# Recipe: http-health
# Category: Network
#
# Purpose: show the HTTP status code of a health/uptime endpoint, so a
# non-2xx response is visible from the menu bar.
# Dependencies: `curl`, which ships with macOS at /usr/bin/curl.
#
# Network recipe: `https://example.com` below is a placeholder. IANA
# reserves example.com for documentation and it normally answers with a
# real 200, but it is not your service and is not a commitment of uptime —
# replace it with an endpoint you own or operate before relying on this
# for anything.
#
# Expected output: "200" on success. When no response is received, curl
# prints "000" and exits with a network-specific status.
# Network-, endpoint-, and route-dependent by design.
# Limitations: `--max-time 5` bounds curl itself; the item's own
# `timeout = "8s"` is a second, independent bound. This recipe is not
# exercised in CI (no network there); it is syntax-checked only.
# This is a single command (no shell pipeline), so it is easy to review.
#
# Copy this file's [item.*] table(s) into your pinchos.toml, replace the
# URL, then:
# .build/release/pinchos validate
# .build/release/pinchos doctor
# .build/release/pinchos run http_health
[item.http_health]
run = "curl -s -o /dev/null -w '%{http_code}' --max-time 5 https://example.com"
interval = "5m"
timeout = "8s"
format = "HTTP {output}"
canonical item
http_healthHTTP 200
- http_health
- 5m · HTTP {output}
Copy the item table into your config, replace placeholders, then validate before running it. Add ordered menu rows when the item needs a submenu.
TOML
# Recipe: load-average
# Category: System
#
# Purpose: show the one-minute load average as a compact saturation signal.
# Dependencies: none beyond the macOS base system (/usr/sbin/sysctl and awk).
# Expected output: "1.42" or another machine- and workload-dependent value.
# Limitations: load average is not CPU percentage and should be read beside
# the machine's core count; it also includes runnable and uninterruptible
# work.
[item.load_average]
run = "sysctl -n vm.loadavg | awk '{print $2}'"
interval = "30s"
format = "load {output}"
canonical item
load_averageload 1.42
- load_average
- 30s · load {output}
Copy the item table into your config, replace placeholders, then validate before running it. Add ordered menu rows when the item needs a submenu.
TOML
# Recipe: vpn-network
# Category: Network
#
# Purpose: two items covering network connectivity: which interface
# currently owns the default route, and a best-effort heuristic for
# whether a VPN tunnel interface is carrying traffic.
# Dependencies: none beyond the macOS base system (/sbin/ifconfig,
# /sbin/route).
#
# Both commands use a shell pipeline (`|`). Review the commands before
# installing them.
# --- network -----------------------------------------------------------
# Expected output: "en0" or "en7" (the BSD name of the interface
# currently holding the default route), or "offline" if there is none.
# Machine- and network-dependent: the interface name depends on this
# Mac's hardware and which network it is joined to.
[item.network]
run = "route -n get default 2>/dev/null | awk '/interface:/{print $2}' | sed 's/^$/offline/'"
interval = "30s"
# --- vpn -----------------------------------------------------------
# Expected output: "1" (or higher) when at least one `utun` tunnel
# interface has an IPv4 address assigned, "0" otherwise.
# Limitations: this is a heuristic, not an authoritative VPN indicator.
# macOS also creates `utun` interfaces for services unrelated to a
# user-initiated VPN (e.g. Personal Hotspot, some Screen Time / content
# filter configurations); those typically only carry an IPv6
# link-local address and are excluded here by requiring an IPv4
# ("inet") line, but a corporate MDM profile or another local
# networking tool could still cause a false positive. Treat the
# output as "likely tunnel activity", not certainty.
[item.vpn]
run = "ifconfig | awk '/^utun[0-9]+:/{iface=1;next} /^[a-zA-Z0-9_.]+:/{iface=0} iface && /^[[:space:]]+inet[[:space:]]/{print}' | wc -l | tr -d ' '"
interval = "30s"
format = "{output}"
canonical items
networken0vpn1
- network
- 30s · {output}
- vpn
- 30s · {output}
Copy the item table into your config, replace placeholders, then validate before running it. Add ordered menu rows when the item needs a submenu.
No recipes match that filter. Clear the search to see the full catalog.