{"id":49319701,"url":"https://github.com/davedev42/claude-code-completions","last_synced_at":"2026-04-26T17:02:31.581Z","repository":{"id":352168146,"uuid":"1209328728","full_name":"DaveDev42/claude-code-completions","owner":"DaveDev42","description":"Shell completions for the Claude Code CLI (zsh, bash, fish)","archived":false,"fork":false,"pushed_at":"2026-04-26T16:24:28.000Z","size":51,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T16:25:02.974Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DaveDev42.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T10:12:39.000Z","updated_at":"2026-04-26T16:24:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DaveDev42/claude-code-completions","commit_stats":null,"previous_names":["davedev42/claude-code-completions"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/DaveDev42/claude-code-completions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveDev42%2Fclaude-code-completions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveDev42%2Fclaude-code-completions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveDev42%2Fclaude-code-completions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveDev42%2Fclaude-code-completions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DaveDev42","download_url":"https://codeload.github.com/DaveDev42/claude-code-completions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveDev42%2Fclaude-code-completions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32305040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-26T17:02:27.158Z","updated_at":"2026-04-26T17:02:31.575Z","avatar_url":"https://github.com/DaveDev42.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-code-completions\n\nShell completions for the [Claude Code](https://claude.ai/code) CLI.\n\nSupports **zsh**, **bash**, and **fish**. Completions are auto-generated\nfrom `claude --help` on your machine and refresh the moment `claude`\nupdates, so they always match your installed version — no separate package\nrelease required to track upstream changes.\n\nWhy bother:\n- **Always in sync.** The completion is derived from `claude --help` at\n  the exact version you have installed. New flag added upstream → next\n  shell picks it up.\n- **Fast.** A path+mtime sentinel skips `claude --version` on warm shells\n  (≈40ms vs 1.16s on a cold cache).\n- **Self-diagnosing.** `claude-code-completions doctor` and `audit` make\n  failure modes legible instead of \"tab just stopped working\".\n\n## Requirements\n\n- Node.js ≥ 18 (used at runtime by the generator)\n- One of zsh / bash / fish\n- `claude` CLI on your `PATH` (without it, the loader falls back to a\n  pre-generated static completion shipped with the package)\n\n## Install\n\n### Homebrew (recommended)\n\n```sh\nbrew tap DaveDev42/tap\nbrew install claude-code-completions\n```\n\nTo upgrade later:\n\n```sh\nbrew update \u0026\u0026 brew upgrade claude-code-completions\n```\n\nAfter first install, depending on your shell:\n\n**zsh** — completions directory is automatically picked up if your\n`$fpath` already includes Homebrew's `site-functions`. If not, add to\n`~/.zshrc`:\n\n```sh\nfpath=(\"$(brew --prefix)/share/zsh/site-functions\" $fpath)\nautoload -Uz compinit \u0026\u0026 compinit\n```\n\n**bash** — add to `~/.bashrc`:\n\n```sh\nsource \"$(brew --prefix)/etc/bash_completion.d/claude.bash\"\n```\n\n**fish** — works out of the box; Homebrew installs into\n`~/.config/fish/completions/`.\n\n### Manual install\n\n```sh\ngit clone https://github.com/DaveDev42/claude-code-completions.git\ncd claude-code-completions\n# zsh\nln -s \"$PWD/completions/_claude\" ~/.local/share/zsh/site-functions/_claude\n# bash\necho \"source $PWD/completions/claude.bash\" \u003e\u003e ~/.bashrc\n# fish\nln -s \"$PWD/completions/claude.fish\" ~/.config/fish/completions/claude.fish\n```\n\n## How it works\n\nTwo layers:\n\n1. **Thin loader** (installed into your shell's completion path) — on\n   every shell start, checks a one-line sentinel at\n   `${XDG_CACHE_HOME:-~/.cache}/claude-code-completions/.claude-meta`\n   (format: `path\u003cTAB\u003emtime\u003cTAB\u003eversion`). If the recorded path and mtime\n   match the current `claude` binary, it sources the cached completion\n   without spawning any process. On mismatch (claude was upgraded,\n   reinstalled, or moved), it falls through to the slow path: run\n   `claude --version`, regenerate the cache, prune the previous version's\n   entry, refresh the sentinel.\n2. **Generator** (`claude-code-completions` CLI) — parses `claude --help`\n   into a shell-agnostic intermediate representation, then emits\n   shell-specific completion code. Supplements with manual overrides for\n   things `--help` doesn't expose (e.g. model names, MCP/plugin/auth\n   subcommands).\n\nCache layout under `${XDG_CACHE_HOME:-~/.cache}/claude-code-completions/`:\n\n| File | Purpose |\n|---|---|\n| `_claude-\u003cversion\u003e` | zsh completion for that exact `claude` version |\n| `claude.bash-\u003cversion\u003e` | bash completion |\n| `claude.fish-\u003cversion\u003e` | fish completion |\n| `.claude-meta` | Fast-path sentinel (`path\u003cTAB\u003emtime\u003cTAB\u003eversion`) |\n\nLoaders prune older `_claude-*`, `claude.bash-*`, `claude.fish-*` entries\non the next slow-path miss, so the cache stays at most one entry per\nshell.\n\nThe pre-generated files in `completions/` (and their installed copies\nunder `\u003cbrew prefix\u003e/share/claude-code-completions/*.static`) are\n**fallback only** — used when the generator can't run (e.g. `claude` is\nnot yet on `PATH` after a fresh install). On a normal machine the\nloader-generated cache is always preferred.\n\n## CLI\n\n```sh\n# Generate for one shell, write to ./completions/_claude\nclaude-code-completions generate --shell zsh --out ./completions\n\n# Generate for all supported shells\nclaude-code-completions generate --all --out ./completions\n\n# Pre-warm the runtime cache for the current claude version (all shells),\n# pruning entries for older versions. Run from cron / launchd / a hook /\n# the /upgrade-completion slash command to eliminate first-tab latency\n# right after claude updates.\nclaude-code-completions prefetch\n\n# Audit src/overrides.js against the live `claude --help`. Reports orphan\n# overrides, missing enum values, and drift. Exits non-zero on errors.\nclaude-code-completions audit\n\n# Diagnose the install: claude on PATH, --help works, cache state, loader\n# files in expected locations, parser end-to-end. Exits non-zero on\n# failures.\nclaude-code-completions doctor\n\n# Dump parsed IR as JSON (useful for debugging)\nclaude-code-completions parse\n```\n\n### Troubleshooting\n\nIf completions stop working, run `doctor` first:\n\n```\n$ claude-code-completions doctor\nclaude-code-completions doctor\n  [OK  ] claude binary: 2.1.119 (Claude Code)\n  [OK  ] claude --help: 73 lines\n  [OK  ] cache directory: ~/.cache/claude-code-completions (zsh=1)\n  [OK  ] zsh loader: /opt/homebrew/share/zsh/site-functions/_claude\n  [WARN] bash loader: not at /opt/homebrew/etc/bash_completion.d/claude.bash (ok if you don't use this shell)\n  [OK  ] fish loader: /opt/homebrew/share/fish/vendor_completions.d/claude.fish\n  [OK  ] parser: 52 options, 9 commands parsed\n\n6 ok, 1 warn, 0 fail\n```\n\n`doctor` exits non-zero on `FAIL` so it composes with shell scripts. If\nit reports an issue with overrides specifically, also run `audit` for\nthe detailed list of orphan / missing / extra entries.\n\n## When does this need updating?\n\nTwo distinct flows, and they should not be confused:\n\n1. **`claude` itself updates** (e.g. `claude` 2.1.119 → 2.1.120). The\n   loader handles this entirely on your machine — sentinel mismatch on\n   the next shell, regenerate, prune. No package release, no `brew\n   upgrade`, no internet.\n2. **This package itself updates** (parser fix, generator fix, new\n   feature). Use `brew upgrade claude-code-completions`. There's no\n   periodic cron pushing changes — releases happen when there are\n   actual code changes worth shipping.\n\nIf you'd like to verify a refresh worked after a `claude` upgrade, run\n`claude-code-completions prefetch` in any shell.\n\nContributors working in this repository can also use the project-scope\n`/upgrade-completion` slash command, defined in\n`.claude/commands/upgrade-completion.md`. Open this directory with\nClaude Code and the command will be available automatically — it runs\n`prefetch` and falls back to `doctor` on failure.\n\n## Contributing\n\n- To add support for a new shell, implement a generator in\n  `src/generators/\u003cshell\u003e.js` that takes the IR produced by\n  `src/parse.js`, and register it in `bin/claude-code-completions.js`'s\n  `GENERATORS` map.\n- To fix missing enum values or subcommand options, edit\n  `src/overrides.js`. The next `audit` run flags drift against\n  `claude --help`.\n- `npm test` runs four suites: parse, generators (round-trip + mutex +\n  escape + variadic), audit, and doctor smoke. Add cases there for any\n  IR shape the parser starts producing.\n\nCI runs the same `npm test` plus syntax-checks the pre-generated\ncompletions with `zsh -n`, `bash -n`, and `fish -n`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavedev42%2Fclaude-code-completions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavedev42%2Fclaude-code-completions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavedev42%2Fclaude-code-completions/lists"}