code-aide
An aide for your AI coding tools.
Manages installation, upgrade, removal, and version tracking of AI coding CLI tools: Claude Code, Antigravity, Copilot, Cursor, Gemini, Amp, Codex, OpenCode, and Kilo.
Installation
# Run without installing (requires uv)
uvx code-aide status
# Install persistently
uv tool install code-aide
# Or use pipx
pipx install code-aide
Usage
# List available tools and their status
code-aide list
# Show compact one-line-per-tool status
code-aide status
# Show detailed status for installed tools
code-aide status -l
# Install specific tools
code-aide install claude antigravity
# Install all default tools
code-aide install
# Install with automatic prerequisite installation (Node.js, npm)
code-aide install -p
# Upgrade installed tools (no args = only out-of-date tools)
code-aide upgrade [NAMES]
# Remove tools (prompts before removing all managed tools)
code-aide remove [NAMES]
# Preview a removal without changing anything
code-aide remove -n
# Remove all managed tools without prompting
code-aide remove -y
# Check upstream for latest versions (dry-run)
code-aide update-versions -n
# Update version cache
code-aide update-versions -y
Supported Tools
| Tool | Command | Install Type | Default |
|---|---|---|---|
| Cursor CLI | agent |
Direct download | No |
| Claude CLI (Claude Code) | claude |
Script | Yes |
| Antigravity CLI | agy |
Script | Yes |
| Gemini CLI | gemini |
npm | No |
| OpenCode | opencode |
npm | No |
| Kilo CLI | kilo |
npm | No |
| Amp (Sourcegraph) | amp |
Script | No |
| Codex CLI | codex |
npm | No |
| Copilot CLI | copilot |
npm | No |
Command aliases are also accepted: agy resolves to antigravity, and agent
resolves to cursor.
How Version Data Works
code-aide uses a two-layer version data model:
-
Bundled tool definitions (in
data/tools.json): Install methods, URLs, npm packages, version args, and SHA256 checksums. Updated by releasing new versions of code-aide. -
User's local version cache (
~/.config/code-aide/versions.json): Written bycode-aide update-versions. Provides latest versions, dates, updated SHA256 checksums, and recorded tarball checksums for direct_download tools.
Run code-aide update-versions to get the latest version data without waiting
for a new code-aide release.
Tool definition schema (data/tools.json)
Each entry in tools.json describes one managed tool. Required fields are
name, command, and install_type; the others are optional and only
consulted when the relevant install method or platform applies.
| Field | Required | Notes |
|---|---|---|
name |
Yes | Display name for status output |
command |
Yes | Binary name (looked up in PATH) |
aliases |
No | Alternate names accepted by commands and resolved to the canonical tool key |
install_type |
Yes | One of npm, script, direct_download, pkg |
version_args |
No | List of arguments passed to the binary to print its version (default: ["--version"]) |
version_url |
No | URL queried by update-versions to discover the latest upstream version |
version_manifest_url_template |
No | JSON manifest URL template with {platform}; reads its version field |
version_extract_pattern |
No | Regex applied to the install script to extract the version before generic heuristics |
latest_version |
Cache | Last known upstream version (filled by update-versions) |
latest_date |
Cache | Release date for latest_version |
prerequisites |
No | List of required external commands (e.g. ["npm"]) |
min_node_version |
No | Minimum major Node.js version required |
npm_package |
npm | npm package name (e.g. @anthropic-ai/claude-code) |
install_url |
script | URL of the install script that will be downloaded and piped to bash |
install_sha256 |
script | SHA-256 of the install script body — required for verified installs |
download_sha256 |
Cache | SHA-256 of the downloaded tarball for direct_download tools; recorded by update-versions, verified on install |
install_script_path_prepend |
script | Extra directories prepended to PATH when the install script runs (e.g. ["~/.local/bin"]) |
download_url_template |
direct | URL template with {version}, {os}, {arch} placeholders |
install_dir |
direct | Directory to extract into; supports {version} |
bin_dir |
direct | Directory where symlinks for command are created (e.g. ~/.local/bin) |
symlinks |
direct | Map of link_name → relative path inside install_dir to symlink into bin_dir |
freebsd_port |
FreeBSD | FreeBSD ports/pkg name (used when running on FreeBSD) |
freebsd_pkg_repo |
FreeBSD | Optional non-default pkg repository name (passed via pkg install -r <repo>) |
next_steps |
No | Free-form text printed after a successful install |
docs_url |
No | Documentation URL printed after install |
self_updates |
No | Tool updates itself when run; excludes it from managed upgrade actions |
Features
- Zero external dependencies (Python stdlib only)
- SHA256 verification for script-based installations
- Automatic prerequisite detection and installation (Node.js, npm)
- Detects install method (Homebrew, npm, system package, script, direct download)
- PATH configuration validation and warnings
- Supports Linux and macOS
Requirements
- Python 3.11+
- No external Python dependencies
Development
- Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh - Install dependencies:
uv sync - Install pre-commit hooks:
uv tool install pre-commit && pre-commit install - Run tests:
uv run pytest tests/ -v
# Run from development checkout
uv run python -m code_aide status
uv run python -m code_aide install copilot
# Run a specific test
uv run pytest tests/test_install.py::TestDetectOsArch -v
Release
publish.yml publishes to PyPI when a Git tag matching v* is pushed.
- Update the version string in
src/code_aide/__init__.py(__version__).pyproject.tomlreads it automatically via Hatchling. - Run checks:
uv run pytest tests/ -vuv build
- Commit the release version bump:
git add src/code_aide/__init__.pygit commit -m "Bumped version to X.Y.Z"
- Write useful commit messages before tagging:
- Start subject lines with an action verb in past tense (
Added,Changed,Fixed,Removed). - Keep subjects user-facing so auto-generated release notes are meaningful.
- Group related changes into focused commits instead of one broad commit.
- Example:
Fixed timeout handling in status command
- Start subject lines with an action verb in past tense (
- Tag and push to all remotes (origin/GitHub, gitlab, codeberg):
git tag vX.Y.Zgit push origin main && git push origin vX.Y.Zgit push gitlab main && git push gitlab vX.Y.Zgit push codeberg main && git push codeberg vX.Y.Z
- Confirm GitHub Actions:
- CI should pass.
- Publish workflow should upload to PyPI and create GitHub Release notes.
- Release notes should include generated notes plus a commit summary from the previous tag to the current tag.
License
Apache-2.0
1 maintainer
Metadata
1 maintainer
Release files for code-aide 1.17.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| code_aide-1.17.0.tar.gz | 120.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| code_aide-1.17.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 172.1 kB
Release files / code_aide-1.17.0.tar.gz
| Download URL | code_aide-1.17.0.tar.gz |
|---|---|
| Size | 120.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
90ff62cbb59318af4fe47c7071c69e865f31c6610d8be5b7120df099bcb777e8
|
|
BLAKE2b-256 checksum How to use checksums |
36d7a9068722f388cf509990473461a4caade42ed048b7c2cf7e74d63e447449
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 29, 2026.
Transparency logRelease files / code_aide-1.17.0-py3-none-any.whl
| Download URL | code_aide-1.17.0-py3-none-any.whl |
|---|---|
| Size | 51.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
81c13c9c8dc1c354c02e9975eabc80f05bba6727fd836714dae26f739e084901
|
|
BLAKE2b-256 checksum How to use checksums |
805c071d4fed752c5c980efb23007c197b2fb5d9258e41bbe6742fcb40756c35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 29, 2026.
Transparency log
