/carapace-dev

name: carapace-dev
description: >
  Use when developing or debugging the carapace library — Action API, traverse engine,
  shell formatters, style system, pflag extensions, or internal implementation details.
  Triggers on: "carapace" (development context), "carapace Action", "carapace traverse",
  "carapace shell", "carapace style", "pflagfork", "carapace-bridge".
user-invocable: true

Carapace Development Reference

Reference for developing and debugging the [carapace](https://github.com/carapace-sh/carapace) library.

Sub-Resources

Load the reference that matches your task. When in doubt, load multiple references.

| Keywords | Reference | |----------|----------| | Action type, modifier, InvokedAction, Context, callback, Batch, rawValues, suffix naming, NoPrefix, PrefixMatcher | [references/action.md](references/action.md) | | traverse, completion engine, argument classification, pflagfork, shell patching, complete(), dispatch, LookupArg, FlagPrefix, ArgPrefix, DelimiterDisabled, non-POSIX optarg attached values | [references/traverse.md](references/traverse.md) | | pflag, flag mode, NameAsShorthand, ShorthandOnly, Nargs, OptargDelimiter, ArgumentStyle, AcceptsNext, AcceptsDelimited, AcceptsAttached, FlagPrefix, custom flag prefix, non-POSIX flags, DelimiterDisabled, delimiter-disabled attached values | [references/pflag.md](references/pflag.md) | | Shell overview, cross-shell comparison, dispatch pipeline, supported shells, nospace/message/quoting comparison | [references/shell.md](references/shell.md) | | Bash, COMP_TYPE, COMP_WORDBREAKS, redirect patching, partial completion, bash quoting | [references/shell-bash.md](references/shell-bash.md) | | Bash BLE, ble.sh, tab-delimited format, per-candidate suffix, ble/complete/cand/yield | [references/shell-bash-ble.md](references/shell-bash-ble.md) | | Oil, OSH, inline nospace indicator, simpler snippet | [references/shell-oil.md](references/shell-oil.md) | | Zsh, _describe, zstyle, named directory, quoting state machine, CARAPACE_COMPLINE | [references/shell-zsh.md](references/shell-zsh.md) | | Fish, commandline, tab-separated format, open-quote retry, fish pager | [references/shell-fish.md](references/shell-fish.md) | | Elvish, complexCandidate, CodeSuffix, styled, edit:notify, from-json, ParseStyling | [references/shell-elvish.md](references/shell-elvish.md) | | Nushell, from json, JSON record, open-quote patching, style conversion, nushell.Patch | [references/shell-nushell.md](references/shell-nushell.md) | | PowerShell, CompletionResult, Register-ArgumentCompleter, commandAst, SGR color, tooltip | [references/shell-powershell.md](references/shell-powershell.md) | | Xonsh, RichCompletion, prefix_len, append_closing_quote, contextual_command_completer | [references/shell-xonsh.md](references/shell-xonsh.md) | | Style system, XTerm256, TrueColor, ForKeyword, ForPath, ForPathExt, LS_COLORS, style config | [references/style.md](references/style.md) | | Bridge, bridgeActions, actionCommand, output parsing, NoSpace detection, shell config, Detect() | [references/bridge.md](references/bridge.md) | | Storage, global map, mutex, entry, FlagCompletion, PositionalCompletion, PreRun, PreInvoke, storage.get, gotchas | [references/storage.md](references/storage.md) | | Sandbox, Command, Package, Action, Files, Reply, Run, Expect, ExpectNot, ClearCache, SANDBOX env, subprocess isolation | [references/sandbox.md](references/sandbox.md) | | Batch, Invoke, parallelize, Merge, ToA, invokedBatch, goroutine model, shared Context, parallel invocation | [references/batch.md](references/batch.md) | | Cache, Action.Cache, File, Load, Write, cache key, file:line, key.Key types, FolderStats, TTL, sandbox override | [references/cache.md](references/cache.md) | | UID, url.URL, cmd:// scheme, Command, Flag, mLocalFlags mutex, PathEscape, Executable, UidF, uid.Map | [references/uid.md](references/uid.md) | | Config, styles.json, RegisterStyle, Load, CARAPACE_* env vars, LOG, ColorDisabled, Hidden, Sandbox, isGoRun | [references/config-env.md](references/config-env.md) | | Spec, spec.Spec, yaml.Marshal, Command struct, Flags, PersistentFlags, _carapace skip, pflagfork.Flag.Definition | [references/spec.md](references/spec.md) | | Export, Export struct, MarshalJSON, version, RawValue, Meta, cache format, sandbox invoke, ActionImport | [references/export.md](references/export.md) | | Conditionals, Arch, Os, Executable, File, CompletingPath, UnlessF, Context predicates, pkg/condition | [references/conditionals.md](references/conditionals.md) | | _carapace CLI, command.go, addCompletionCommand, spec, style set, export re-invocation, PositionalAnyCompletion, multi-completer, WithSubcommands, WithDefault, WithSnippetFuncs, rewriteArgs, multi.Snippet | [references/command-cli.md](references/command-cli.md) | | Mock, Mock struct, NewMock, Dir, Replies, CacheDir, WorkDir, t interface, Reply mechanism, sandbox integration | [references/mock.md](references/mock.md) |

Quick Guide

• **How do I add/modify an Action?** → [references/action.md](references/action.md)
• **How does argument traversal work?** → [references/traverse.md](references/traverse.md)
• **How do non-POSIX flags work?** → [references/pflag.md](references/pflag.md)
• **Which shells support which features?** → [references/shell.md](references/shell.md)
• **How does a specific shell format completions?** → [references/shell-{name}.md](references/shell-bash.md)
• **How do styles/colors work?** → [references/style.md](references/style.md)
• **How do bridges work internally?** → [references/bridge.md](references/bridge.md)
• **How does the global storage map work?** → [references/storage.md](references/storage.md)
• **How do I write/run sandbox tests?** → [references/sandbox.md](references/sandbox.md)
• **How does Batch parallel invocation work?** → [references/batch.md](references/batch.md)
• **How does Action.Cache work?** → [references/cache.md](references/cache.md)
• **How do UID identifiers wo