Skip to main content

Built-in Providers

Everything on this page ships with comb and works with no setup. Each namespace is ordinary configuration in the managed ~/.config/beachcomber/defaults/ directory, which you can retune or switch off like any other; see Configuration, and Custom Providers to add your own.

Every example below is a real run, with personal details replaced.

Reading this page​

  • Scope. A global namespace has one answer for the whole machine, whatever directory you ask from. A directory namespace answers for the project around the directory you ask from (the repository, the Python project, …), so comb g git.branch gives a different answer in each repository and nothing outside one.
  • Cached or rendered. Most namespaces are computed by the daemon and cached. A few are templates your own shell renders on each read, from its environment, so they follow export AWS_PROFILE=… at once. See The Tree.
  • Absent fields. A field with no value is left out, never "". comb g prints nothing for it and comb g.j prints null.

At a glance​

NamespaceTells youScopeNeeds
hostnameMachine nameglobal—
userLogin name and uidglobal—
unameKernel and architectureglobal—
loadLoad averagesglobal—
uptimeTime since bootglobal—
batteryCharge and charging stateglobala battery
networkInterface, addresses, VPN, Wi-FiglobalLinux SSID: nmcli or iw
sudoWhether sudo is cachedglobalLinux only, in practice
gitBranch, status, divergencedirectorygit
pythonVirtualenv and interpreter versiondirectory—
miseTool versions mise has in effectdirectorymise
asdfTool versions from .tool-versionsdirectory—
direnvWhether the .envrc is alloweddirectory—
terraformSelected workspacedirectory—
aws, aws_profilesProfile and region in effect; every profile's regionglobal—
gcloud, gcloud_configsProject and account in effect; every configurationglobal—
kubecontextkubectl context and namespaceglobalkubectl
talostalosctl contextglobaltalosctl
condaActive conda environmentglobal—
opWhether a 1Password service-account token is setglobal—

"Needs" is what must be installed for the namespace to have values. A tool the daemon runs (git, mise) must be on the daemon's PATH, which is the PATH of the shell that started it. A tool a template runs (kubectl, talosctl) must be on your shell's PATH.

System​

These read the operating system directly through the sys plugin compiled into comb. Only two spawn a process: battery on macOS (pmset) and the Wi-Fi name in network.

hostname​

The machine's name. Polled every 10 minutes while read.

FieldMeaningExample
nameFull hostnamelaptop.local
shortThe hostname up to its first .laptop

user​

The user the daemon runs as. Polled every 10 minutes.

FieldMeaningExample
nameLogin name; absent for a uid with no account entryjane
uidNumeric user id501

uname​

The kernel, as uname reports it. Polled hourly.

FieldMeaningExample
sysnameKernel nameDarwin, Linux
releaseKernel release24.6.0
versionKernel version stringDarwin Kernel Version 24.6.0: …
machineHardware architecturearm64, x86_64

load​

The 1, 5 and 15 minute load averages. Polled every 10 seconds.

FieldMeaningExample
one1-minute average2.3916015625
five5-minute average1.873046875
fifteen15-minute average1.4189453125

The values are unrounded; round them in a template ({{ load.one | round(1) }}).

uptime​

Time since boot. Polled every minute. days, hours and minutes split seconds up, so the uptime is daysd hoursh minutesm.

FieldMeaningExample
secondsSeconds since boot4529149
daysWhole days52
hoursHours past the last whole day (0–23)10
minutesMinutes past the last whole hour (0–59)5

battery​

The battery's charge. Polled every 30 seconds. macOS reads pmset -g batt; Linux reads the first battery under /sys/class/power_supply. A machine with no battery has no battery fields.

FieldMeaningExample
percentCharge, 0–10080
chargingWhether it is chargingfalse
statuscharging, discharging, charged, calculating or unknowndischarging
time_remaining_secsEstimated seconds to empty or full; absent when there is no estimate7200
status_rawLinux only: the kernel's own status wordDischarging

network​

The network connection. Polled every 10 seconds.

FieldMeaningExample
interfaceThe preferred interface: an en* one on macOS, the default route's on Linuxen0
ipIts IPv4 address192.168.1.42
ipv6The first routable IPv6 addressfd00::1c87:ef81:7850:3561
vpn_activeWhether a VPN interface is uptrue
vpn_nameThe first VPN interfaceutun0
ssidWi-Fi network name; absent on macOS 14.4 and later, which removed the airport toolHomeNet
onlineWhether there is an address at alltrue

On Linux the SSID comes from nmcli, else iw.

sudo​

Whether sudo would run without asking for a password: the user's sudo timestamp is under five minutes old. Polled every 30 seconds.

FieldMeaningExample
activeWhether sudo is cachedtrue

It reads /var/run/sudo/ts/$USER, else /run/sudo/ts/$USER. Where that directory is readable only by root (many Linux systems), and always on macOS, which keeps its timestamps under /var/db/sudo, active is absent rather than false.

