# Shell Builtins

Use when creating a new shell builtin command for Crush (internal/shell/), editing an...

- Repository: https://github.com/charmbracelet/crush (28908 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add charmbracelet/crush --skill shell-builtins -g -a claude-code -y`
Codex: `npx skills add charmbracelet/crush --skill shell-builtins -g -a codex -y`
Cursor: `npx skills add charmbracelet/crush --skill shell-builtins -g -a cursor -y`
Gemini CLI: `npx skills add charmbracelet/crush --skill shell-builtins -g -a gemini-cli -y`

## Description

Use when creating a new shell builtin command for Crush (internal/shell/), editing an existing one, or when the user needs to understand how commands are intercepted in Crush's embedded shell.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Shell Builtins

Crush's shell (`internal/shell/`) uses `mvdan.cc/sh/v3` for POSIX shell
emulation. Commands can be intercepted before they reach the OS by adding
**builtins**, functions handled in-process.

## How Builtins Work

Builtins live in `builtinHandler()` in `internal/shell/run.go`. This is an
`interp.ExecHandlerFunc` middleware registered in `standardHandlers()`
**before** the block handler, so builtins run even for commands that would
otherwise be blocked. The same handler chain is shared by the stateful
`Shell` type and the stateless `Run` entrypoint used by the hook runner,
so builtins are available identically in the `bash` tool and in hooks.

The handler is a switch on `args[0]`. Each case either handles the command
inline or delegates to a helper function.

## Adding a New Builtin

The rest: https://github.com/charmbracelet/crush/blob/HEAD/.agents/skills/shell-builtins/SKILL.md