carapace-sh/carapace-bin / skills/carapace
carapace
VerifiedUse when working with carapace shell completion — integrating into CLIs, writing YAML specs, creating custom actions, building completion-aware lexers for DSLs, looking up macros, setting up shell completion, configuring choices/bridges, using the MCP server, or adding man page documentation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.0 KB |
| references/action.md | markdown | 20.8 KB |
| references/choice.md | markdown | 9.0 KB |
| references/convert.md | markdown | 10.5 KB |
| references/env.md | markdown | 7.8 KB |
| references/integrate.md | markdown | 29.1 KB |
| references/lexer.md | markdown | 24.3 KB |
| references/macro.md | markdown | 19.4 KB |
| references/man.md | markdown | 13.5 KB |
| references/mcp.md | markdown | 14.0 KB |
| references/scrape.md | markdown | 6.3 KB |
| references/setup.md | markdown | 6.8 KB |
| references/spec.md | markdown | 8.0 KB |
| references/update.md | markdown | 11.2 KB |
references/choice.md
View on GitHub# Carapace Choices, Variants & Bridges
How carapace resolves which completer to use when multiple sources exist for the same command.
## Completer Sources
A single command can have completers from multiple sources:
| Source | Location | Group |
|--------|----------|-------|
| Native Go completers | `completers/` (built-in) | `common`, `unix`, `linux`, `darwin`, `bsd`, `freebsd`, `netbsd`, `openbsd`, `windows`, `android` |
| User YAML specs | `${UserConfigDir}/carapace/specs/` | `user` |
| Known bridges | hardcoded in `bridges.go` (72 commands) | `bridge` |
| Shell bridges | enabled via `CARAPACE_BRIDGES` | `bridge` |
| Overlays | `${UserConfigDir}/carapace/overlays/` | modifies existing variant |
> The `system` group exists in the priority map but no loader currently populates it; specs in `${UserConfigDir}/carapace/specs/` are loaded as group `user`.
## Group Priority
When multiple groups provide a completer for the same command, they resolve in this order (highest wins):
1. **A choice** (set via `--choice`) — overrides everything
2. **`user`** — user YAML specs
3. **Current shell** — the group matching `CARAPACE_SHELL` (e.g. `bash`, `zsh`) is boosted above all OS groups
4. **Current OS group** (`runtime.GOOS`)
5. **Other OS groups** — base priority order: `linux`, `unix`, `darwin`, `freebsd`, `netbsd`, `openbsd`, `bsd`, `windows`, `android`, `common`
6. **`bridge`** — lowest priority above shell-builtin bridges
7. **Shell builtin groups** (`bash`, `zsh`, `fish`, …) — below `bridge` so they don't shadow real command completers
Within the same group, variants are ordered alphabetically by name — except group `bridge`, which follows the order in `CARAPACE_BRIDGES`.
## Listing Variants
```sh
carapace --list {command} # list all variants for a command
carapace --list @{group} # list completers in a group
carapace --list gh@bridge # list bridge variants for 'gh'
```
## Choices
When multiple variants exist for a command, use `--choice` to select the preferred one:
```sh
carapace --choice {name}[/{variant}][@{group}]
```
Examples:
```sh
# Prefer bsd sed over the default
carapace --choice sed@bsd
# Prefer a specific tldr variant
carapace --choice tldr/tldr-python-client
# Use the cobra bridge for gh instead of the native completer
carapace --choice gh/cobra@bridge
```
Choices are persisted as simple text files in `${UserConfigDir}/carapace/choices/`:
```
carapace/
└── choices/
├── sed # content: sed@bsd
└── tldr # content: tldr/tldr-python-client
```
To remove a choice: `carapace --choice -d gh` (deletes the persisted file).
A choice gives that variant the **highest priority**, overriding all group ordering.
## Bridges
Bridges delegate completion to another engine when carapace lacks a native completer.
### Implicit Bridges (Shell-Based)
Enabled via `CARAPACE_BRIDGES`. These discover any command that has completion registered in the source shell:
```sh
export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense'
```
| Bridge | What it uses | Notes |
|--------|-------------|-------|
| `zsh` | Zsh's completion system | Requires zsh installed |
| `fish` | Fish's completion system | Requires fish installed |
| `bash` | Bash's completion system | Requires bash and completions loaded |
| `inshellisense` | [inshellisense](https://github.com/microsoft/inshellisense) | Requires inshellisense installed |
Unset by default — shell bridges are only active when `CARAPACE_BRIDGES` is set. The completer list is **cached** — clear with `carapace --clear-cache` after installing new shells or commands.
> Shell bridges should be a fallback — framework bridges produce better completions with less overhead.
### Explicit Bridges (Framework-Based)
These must be set explicitly via `--choice` or a user spec because carapace **doesn't auto-detect** which framework a tool was built with by default. For example, carapace doesn't know that `gh` (GitHub CLI) uses cobra — you must tell it. To probe a command, use `carapace --detect <cmd>` (wraps the experimental `bridge.Detect()` from carapace-bridge, which tests each bridge type).
**Via choice:**
```sh
carapace --choice gh/cobra@bridge
```
**Via user spec** (in `${UserConfigDir}/carapace/specs/gh.yaml`):
```yaml
# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: gh
description: GitHub CLI
parsing: disabled
completion:
positionalany: ["$carapace.bridge.Cobra([gh])"]
```
### Known Bridges
carapace-bin includes a hardcoded map of 72 commands with their known framework (in `cmd/carapace/cmd/completers/bridges.go`). These are low-priority `bridge` group defaults — a native completer or user choice always overrides them.
Full list of bridge types:
| Bridge | Framework/Source | Macro |
|--------|-----------------|-------|
| `argcomplete` | [kislyuk/argcomplete](https://github.com/kislyuk/argcomplete) | `$carapace.bridge.Argcomplete([cmd])` |
| `argcomplete_v1` | argcomplete (legacy) | `$carapace.bridge.ArgcompleteV1([cmd])` |
| `aws` | [aws/aws-cli](https://github.com/aws/aws-cli) | `$carapace.bridge.Aws([cmd])` |
| `bash` | [bash](https://www.gnu.org/software/bash/) | `$carapace.bridge.Bash([cmd])` |
| `carapace` | [carapace-sh/carapace](https://github.com/carapace-sh/carapace) | `$carapace.bridge.Carapace([cmd])` |
| `carapace-bin` | carapace-bin registry | `$carapace.bridge.CarapaceBin([cmd])` |
| `clap` | [clap-rs/clap](https://github.com/clap-rs/clap) (experimental) | `$carapace.bridge.Clap([cmd])` |
| `click` | [pallets/click](https://github.com/pallets/click) | `$carapace.bridge.Click([cmd])` |
| `cobra` | [spf13/cobra](https://github.com/spf13/cobra) | `$carapace.bridge.Cobra([cmd])` |
| `complete` | [posener/complete](https://github.com/posener/complete) | `$carapace.bridge.Complete([cmd])` |
| `fish` | [fish](https://fishshell.com/) | `$carapace.bridge.Fish([cmd])` |
| `gcloud` | [Google Cloud SDK](https://docs.cloud.google.com/sdk/gcloud) | `$carapace.bridge.Gcloud([cmd])` |
| `inshellisense` | [inshellisense](https://github.com/microsoft/inshellisense) | `$carapace.bridge.Inshellisense([cmd])` |
| `jj` | [jj-vcs](https://www.jj-vcs.dev) | `$carapace.bridge.JJ([cmd])` |
| `kingpin` | [alecthomas/kingpin](https://github.com/alecthomas/kingpin) | `$carapace.bridge.Kingpin([cmd])` |
| `kitten` | [kitty](https://sw.kovidgoyal.net/kitty/) | `$carapace.bridge.Kitten([cmd])` |
| `powershell` | [powershell](https://microsoft.com/powershell) | `$carapace.bridge.Powershell([cmd])` |
| `typer` | [fastapi/typer](https://github.com/fastapi/typer) | `$carapace.bridge.Typer([cmd])` |
| `urfavecli` | [urfave/cli](https://github.com/urfave/cli) | `$carapace.bridge.Urfavecli([cmd])` |
| `urfavecli_v1` | urfave/cli (legacy) | `$carapace.bridge.UrfavecliV1([cmd])` |
| `yargs` | [yargs/yargs](https://github.com/yargs/yargs) | `$carapace.bridge.Yargs([cmd])` |
| `zsh` | [zsh](https://www.zsh.org/) | `$carapace.bridge.Zsh([cmd])` |
Custom shell bridge configurations can be placed in `${UserConfigDir}/carapace/bridge/`.
### How Bridge Resolution Works
The `ActionBridge` function (from carapace-bridge) resolves completions at runtime:
1. **Check choices first** — looks up `~/.config/carapace/choices/<name>`; if a choice exists with `group == "bridge"` (or empty), uses its variant as the bridge type
2. **Fall back to `CARAPACE_BRIDGES`** — iterates the env var in order, checking if the command is known to each shell bridge (bash, fish, zsh, inshellisense)
3. **Return empty** — if neither yields a match, returns no completions
### Determining the Right Bridge
An agent can look up a tool's framework by:
1. Checking the tool's dependencies (e.g. `go list -m` for Go tools, `pip show` for Python)
2. Searching the tool's source code for framework imports (e.g. `import "github.com/spf13/cobra"`)
3. Checking the tool's documentation or `--help` output for framework clues
4. Checking the hardcoded map in `cmd/carapace/cmd/completers/bridges.go` for known mappings
5. Using `carapace --detect <cmd>` (wraps the experimental `bridge.Detect()` from carapace-bridge, which probes a command to auto-detect its completion framework by testing each bridge type)
Common framework signatures:
- **Cobra** (Go): `import "github.com/spf13/cobra"`, completion command `cmd completion <shell>`
- **Click** (Python): `import click`, `@click.command()`
- **Argcomplete** (Python): `import argcomplete`, `argcomplete.autocomplete(parser)`
- **urfave/cli** (Go): `import "github.com/urfave/cli/v2"`, `cli.App{}`
- **Yargs** (Node.js): `require('yargs')`, `yargs.command(...)`
- **Clap** (Rust): `use clap::Parser`, `#[derive(Parser)]`
- **Gcloud** (Python): uses argcomplete internally — check for `gcloud` binary and `CLOUDSDK_*` env vars
## Troubleshooting
- **Completions not appearing after install**: Run `carapace --clear-cache` to refresh the completer list.
- **Wrong completer used**: Check `carapace --list <cmd>` to see variants, then use `--choice` to override.
- **Bridge completions empty**: Ensure the target shell/framework is installed and completions are registered in it.
- **Changes not taking effect**: Restart your shell or re-source the init snippet.Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |