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
code-aide remove [NAMES]

# 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:

  1. 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.

  2. User's local version cache (~/.config/code-aide/versions.json): Written by code-aide update-versions. Provides latest versions, dates, and updated SHA256 checksums.

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
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
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

  1. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
  2. Install dependencies: uv sync
  3. Install pre-commit hooks: uv tool install pre-commit && pre-commit install
  4. 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.

  1. Update the version string in src/code_aide/__init__.py (__version__). pyproject.toml reads it automatically via Hatchling.
  2. Run checks:
    • uv run pytest tests/ -v
    • uv build
  3. Commit the release version bump:
    • git add src/code_aide/__init__.py
    • git commit -m "Bumped version to X.Y.Z"
  4. 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
  5. Tag and push to all remotes (origin/GitHub, gitlab, codeberg):
    • git tag vX.Y.Z
    • git push origin main && git push origin vX.Y.Z
    • git push gitlab main && git push gitlab vX.Y.Z
    • git push codeberg main && git push codeberg vX.Y.Z
  6. 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

Project links

Data verified by PyPI on Jul 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dajobe from gravatar.com dajobe

Credits

Author: Dave Beckett

GitHub Statistics

Data verified by PyPI on Jul 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

code_aide-1.16.1.tar.gz (116.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

code_aide-1.16.1-py3-none-any.whl (49.4 kB view details)

Uploaded Python 3

File details

Details for the file code_aide-1.16.1.tar.gz.

File metadata

  • Download URL: code_aide-1.16.1.tar.gz
  • Upload date:
  • Size: 116.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for code_aide-1.16.1.tar.gz
Algorithm Hash digest
SHA256 9671614176dc965fdbb3d756936d7bd8ae478a20a7f8878b13e13851dc684d7b
MD5 62b843a297af94df9069f76808d9fde6
BLAKE2b-256 5113aa4d7936fcf8d0aa669ba1fa75c258416d505f04e27f20113ee7c275b24b

See more details on using hashes here.

Provenance

The following attestation bundles were made for code_aide-1.16.1.tar.gz:

Publisher: publish.yml on dajobe/code-aide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file code_aide-1.16.1-py3-none-any.whl.

File metadata

  • Download URL: code_aide-1.16.1-py3-none-any.whl
  • Upload date:
  • Size: 49.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for code_aide-1.16.1-py3-none-any.whl
Algorithm Hash digest
SHA256 5d13d07a3cd02dca4c8b7f6ea0d377c262188bbea198086faa4d46fc4895d85c
MD5 bac61670f5df1814b2385f5a6de4fccc
BLAKE2b-256 1d4bcb45241b5550e890982f8594816a1021f39bde13a0aaacc170822fc284a5

See more details on using hashes here.

Provenance

The following attestation bundles were made for code_aide-1.16.1-py3-none-any.whl:

Publisher: publish.yml on dajobe/code-aide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.16.1 This release

2 files

1.16.0

2 files

1.15.7

2 files

1.15.6

2 files

1.15.5

2 files

1.15.4

2 files

1.15.3

2 files

1.15.2

2 files

1.15.1

2 files

1.15.0

2 files

1.14.1

2 files

1.14.0

2 files

1.13.0

2 files

1.12.3

2 files

1.12.2

2 files

1.12.1

2 files

1.12.0

2 files

1.11.5

2 files

1.11.4

2 files

1.11.3

2 files

1.11.2

2 files

1.11.1

2 files

1.11.0

2 files

1.10.1

2 files

1.10.0

2 files

1.8.0

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.0

2 files

1.5.0

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.0

2 files

1.0.3

2 files

1.0.2

2 files

1.0.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page