The Problem
Terminal users traditionally rely on muscle memory or cheat sheets for CLI tools. Even experienced practitioners frequently forget subcommands, options, or argument formats across the dozens of tools they use daily. This friction slows workflow and increases cognitive load, particularly when switching between tools or onboarding to new environments.
What This Does
This repo provides IDE-style autocomplete for shell terminals. It delivers contextually relevant subcommands, options, and args as you type, functioning as an Amazon Q Developer CLI (formerly Fig).
The codebase is structured around completion specs—declarative schemas that define CLI behavior. With 119 TypeScript files in src/, the spec layer lives here and gets compiled to the build/ folder on save. The repo uses pnpm (per package.json) and is orchestrated through GitHub Actions workflows in .github/workflows/. Entry points include src/@capgo/cli.ts, src/@magnolia/cli.ts, src/@preset/cli.ts, and src/@usermn/sdc/index.ts. Icons reside in icons/ (49 files), and the dev container is configured via .devcontainer/Dockerfile and .devcontainer/devcontainer.json.
How To Use It
Setup
The repo requires Node and pnpm. From the README:
Install dependencies
pnpm install
Create a new spec (example: "abc")
pnpm create-spec abc
Enable dev mode—specs read from build/, generators run on every keystroke pnpm dev
Configuration
Edit your spec TypeScript file in src/. On save, the spec compiles to build/. In dev mode, the build/ folder is read directly and generators execute on each keystroke, enabling rapid iteration.
Running it
Launch the Amazon Q app to set up the CLI. Once installed, type any supported command (e.g., git, npm, docker, aws) and suggestions will populate contextually.
Real-World Use
A developer working in a terminal frequently runs git with varying subcommands (commit, branch, rebase) and options. With Amazon Q enabled, typing git co triggers suggestions for checkout, config, and other git subcommands, including relevant flags and arguments—all driven by the spec files in src/. This reduces lookup time and minimizes typos across repeated tool usage.
Code Health & Issues
Tests: Only 2 test files are present for a codebase of ~200 files. Test coverage appears sparse relative to the spec surface area. CI/CD: GitHub Actions are configured (workflows for build, lint, typecheck, verify-cla), but the low test count is a gap given the spec-driven architecture. License: LICENSE is present in the root. Dependency hygiene: package.json and pnpm-lock.yaml are present; no obvious version-lock violations detected. Separation of concerns: Specs in src/ compile to build/—the build output directory is not gitignored per the structure, which could lead to merge noise if not managed.
The Bottom Line
The repo delivers a functional, spec-driven autocomplete layer that integrates with major CLIs and supports rapid custom spec development via TypeScript. It’s well-suited for teams or individuals who spend significant time in shell environments and want to reduce command-friction. The primary trade-off is the test coverage mismatch for the spec surface area; adding a test suite for spec validation would improve confidence in changes. Solo practitioners and small teams will find it immediately useful; large organizations with strict CI gate requirements may need to augment the existing workflow.