Amp completions

Shell completion for the Amp coding agent's amp CLI, generated from Amp's own help output and distributed as a checked-in Carapace spec.

It works with Bash, Zsh, Fish, Nushell, PowerShell, and other shells supported by Carapace. Commands, flags, fixed values, and filesystem arguments are generated statically. Completing threads, projects, tools, skills, MCP servers, model-provider connections, and domains runs a small helper that calls Amp, so those completions reflect the resources available to the signed-in user.

amp th<Tab>        → thread, threads
amp --mode m<Tab>  → medium

Install

First install and configure Carapace. Then clone this repository and install the spec:

git clone https://github.com/meatcar/amp-completions.git
cd amp-completions
make install

Open a new shell after installation. make install copies amp.yaml to the Carapace user spec directory under ${XDG_CONFIG_HOME:-$HOME/.config} and installs the dynamic completion helper under carapace/bin. The helper uses Python 3 and may run an Amp JSON-listing command for account-backed completions.

Nix

Build a spec from the Amp package pinned by this flake:

nix build github:meatcar/amp-completions

The spec is written to result/share/carapace/specs/amp.yaml. A consuming flake can select its own Nixpkgs and Amp package by following both inputs:

inputs.amp-completions = {
  url = "github:meatcar/amp-completions";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.llm-agents.follows = "llm-agents";
};

Reference the generated file from Home Manager, standalone or as a NixOS module, to build it during activation. For example:

xdg.configFile."carapace/specs/amp.yaml".source =
  "${inputs.amp-completions.packages.${pkgs.system}.default}/share/carapace/specs/amp.yaml";
xdg.configFile."carapace/bin/amp-completions".source =
  "${inputs.amp-completions.packages.${pkgs.system}.default}/share/carapace/bin/amp-completions";

The Amp package does not need to come from llm-agents. Build and install completions for any Amp executable in the Nix store with the package constructor:

let
  ampCompletions = inputs.amp-completions.lib.mkAmpCompletions {
    inherit pkgs;
    amp = "${myAmpPackage}/bin/amp";
  };
in
{
  xdg.configFile."carapace/specs/amp.yaml".source =
    "${ampCompletions}/share/carapace/specs/amp.yaml";
  xdg.configFile."carapace/bin/amp-completions".source =
    "${ampCompletions}/share/carapace/bin/amp-completions";
}

The executable must support amp --help, nested command help, and amp version; generation does not make network requests.

How it works

src/amp_completions/generate.py recursively reads amp --help and each subcommand's help into one command model. That model produces two files:

• amp.yaml is the completion spec installed by users.
• amp-manifest.json records canonical command and flag paths for update safety checks.

Both files identify the Amp version that produced them. The generator also supplies semantic values that help output cannot describe, such as agent modes, visibility levels, orb sizes, and ship behavior. It also adds file and directory completion to path-like arguments. For account-specific values, the generated spec invokes amp-completions, which converts Amp's JSON listing commands into Carapace candidates.

The pinned Amp executable comes from llm-agents.nix. Generated output is deterministic and checked in, so changes are reviewable. Only dynamic resource completion runs Amp.

Development

Regenerate the spec through the Nix development shell, then run all checks:

nix develop --command make generate
nix flake check

To test another Amp build:

AMP_BIN=/path/to/amp make generate
AMP_BIN=/path/to/amp make check

Do not edit amp.yaml or amp-manifest.json by hand. nix flake check checks formatting, rejects stale or nondeterministic generated files, and runs the parser, policy, workflow, and completion tests.

Automated updates

• Update Amp checks four times a day, shortly after upstream Amp packages usually update. Every generated update that passes the parser, determinism, scope, size, and full flake checks merges automatically if main still matches the revision that was checked. Command and flag removals remain visible in the pull request but do not require maintainer input. If main advances during validation, the next scheduled run rebuilds the candidate instead of merging stale validation. New and changed commands, flags, aliases, and help text are discovered automatically. Semantic completion rules are curated: an existing recognized flag name automatically keeps its enum or filesystem completion, but a new resource argument, a changed enum, or a changed JSON response shape requires a generator/helper update.
• Update flake inputs updates the non-Amp root inputs weekly and merges them under the same rules. It cannot change llm-agents or files other than flake.lock.
• Merge gate is a required check, posted by a dedicated GitHub App, that decides whether a pull request may merge without review. It runs trusted code from main and passes only open pull requests from this repository into main whose changes stay within src/, tests/, amp.yaml, amp-manifest.json, flake.lock, and README.md. Changes to workflows, Nix files, or agent configuration always need a maintainer.
• Renovate updates SHA-pinned GitHub Actions. It does not update Nix inputs or merge pull requests. Current and pending updates appear in the Dependency Dashboard.

All update candidates run the same checks as pull requests before they are pushed. The update workflows use the scoped GITHUB_TOKEN; only the merge gate holds a credential, its app key, in a merge-gate environment limited to main. When an Amp update fails twice in a row at the same step, the workflow opens a locked amp-update-failure issue and closes it after the next successful run.

Amp threads that handle this automation without supervision start with [automation-guard: unattended]. The automation guard plugin then restricts them to allowlists of tools, gh commands, API writes, and hosts. They may push only with git push origin HEAD:refs/heads/amp/<branch>. Anything else, including guardrail edits and branch-protection bypass, needs owner approval. The guard parses command text, so it prevents mistakes rather than enforcing permissions. Threads a person starts are unaffected.

Maintainer notes

Run either updater manually:

gh workflow run update-amp.yml --ref main
gh workflow run update-flake-inputs.yml --ref main

Rerun the owning workflow to rebuild a failed, stale, or conflicting candidate from current main; do not edit generated branches. Renovate pull requests always require review. safe-update marks additive Amp updates; validated compatibility changes also merge automatically.

The merge gate needs a GitHub App with checks write, contents read, and pull requests read, installed only on this repository. Store its client ID as the MERGE_GATE_CLIENT_ID variable and its private key as the MERGE_GATE_PRIVATE_KEY secret in the merge-gate environment, set the repository variable MERGE_GATE_APP_ID, and require the merge-gate check from that app on main.

The reusable automation/amp-update and automation/flake-update branches may appear beside main after squash merges. Either may be deleted when it has no open pull request; its workflow recreates it when needed.

License

MIT