Git​

git​

The repository around the directory you ask from: the nearest .git above it, including a linked worktree or a submodule. Outside a repository there are no git fields, and a nested repository shows only its own values. The compiled-in git plugin reads HEAD and the refs straight from .git, and runs git for the rest. Each group of fields reruns only when the files it depends on change (the working tree, the index or the refs), with polling as a backstop.

$ comb g git
ahead=1
behind=0
branch=feature/login
branch_default=main
branch_parent=main
commit=21520f4
commit_summary=Fix login redirect
conflicted=0
detached=false
dirty=true
last_commit_age_secs=5
last_commit_timestamp=1793740680
lines_added=1
lines_added_default=2
lines_added_parent=2
lines_removed=0
lines_removed_default=0
lines_removed_parent=0
lines_staged_added=1
lines_staged_removed=0
push_ahead=1
push_behind=0
staged=1
stash=1
state=clean
tag=v0.1.0
unstaged=1
untracked=1
upstream=origin/feature/login

Branch and commit

FieldMeaningExample
branchCurrent branch; absent on a detached HEADfeature/login
detachedWhether HEAD is detachedfalse
commitShort hash of HEAD; absent before the first commit21520f4
commit_summaryFirst line of HEAD's commit messageFix login redirect
last_commit_timestampWhen HEAD was committed, in Unix seconds1793740680
last_commit_age_secsSeconds since HEAD was committed, worked out from last_commit_timestamp as you read it3420
tagNearest tag reachable from HEAD; absent when nonev0.1.0

Working tree

FieldMeaningExample
dirtyWhether anything is staged, changed, untracked or conflictedtrue
stagedFiles staged1
unstagedTracked files changed but not staged1
untrackedUntracked files1
conflictedFiles with merge conflicts0
lines_addedLines added in unstaged changes1
lines_removedLines removed in unstaged changes0
lines_staged_addedLines added in staged changes1
lines_staged_removedLines removed in staged changes0
stashStash entries1

Remotes

FieldMeaningExample
upstreamThe branch's upstream; absent when it has noneorigin/feature/login
aheadCommits ahead of the upstream; absent without one1
behindCommits behind the upstream; absent without one0
push_aheadCommits ahead of the branch on the push remote (branch.<name>.pushRemote, else remote.pushDefault); absent when neither is set1
push_behindCommits behind it0

Operation in progress

FieldMeaningExample
stateclean, merge, rebase, cherry-pick, bisect or revertrebase
state_stepCurrent step of a rebase; absent otherwise2
state_totalTotal steps of a rebase; absent otherwise5

Lineage: how far this branch has moved from the branch it came from and from the default branch. These count committed changes since the merge base, not the working tree, and are absent on a detached HEAD.

FieldMeaningExample
branch_parentThe branch this one was created from, per its reflog; else the default branchmain
lines_added_parentLines added since leaving branch_parent2
lines_removed_parentLines removed since leaving branch_parent0
branch_defaultThe default branch: origin/HEAD's, else a local main or master; absent when none is foundmain
lines_added_defaultLines added since diverging from branch_default2
lines_removed_defaultLines removed since diverging from branch_default0

When the default branch comes from origin/HEAD, the comparison is with origin/<name>, so a checkout on the default branch still counts what it has not pushed.

Development tools​

python​

The Python project around the directory: the nearest directory with a pyproject.toml or a virtualenv (.venv, venv, .virtualenv or env holding a pyvenv.cfg). Reruns when the virtualenv or pyproject.toml changes.

$ comb g.j python
{
"local_venv_name": ".venv",
"venv": true,
"venv_name": ".venv",
"venv_version": "3.12.4",
"version": "3.12.4"
}
FieldMeaningExample
venvWhether the project has a virtualenvtrue
local_venv_nameThat virtualenv's directory name.venv
venv_versionThe Python version its pyvenv.cfg records3.12.4
versionRendered: the version in effect, the first of $PYENV_VERSION, $MISE_PYTHON_VERSION, mise.python, asdf.python, venv_version3.12.4
venv_nameRendered: local_venv_name, else the last part of $VIRTUAL_ENV.venv

version and venv_name are rendered in your shell, so they work outside a project too: with VIRTUAL_ENV=/opt/envs/tools set, comb g python.venv_name is tools.

mise​

The tools mise has in effect: each tool's version as mise ls --current reports it, run at the nearest directory with a mise.toml or .mise.toml, else at ~. That answer already includes mise's global tools and its parent configs. A tool the project does not set comes from ~. Reruns when either file, or mise's global config directory, changes. Needs mise on the daemon's PATH.

$ comb g.j mise
{
"node": "22.22.1",
"python": "3.13.3",
"rust": "1.95.0"
}

There is one field per tool, named as mise names it: comb g mise.node. A name holding a . or / (such as go:golang.org/x/tools/gopls) is quoted in brackets: comb g 'mise["go:golang.org/x/tools/gopls"]'.

