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

Quick Guide

• How do I add/modify an Action? → references/action.md
• How does argument traversal work? → references/traverse.md
• How do non-POSIX flags work? → references/pflag.md
• Which shells support which features? → references/shell.md
• How does a specific shell format completions? → references/shell-{name}.md
• How do styles/colors work? → references/style.md
• How do bridges work internally? → references/bridge.md
• How does the global storage map work? → references/storage.md
• How do I write/run sandbox tests? → references/sandbox.md
• How does Batch parallel invocation work? → references/batch.md
• How does Action.Cache work? → references/cache.md
• How do UID identifiers work? → references/uid.md
• How is styles.json loaded? → references/config-env.md
• How does spec YAML generation work? → references/spec.md
• What is the JSON wire format? → references/export.md
• What conditional helpers exist? → references/conditionals.md
• How does the _carapace CLI work? → references/command-cli.md
• How does the mock system work? → references/mock.md

Cross-Project References

• For user-facing topics (integrating carapace into a CLI, writing specs, macros, setup, choices), use the carapace skill (in the carapace-bin repo).
• For in-depth bash shell knowledge (programmable completion, Readline, quoting/expansion, execution model, startup files), use the bash skill (in this repo).
• For in-depth bash BLE/ble.sh knowledge (cand/yield, completion sources and actions, menu styles, menu-filter, progcomp integration, sabbrev, dabbrev, auto-complete, syntax highlighting, faces, gspec colors, widgets, keymaps, bleopt, ble-bind, blehook, blerc, ble-import), use the bash-ble skill (in this repo).
• For in-depth clink/cmd.exe knowledge (argmatcher API, match generators, Readline integration, DLL injection, prompt filtering, auto-suggestions, input line coloring), use the cmd-clink skill (in this repo).
• For in-depth elvish shell knowledge (arg-completer, complex-candidate, matcher, editor API, styled text, language fundamentals, modules, rc.elv), use the elvish skill (in this repo).
• For in-depth xonsh shell knowledge (RichCompletion, CommandContext, contextual_command_completer, completer pipeline, prompt-toolkit integration, Python/shell hybrid model, xontribs, event system, rc.xsh), use the xonsh skill (in this repo).
• For in-depth fish shell knowledge (complete builtin, commandline builtin, pager, autosuggestions, syntax highlighting, abbreviations, key bindings, language fundamentals, job control, startup configuration), use the fish skill (in this repo).
• For in-depth PowerShell knowledge (Register-ArgumentCompleter, PSReadLine, CompletionResult, CommandAst, tab completion, menu completion, prediction plugins, $PSStyle ANSI rendering, quoting rules, argument passing to native commands, profiles and configuration), use the powershell skill (in this repo).
• For in-depth tcsh shell knowledge (complete builtin, COMMAND_LINE, programmable completion, bindkey, command-line editor, quoting/expansion, execution model, startup files, addsuffix, autolist, wordchars, tenematch), use the tcsh skill (in this repo).
• For in-depth Oil/OSH/YSH shell knowledge (programmable completion, COMP_ARGV, compadjust, compexport, OILS_COMP_UI, NiceDisplay, Readline, quoting model, simple word evaluation, lastpipe, strict:all, ysh:all, headless mode, parser-as-library, startup configuration), use the oil skill (in this repo).
• For in-depth hilbish shell knowledge (hilbish.completions, completion handler, completion groups grid/list, TabCompleter, readline integration, Lua API, bait event system, runner mode, commander, lunacolors, syntax highlighting, hinter, vim mode, job control, init.lua configuration), use the hilbish skill (in this repo).