asdf​

The tools set in .tool-versions: the nearest one above the directory, then the global ~/.tool-versions (else ~/.config/asdf/tool-versions) for any tool the project does not set. One field per tool, holding its first version. Reads the file itself; asdf does not need to be installed.

$ cat ~/.tool-versions
nodejs 18.0.0
terraform 1.7.0
$ cat ~/tv/.tool-versions
nodejs 20.11.0
ruby 3.3.0
$ comb g.j asdf ~/tv/sub
{
"nodejs": "20.11.0",
"ruby": "3.3.0",
"terraform": "1.7.0"
}

direnv​

Whether direnv allows the nearest .envrc above the directory. It reads direnv's own allow and deny records under $XDG_DATA_HOME/direnv (by default ~/.local/share/direnv), so it needs no process; an edit to the .envrc, or direnv allow/direnv deny, shows on the next read. Absent outside a directory with an .envrc.

FieldMeaningExample
statusallowed, blocked (not yet allowed, or edited since) or deniedblocked
allowedWhether status is allowedfalse

terraform​

The workspace selected in the nearest directory holding .terraform. Absent outside one.

FieldMeaningExample
workspace$TF_WORKSPACE when your shell sets it, else the workspace in .terraform/environment, else defaultstaging
$ comb g terraform.workspace
staging
$ TF_WORKSPACE=prod comb g terraform.workspace
prod

Cloud​

The cloud namespaces come in pairs. aws_profiles and gcloud_configs are cached by the daemon: every profile or configuration on the machine, whatever your shell has selected. aws and gcloud are rendered in your shell and pick the one your environment selects, so two shells with different AWS_PROFILE each see their own. Neither needs the cloud CLI installed.

aws​

The AWS profile and region in effect in your shell.

FieldMeaningExample
profile$AWS_PROFILE, else $AWS_VAULT, else $AWS_DEFAULT_PROFILE, else defaultwork-prod
region$AWS_REGION, else $AWS_DEFAULT_REGION, else that profile's region from aws_profileseu-west-1
expirationWhen the session's credentials expire: $AWS_CREDENTIAL_EXPIRATION, else $AWS_SESSION_EXPIRATION2026-11-06T04:00:00Z
$ comb g aws
profile=default
region=us-east-1
$ AWS_PROFILE=work-prod comb g aws
profile=work-prod
region=eu-west-1

aws_profiles​

Every profile in the AWS config file ($AWS_CONFIG_FILE, else ~/.aws/config), each with its region. A profile with no region is left out. Watches the file, and polls it every minute.

$ comb g.j aws_profiles
{
"default": {
"region": "us-east-1"
},
"work-prod": {
"region": "eu-west-1"
}
}

gcloud​

The Google Cloud project and account in effect in your shell.

FieldMeaningExample
project$CLOUDSDK_CORE_PROJECT, else the selected configuration's projectacme-prod
accountThe selected configuration's accountjane@example.com

The selected configuration is $CLOUDSDK_ACTIVE_CONFIG_NAME, else gcloud's active one.

$ comb g gcloud.project
acme-prod
$ CLOUDSDK_ACTIVE_CONFIG_NAME=default comb g gcloud.project
my-sandbox

gcloud_configs​

Every gcloud configuration, from gcloud's config directory ($CLOUDSDK_CONFIG, else ~/.config/gcloud): the active one's name, and each configuration's project and account keyed by its name. Polled every minute.

$ comb g.j gcloud_configs
{
"active_config": "work",
"default": {
"account": "jane@example.com",
"project": "my-sandbox"
},
"work": {
"account": "jane@example.com",
"project": "acme-prod"
}
}

kubecontext​

The kubectl context in effect in your shell, from kubectl config. Rendered in your shell, so it honours your $KUBECONFIG. The command's answer is remembered, and run again when $KUBECONFIG or a kubeconfig file changes, or after 10 minutes. Needs kubectl.

FieldMeaningExample
contextCurrent context; absent when none is set or kubectl is not installeddev-cluster
namespaceThe context's namespace, default when it sets none; absent without a contextweb

talos​

The talosctl context in effect, from talosctl config info. Remembered and rerun as kubecontext is, on $TALOSCONFIG or ~/.talos/config. Needs talosctl.

FieldMeaningExample
contextCurrent context; absent when none is set or talosctl is not installedhomelab

kubecontext and talos run a command, so they render only where a template may run commands: comb get, comb eval, comb watch and comb status, and an SDK client created with its exec option on (off by default). Elsewhere the field is the error exec() is disabled in this context.

Shell environment​

conda​

FieldMeaningExample
envThe active conda environment, $CONDA_DEFAULT_ENV; absent when none is activebase

op​

FieldMeaningExample
service_accountWhether $OP_SERVICE_ACCOUNT_TOKEN is set in your shell. Never the token, and nothing about whether it is validfalse