code-aide 1.19.1__tar.gz → 1.20.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. code_aide-1.20.1/PKG-INFO +291 -0
  2. code_aide-1.20.1/README.md +264 -0
  3. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/__init__.py +1 -1
  4. code_aide-1.20.1/src/code_aide/app_bundle.py +479 -0
  5. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/commands_actions.py +42 -5
  6. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/commands_tools.py +65 -7
  7. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/config.py +33 -6
  8. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/data/tools.json +68 -0
  9. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/detection.py +68 -0
  10. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/install.py +171 -70
  11. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/install_types.py +3 -0
  12. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/operation_handlers.py +68 -4
  13. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/operations.py +81 -44
  14. code_aide-1.20.1/src/code_aide/path_copies.py +88 -0
  15. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/prereqs.py +3 -0
  16. code_aide-1.20.1/src/code_aide/release_assets.py +100 -0
  17. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/status.py +30 -7
  18. code_aide-1.20.1/src/code_aide/tool_groups.py +119 -0
  19. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/versions.py +51 -1
  20. code_aide-1.20.1/tests/test_app_bundle.py +612 -0
  21. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_commands_actions.py +1 -3
  22. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_commands_tools.py +45 -0
  23. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_install.py +46 -0
  24. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_npm_cache.py +5 -2
  25. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_operations.py +2 -2
  26. code_aide-1.20.1/tests/test_path_copies.py +148 -0
  27. code_aide-1.20.1/tests/test_release_assets.py +330 -0
  28. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_status.py +28 -0
  29. code_aide-1.19.1/PKG-INFO +0 -254
  30. code_aide-1.19.1/README.md +0 -227
  31. {code_aide-1.19.1 → code_aide-1.20.1}/.github/workflows/ci.yml +0 -0
  32. {code_aide-1.19.1 → code_aide-1.20.1}/.github/workflows/publish.yml +0 -0
  33. {code_aide-1.19.1 → code_aide-1.20.1}/.gitignore +0 -0
  34. {code_aide-1.19.1 → code_aide-1.20.1}/.gitlab-ci.yml +0 -0
  35. {code_aide-1.19.1 → code_aide-1.20.1}/.pre-commit-config.yaml +0 -0
  36. {code_aide-1.19.1 → code_aide-1.20.1}/AGENTS.md +0 -0
  37. {code_aide-1.19.1 → code_aide-1.20.1}/CLAUDE.md +0 -0
  38. {code_aide-1.19.1 → code_aide-1.20.1}/LICENSE +0 -0
  39. {code_aide-1.19.1 → code_aide-1.20.1}/Makefile +0 -0
  40. {code_aide-1.19.1 → code_aide-1.20.1}/TODO.md +0 -0
  41. {code_aide-1.19.1 → code_aide-1.20.1}/pyproject.toml +0 -0
  42. {code_aide-1.19.1 → code_aide-1.20.1}/script-archive/README.md +0 -0
  43. {code_aide-1.19.1 → code_aide-1.20.1}/script-archive/amp-install.sh +0 -0
  44. {code_aide-1.19.1 → code_aide-1.20.1}/script-archive/antigravity-install.sh +0 -0
  45. {code_aide-1.19.1 → code_aide-1.20.1}/script-archive/claude-install.sh +0 -0
  46. {code_aide-1.19.1 → code_aide-1.20.1}/script-archive/cursor-install.sh +0 -0
  47. {code_aide-1.19.1 → code_aide-1.20.1}/specs/2026-05-03-qwen3.6-code-quality-analysis-original.md +0 -0
  48. {code_aide-1.19.1 → code_aide-1.20.1}/specs/2026-05-03-qwen3.6-code-quality-analysis.md +0 -0
  49. {code_aide-1.19.1 → code_aide-1.20.1}/specs/antigravity-cli-integration.md +0 -0
  50. {code_aide-1.19.1 → code_aide-1.20.1}/specs/auto-migrate-deprecated-installs.md +0 -0
  51. {code_aide-1.19.1 → code_aide-1.20.1}/specs/claude-native-installer-migration.md +0 -0
  52. {code_aide-1.19.1 → code_aide-1.20.1}/specs/missing-coding-llm-cli-tools.md +0 -0
  53. {code_aide-1.19.1 → code_aide-1.20.1}/specs/pre-commit-uv-setup.md +0 -0
  54. {code_aide-1.19.1 → code_aide-1.20.1}/specs/remove-bundled-version-baseline.md +0 -0
  55. {code_aide-1.19.1 → code_aide-1.20.1}/specs/unify-upgrade-eligibility-with-shared-evaluator.md +0 -0
  56. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/__main__.py +0 -0
  57. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/console.py +0 -0
  58. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/constants.py +0 -0
  59. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/detection_types.py +0 -0
  60. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/entry.py +0 -0
  61. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/npm_cache.py +0 -0
  62. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/package_info.py +0 -0
  63. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/package_managers.py +0 -0
  64. {code_aide-1.19.1 → code_aide-1.20.1}/src/code_aide/status_print.py +0 -0
  65. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_config.py +0 -0
  66. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_console.py +0 -0
  67. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_constants.py +0 -0
  68. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_detection.py +0 -0
  69. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_entry.py +0 -0
  70. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_error_paths.py +0 -0
  71. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_install_types.py +0 -0
  72. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_package_info.py +0 -0
  73. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_package_managers.py +0 -0
  74. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_prereqs.py +0 -0
  75. {code_aide-1.19.1 → code_aide-1.20.1}/tests/test_versions.py +0 -0
  76. {code_aide-1.19.1 → code_aide-1.20.1}/uv.lock +0 -0
@@ -0,0 +1,291 @@
1
+ Metadata-Version: 2.5
2
+ Name: code-aide
3
+ Version: 1.20.1
4
+ Summary: Manage AI coding CLI tools (Claude, Antigravity, Copilot, Cursor, Gemini, Amp, Codex)
5
+ Project-URL: Homepage, https://github.com/dajobe/code-aide
6
+ Project-URL: Repository, https://github.com/dajobe/code-aide
7
+ Project-URL: Issues, https://github.com/dajobe/code-aide/issues
8
+ Project-URL: Changelog, https://github.com/dajobe/code-aide/releases
9
+ Author: Dave Beckett
10
+ License-Expression: Apache-2.0
11
+ License-File: LICENSE
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: Apache Software License
16
+ Classifier: Operating System :: MacOS
17
+ Classifier: Operating System :: POSIX :: BSD :: FreeBSD
18
+ Classifier: Operating System :: POSIX :: Linux
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Software Development :: Build Tools
24
+ Classifier: Topic :: System :: Installation/Setup
25
+ Requires-Python: >=3.11
26
+ Description-Content-Type: text/markdown
27
+
28
+ # code-aide
29
+
30
+ An aide for your AI coding tools.
31
+
32
+ Manages installation, upgrade, removal, and version tracking of AI coding CLI
33
+ tools: Claude Code, Antigravity, Copilot, Cursor, Gemini, Amp, Codex, OpenCode,
34
+ Kilo, and T3 Code.
35
+
36
+ ## Installation
37
+
38
+ ```bash
39
+ # Run without installing (requires uv)
40
+ uvx code-aide status
41
+
42
+ # Install persistently
43
+ uv tool install code-aide
44
+
45
+ # Or use pipx
46
+ pipx install code-aide
47
+ ```
48
+
49
+ ## Usage
50
+
51
+ ```bash
52
+ # Show compact one-line-per-tool status (default when no command is given)
53
+ code-aide
54
+
55
+ # List available tools and their status
56
+ code-aide list
57
+
58
+ # Show compact one-line-per-tool status
59
+ code-aide status
60
+
61
+ # Show detailed status for installed tools
62
+ code-aide status -l
63
+
64
+ # Install specific tools
65
+ code-aide install claude antigravity
66
+
67
+ # Install all default tools
68
+ code-aide install
69
+
70
+ # Install with automatic prerequisite installation (Node.js, npm)
71
+ code-aide install -p
72
+
73
+ # Verify checksums and show what would be installed, without installing
74
+ code-aide install -n
75
+
76
+ # Upgrade installed tools (no args = only out-of-date tools)
77
+ code-aide upgrade [NAMES]
78
+
79
+ # Remove tools (prompts before removing all managed tools)
80
+ code-aide remove [NAMES]
81
+
82
+ # Preview a removal without changing anything
83
+ code-aide remove -n
84
+
85
+ # Remove all managed tools without prompting
86
+ code-aide remove -y
87
+
88
+ # Remove stale version directories of direct-download tools
89
+ code-aide clean [NAMES]
90
+
91
+ # Check upstream for latest versions (dry-run)
92
+ code-aide update-versions -n
93
+
94
+ # Update version cache
95
+ code-aide update-versions -y
96
+ ```
97
+
98
+ ## Supported Tools
99
+
100
+ | Tool | Command | Install Type | Default |
101
+ |:----------------------------|:-----------|:----------------|:--------|
102
+ | Cursor CLI | `agent` | Direct download | No |
103
+ | Claude CLI (Claude Code) | `claude` | Script | Yes |
104
+ | Antigravity CLI | `agy` | Script | Yes |
105
+ | Gemini CLI | `gemini` | npm | No |
106
+ | OpenCode | `opencode` | npm | No |
107
+ | Kilo CLI | `kilo` | npm | No |
108
+ | Amp (Sourcegraph) | `amp` | Script | No |
109
+ | Codex CLI | `codex` | npm | No |
110
+ | Copilot CLI | `copilot` | npm | No |
111
+ | T3 Code | `t3` | Direct download | No |
112
+ | T3 Code desktop app (macOS) | (app) | App bundle | No |
113
+
114
+ Command aliases are also accepted: `agy` resolves to `antigravity`, `agent` to
115
+ `cursor`, and `t3` to `t3code`.
116
+
117
+ T3 Code installs the `t3` command from the GitHub release tarball, verified
118
+ against the release's `SHA256SUMS`, into `~/.t3/runtime/versions/` (the same
119
+ layout as the upstream installer). There is no `t3` command for Intel Macs; use
120
+ the desktop app there (`brew install --cask t3-code`). code-aide never restarts
121
+ the `t3` background service; after the CLI changes version it reminds you to run
122
+ `t3 service restart`. A `t3` command provided by the desktop app is reported as
123
+ a Homebrew cask install when the `t3-code` cask owns the app.
124
+
125
+ On macOS, `t3code-app` installs the T3 Code desktop app. Each release's signed
126
+ zip is checked against the SHA-512 in the release's `latest-mac.yml`, unpacked
127
+ into `~/.local/opt/t3code-app/v<version>/`, and activated by pointing
128
+ `~/Applications/T3 Code.app` at it. The CLI and the app upgrade together:
129
+ upgrading either one also upgrades the other if it is installed, so both run the
130
+ same release. If the app is running, code-aide offers to quit it before
131
+ switching versions; if it stays running, neither is upgraded. `status` warns
132
+ when the two versions differ.
133
+
134
+ ## How Version Data Works
135
+
136
+ code-aide uses a two-layer version data model:
137
+
138
+ 1. **Bundled tool definitions** (in `data/tools.json`): Install methods, URLs,
139
+ npm packages, version args, and SHA256 checksums. Updated by releasing new
140
+ versions of code-aide.
141
+
142
+ 2. **User's local version cache** (`~/.config/code-aide/versions.json`): Written
143
+ by `code-aide update-versions`. Provides latest versions, dates, updated
144
+ SHA256 checksums, and recorded tarball checksums for direct_download tools.
145
+
146
+ Run `code-aide update-versions` to get the latest version data without waiting
147
+ for a new code-aide release.
148
+
149
+ ## Tool definition schema (`data/tools.json`)
150
+
151
+ Each entry in `tools.json` describes one managed tool. Required fields are
152
+ `name`, `command`, and `install_type`; the others are optional and only
153
+ consulted when the relevant install method or platform applies.
154
+
155
+ | Field | Required | Notes |
156
+ |:---------------------------------|:---------|:---------------------------------------------------------------------------------------------------------------------|
157
+ | `name` | Yes | Display name for status output |
158
+ | `command` | Yes | Binary name (looked up in `PATH`) |
159
+ | `aliases` | No | Alternate names accepted by commands and resolved to the canonical tool key |
160
+ | `install_type` | Yes | One of `npm`, `script`, `direct_download`, `pkg`, `app_bundle` |
161
+ | `version_args` | No | List of arguments passed to the binary to print its version (default: `["--version"]`) |
162
+ | `version_url` | No | URL queried by `update-versions` to discover the latest upstream version |
163
+ | `version_manifest_url_template` | No | JSON manifest URL template with `{platform}`; reads its `version` field |
164
+ | `version_extract_pattern` | No | Regex applied to the install script to extract the version before generic heuristics |
165
+ | `github_release_repo` | No | `owner/repo` whose latest (non-prerelease) GitHub release supplies the version; replaces the install script check |
166
+ | `latest_version` | Cache | Last known upstream version (filled by `update-versions`) |
167
+ | `latest_date` | Cache | Release date for `latest_version` |
168
+ | `prerequisites` | No | List of required external commands (e.g. `["npm"]`) |
169
+ | `min_node_version` | No | Minimum major Node.js version required |
170
+ | `npm_package` | npm | npm package name (e.g. `@anthropic-ai/claude-code`) |
171
+ | `install_url` | script | URL of the install script that will be downloaded and piped to `bash` |
172
+ | `install_sha256` | script | SHA-256 of the install script body — required for verified installs |
173
+ | `download_sha256` | Cache | SHA-256 of the downloaded tarball for direct_download tools; recorded by `update-versions`, verified on install |
174
+ | `install_script_path_prepend` | script | Extra directories prepended to `PATH` when the install script runs (e.g. `["~/.local/bin"]`) |
175
+ | `download_url_template` | direct | URL template with `{version}`, `{os}`, `{arch}` placeholders |
176
+ | `install_dir` | direct | Directory to extract into; supports `{version}` |
177
+ | `bin_dir` | direct | Directory where symlinks for `command` are created (e.g. `~/.local/bin`) |
178
+ | `symlinks` | direct | Map of `link_name` → relative path inside `install_dir` to symlink into `bin_dir` |
179
+ | `checksums_url_template` | direct | Publisher `SHA256SUMS` URL template; verified on install in place of `download_sha256` |
180
+ | `unsupported_platforms` | direct | Map of `<os>-<arch>` to an explanation; install refuses those platforms |
181
+ | `install_complete_marker` | direct | File written into the version directory, holding the version, after extraction; an existing match skips the download |
182
+ | `launcher_record_file` | direct | File that symlink paths are appended to, so the tool's own pruning keeps the linked version |
183
+ | `brew_cask` | No | Homebrew cask that ships a desktop app providing `command`; used for detection and status hints |
184
+ | `desktop_cli_shim` | No | Path of the desktop app's CLI shim; a command resolving to it is detected as the app (or `brew_cask`) |
185
+ | `desktop_cli_hint` | No | Status hint shown when `brew_cask` is installed but `command` is not |
186
+ | `freebsd_port` | FreeBSD | FreeBSD ports/pkg name (used when running on FreeBSD) |
187
+ | `freebsd_pkg_repo` | FreeBSD | Optional non-default pkg repository name (passed via `pkg install -r <repo>`) |
188
+ | `next_steps` | No | Free-form text printed after a successful install |
189
+ | `docs_url` | No | Documentation URL printed after install |
190
+ | `platforms` | No | `platform.system().lower()` values (e.g. `["darwin"]`); the tool is hidden elsewhere |
191
+ | `upgrade_with` | No | Tools upgraded alongside this one, held back if it is not upgraded |
192
+ | `self_pruning_versions` | No | The tool prunes its own version directories; `clean` leaves them alone |
193
+ | `service_files` | No | Background service files; when one exists, `service_restart_hint` is shown after an upgrade |
194
+ | `service_restart_hint` | No | Message shown when a background service keeps running the previous version |
195
+ | `app_link` | app | Symlink that activates the installed app version (e.g. `~/Applications/T3 Code.app`) |
196
+ | `app_bundle_name` | app | Bundle name inside each version directory and in the zip |
197
+ | `bundle_id` | app | Bundle identifier, used to ask the running app to quit |
198
+ | `running_process_name` | app | Process name checked before switching or removing a version |
199
+ | `checksum_manifest_url_template` | app | electron-builder `latest-mac.yml` URL template holding each zip's SHA-512 |
200
+ | `self_updates` | No | Tool updates itself when run; excludes it from managed upgrade actions |
201
+
202
+ ## Features
203
+
204
+ - Zero external dependencies (Python stdlib only)
205
+ - SHA256 verification for script-based installations
206
+ - Automatic prerequisite detection and installation (Node.js, npm)
207
+ - Detects install method (Homebrew, npm, system package, script, direct
208
+ download)
209
+ - PATH configuration validation and warnings
210
+ - Supports Linux and macOS
211
+
212
+ ## Configuration
213
+
214
+ - Tool definitions are bundled at `src/code_aide/data/tools.json`.
215
+ - The version cache lives at `~/.config/code-aide/versions.json` by default; set
216
+ `XDG_CONFIG_HOME` to relocate the `code-aide` config directory.
217
+ - Color output honors `NO_COLOR`, `FORCE_COLOR`, `CLICOLOR_FORCE`, `CLICOLOR=0`,
218
+ and `TERM=dumb`, in that priority order; color is disabled when stdout is not
219
+ a terminal.
220
+
221
+ ## Requirements
222
+
223
+ - Python 3.11+
224
+ - No external Python dependencies
225
+
226
+ ## Development
227
+
228
+ 1. Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
229
+ 2. Install dependencies: `uv sync`
230
+ 3. Install pre-commit hooks: `uv tool install pre-commit && pre-commit install`
231
+ 4. Run tests: `uv run pytest tests/ -v`
232
+
233
+ ```bash
234
+ # Run from development checkout
235
+ uv run python -m code_aide status
236
+ uv run python -m code_aide install copilot
237
+
238
+ # Run a specific test
239
+ uv run pytest tests/test_install.py::TestDetectOsArch -v
240
+ ```
241
+
242
+ ## Release
243
+
244
+ `publish.yml` publishes to PyPI when a Git tag matching `v*` is pushed.
245
+
246
+ 1. Update the version string in `src/code_aide/__init__.py` (`__version__`).
247
+ `pyproject.toml` reads it automatically via Hatchling.
248
+ 2. Run checks:
249
+ - `uv run pytest tests/ -v`
250
+ - `uv build`
251
+ 3. Commit the release version bump:
252
+ - `git add src/code_aide/__init__.py`
253
+ - `git commit -m "Bumped version to X.Y.Z"`
254
+ 4. Write useful commit messages before tagging:
255
+ - Start subject lines with an action verb in past tense (`Added`, `Changed`,
256
+ `Fixed`, `Removed`).
257
+ - Keep subjects user-facing so auto-generated release notes are meaningful.
258
+ - Group related changes into focused commits instead of one broad commit.
259
+ - Example: `Fixed timeout handling in status command`
260
+ 5. Tag and push to all remotes (origin/GitHub, gitlab, codeberg):
261
+ - `git tag vX.Y.Z`
262
+ - `git push origin main && git push origin vX.Y.Z`
263
+ - `git push gitlab main && git push gitlab vX.Y.Z`
264
+ - `git push codeberg main && git push codeberg vX.Y.Z`
265
+ 6. Confirm GitHub Actions:
266
+ - CI should pass.
267
+ - Publish workflow should upload to PyPI and create GitHub Release notes.
268
+ - Release notes should include generated notes plus a commit summary from the
269
+ previous tag to the current tag.
270
+
271
+ ## License
272
+
273
+ Apache-2.0
274
+
275
+ ## npm download cache lifetime
276
+
277
+ Standalone install, upgrade, removal (including migration), and installation
278
+ scripts use private download caches under
279
+ `~/.cache/code-aide/npm-operations/operation-*`. Each invocation gets its own
280
+ directory on the home filesystem instead of the temporary filesystem. npm
281
+ authentication, user configuration and install prefixes remain in effect; only
282
+ the download-cache setting is overridden in the child environment.
283
+
284
+ Downloads and npm logs in that directory are removed after success, failure,
285
+ timeouts supported by the command runner, and normal Python interruption.
286
+ Captured command errors are still reported. Existing user caches are preserved.
287
+ Dry runs create no operation cache. Concurrent operations never clean another
288
+ operation's cache. A hard kill or machine crash can leave an operation
289
+ directory; inspect it and establish that its operation has stopped before
290
+ explicitly removing it. There is no automatic age-based cleanup of these
291
+ directories.
@@ -0,0 +1,264 @@
1
+ # code-aide
2
+
3
+ An aide for your AI coding tools.
4
+
5
+ Manages installation, upgrade, removal, and version tracking of AI coding CLI
6
+ tools: Claude Code, Antigravity, Copilot, Cursor, Gemini, Amp, Codex, OpenCode,
7
+ Kilo, and T3 Code.
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ # Run without installing (requires uv)
13
+ uvx code-aide status
14
+
15
+ # Install persistently
16
+ uv tool install code-aide
17
+
18
+ # Or use pipx
19
+ pipx install code-aide
20
+ ```
21
+
22
+ ## Usage
23
+
24
+ ```bash
25
+ # Show compact one-line-per-tool status (default when no command is given)
26
+ code-aide
27
+
28
+ # List available tools and their status
29
+ code-aide list
30
+
31
+ # Show compact one-line-per-tool status
32
+ code-aide status
33
+
34
+ # Show detailed status for installed tools
35
+ code-aide status -l
36
+
37
+ # Install specific tools
38
+ code-aide install claude antigravity
39
+
40
+ # Install all default tools
41
+ code-aide install
42
+
43
+ # Install with automatic prerequisite installation (Node.js, npm)
44
+ code-aide install -p
45
+
46
+ # Verify checksums and show what would be installed, without installing
47
+ code-aide install -n
48
+
49
+ # Upgrade installed tools (no args = only out-of-date tools)
50
+ code-aide upgrade [NAMES]
51
+
52
+ # Remove tools (prompts before removing all managed tools)
53
+ code-aide remove [NAMES]
54
+
55
+ # Preview a removal without changing anything
56
+ code-aide remove -n
57
+
58
+ # Remove all managed tools without prompting
59
+ code-aide remove -y
60
+
61
+ # Remove stale version directories of direct-download tools
62
+ code-aide clean [NAMES]
63
+
64
+ # Check upstream for latest versions (dry-run)
65
+ code-aide update-versions -n
66
+
67
+ # Update version cache
68
+ code-aide update-versions -y
69
+ ```
70
+
71
+ ## Supported Tools
72
+
73
+ | Tool | Command | Install Type | Default |
74
+ |:----------------------------|:-----------|:----------------|:--------|
75
+ | Cursor CLI | `agent` | Direct download | No |
76
+ | Claude CLI (Claude Code) | `claude` | Script | Yes |
77
+ | Antigravity CLI | `agy` | Script | Yes |
78
+ | Gemini CLI | `gemini` | npm | No |
79
+ | OpenCode | `opencode` | npm | No |
80
+ | Kilo CLI | `kilo` | npm | No |
81
+ | Amp (Sourcegraph) | `amp` | Script | No |
82
+ | Codex CLI | `codex` | npm | No |
83
+ | Copilot CLI | `copilot` | npm | No |
84
+ | T3 Code | `t3` | Direct download | No |
85
+ | T3 Code desktop app (macOS) | (app) | App bundle | No |
86
+
87
+ Command aliases are also accepted: `agy` resolves to `antigravity`, `agent` to
88
+ `cursor`, and `t3` to `t3code`.
89
+
90
+ T3 Code installs the `t3` command from the GitHub release tarball, verified
91
+ against the release's `SHA256SUMS`, into `~/.t3/runtime/versions/` (the same
92
+ layout as the upstream installer). There is no `t3` command for Intel Macs; use
93
+ the desktop app there (`brew install --cask t3-code`). code-aide never restarts
94
+ the `t3` background service; after the CLI changes version it reminds you to run
95
+ `t3 service restart`. A `t3` command provided by the desktop app is reported as
96
+ a Homebrew cask install when the `t3-code` cask owns the app.
97
+
98
+ On macOS, `t3code-app` installs the T3 Code desktop app. Each release's signed
99
+ zip is checked against the SHA-512 in the release's `latest-mac.yml`, unpacked
100
+ into `~/.local/opt/t3code-app/v<version>/`, and activated by pointing
101
+ `~/Applications/T3 Code.app` at it. The CLI and the app upgrade together:
102
+ upgrading either one also upgrades the other if it is installed, so both run the
103
+ same release. If the app is running, code-aide offers to quit it before
104
+ switching versions; if it stays running, neither is upgraded. `status` warns
105
+ when the two versions differ.
106
+
107
+ ## How Version Data Works
108
+
109
+ code-aide uses a two-layer version data model:
110
+
111
+ 1. **Bundled tool definitions** (in `data/tools.json`): Install methods, URLs,
112
+ npm packages, version args, and SHA256 checksums. Updated by releasing new
113
+ versions of code-aide.
114
+
115
+ 2. **User's local version cache** (`~/.config/code-aide/versions.json`): Written
116
+ by `code-aide update-versions`. Provides latest versions, dates, updated
117
+ SHA256 checksums, and recorded tarball checksums for direct_download tools.
118
+
119
+ Run `code-aide update-versions` to get the latest version data without waiting
120
+ for a new code-aide release.
121
+
122
+ ## Tool definition schema (`data/tools.json`)
123
+
124
+ Each entry in `tools.json` describes one managed tool. Required fields are
125
+ `name`, `command`, and `install_type`; the others are optional and only
126
+ consulted when the relevant install method or platform applies.
127
+
128
+ | Field | Required | Notes |
129
+ |:---------------------------------|:---------|:---------------------------------------------------------------------------------------------------------------------|
130
+ | `name` | Yes | Display name for status output |
131
+ | `command` | Yes | Binary name (looked up in `PATH`) |
132
+ | `aliases` | No | Alternate names accepted by commands and resolved to the canonical tool key |
133
+ | `install_type` | Yes | One of `npm`, `script`, `direct_download`, `pkg`, `app_bundle` |
134
+ | `version_args` | No | List of arguments passed to the binary to print its version (default: `["--version"]`) |
135
+ | `version_url` | No | URL queried by `update-versions` to discover the latest upstream version |
136
+ | `version_manifest_url_template` | No | JSON manifest URL template with `{platform}`; reads its `version` field |
137
+ | `version_extract_pattern` | No | Regex applied to the install script to extract the version before generic heuristics |
138
+ | `github_release_repo` | No | `owner/repo` whose latest (non-prerelease) GitHub release supplies the version; replaces the install script check |
139
+ | `latest_version` | Cache | Last known upstream version (filled by `update-versions`) |
140
+ | `latest_date` | Cache | Release date for `latest_version` |
141
+ | `prerequisites` | No | List of required external commands (e.g. `["npm"]`) |
142
+ | `min_node_version` | No | Minimum major Node.js version required |
143
+ | `npm_package` | npm | npm package name (e.g. `@anthropic-ai/claude-code`) |
144
+ | `install_url` | script | URL of the install script that will be downloaded and piped to `bash` |
145
+ | `install_sha256` | script | SHA-256 of the install script body — required for verified installs |
146
+ | `download_sha256` | Cache | SHA-256 of the downloaded tarball for direct_download tools; recorded by `update-versions`, verified on install |
147
+ | `install_script_path_prepend` | script | Extra directories prepended to `PATH` when the install script runs (e.g. `["~/.local/bin"]`) |
148
+ | `download_url_template` | direct | URL template with `{version}`, `{os}`, `{arch}` placeholders |
149
+ | `install_dir` | direct | Directory to extract into; supports `{version}` |
150
+ | `bin_dir` | direct | Directory where symlinks for `command` are created (e.g. `~/.local/bin`) |
151
+ | `symlinks` | direct | Map of `link_name` → relative path inside `install_dir` to symlink into `bin_dir` |
152
+ | `checksums_url_template` | direct | Publisher `SHA256SUMS` URL template; verified on install in place of `download_sha256` |
153
+ | `unsupported_platforms` | direct | Map of `<os>-<arch>` to an explanation; install refuses those platforms |
154
+ | `install_complete_marker` | direct | File written into the version directory, holding the version, after extraction; an existing match skips the download |
155
+ | `launcher_record_file` | direct | File that symlink paths are appended to, so the tool's own pruning keeps the linked version |
156
+ | `brew_cask` | No | Homebrew cask that ships a desktop app providing `command`; used for detection and status hints |
157
+ | `desktop_cli_shim` | No | Path of the desktop app's CLI shim; a command resolving to it is detected as the app (or `brew_cask`) |
158
+ | `desktop_cli_hint` | No | Status hint shown when `brew_cask` is installed but `command` is not |
159
+ | `freebsd_port` | FreeBSD | FreeBSD ports/pkg name (used when running on FreeBSD) |
160
+ | `freebsd_pkg_repo` | FreeBSD | Optional non-default pkg repository name (passed via `pkg install -r <repo>`) |
161
+ | `next_steps` | No | Free-form text printed after a successful install |
162
+ | `docs_url` | No | Documentation URL printed after install |
163
+ | `platforms` | No | `platform.system().lower()` values (e.g. `["darwin"]`); the tool is hidden elsewhere |
164
+ | `upgrade_with` | No | Tools upgraded alongside this one, held back if it is not upgraded |
165
+ | `self_pruning_versions` | No | The tool prunes its own version directories; `clean` leaves them alone |
166
+ | `service_files` | No | Background service files; when one exists, `service_restart_hint` is shown after an upgrade |
167
+ | `service_restart_hint` | No | Message shown when a background service keeps running the previous version |
168
+ | `app_link` | app | Symlink that activates the installed app version (e.g. `~/Applications/T3 Code.app`) |
169
+ | `app_bundle_name` | app | Bundle name inside each version directory and in the zip |
170
+ | `bundle_id` | app | Bundle identifier, used to ask the running app to quit |
171
+ | `running_process_name` | app | Process name checked before switching or removing a version |
172
+ | `checksum_manifest_url_template` | app | electron-builder `latest-mac.yml` URL template holding each zip's SHA-512 |
173
+ | `self_updates` | No | Tool updates itself when run; excludes it from managed upgrade actions |
174
+
175
+ ## Features
176
+
177
+ - Zero external dependencies (Python stdlib only)
178
+ - SHA256 verification for script-based installations
179
+ - Automatic prerequisite detection and installation (Node.js, npm)
180
+ - Detects install method (Homebrew, npm, system package, script, direct
181
+ download)
182
+ - PATH configuration validation and warnings
183
+ - Supports Linux and macOS
184
+
185
+ ## Configuration
186
+
187
+ - Tool definitions are bundled at `src/code_aide/data/tools.json`.
188
+ - The version cache lives at `~/.config/code-aide/versions.json` by default; set
189
+ `XDG_CONFIG_HOME` to relocate the `code-aide` config directory.
190
+ - Color output honors `NO_COLOR`, `FORCE_COLOR`, `CLICOLOR_FORCE`, `CLICOLOR=0`,
191
+ and `TERM=dumb`, in that priority order; color is disabled when stdout is not
192
+ a terminal.
193
+
194
+ ## Requirements
195
+
196
+ - Python 3.11+
197
+ - No external Python dependencies
198
+
199
+ ## Development
200
+
201
+ 1. Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
202
+ 2. Install dependencies: `uv sync`
203
+ 3. Install pre-commit hooks: `uv tool install pre-commit && pre-commit install`
204
+ 4. Run tests: `uv run pytest tests/ -v`
205
+
206
+ ```bash
207
+ # Run from development checkout
208
+ uv run python -m code_aide status
209
+ uv run python -m code_aide install copilot
210
+
211
+ # Run a specific test
212
+ uv run pytest tests/test_install.py::TestDetectOsArch -v
213
+ ```
214
+
215
+ ## Release
216
+
217
+ `publish.yml` publishes to PyPI when a Git tag matching `v*` is pushed.
218
+
219
+ 1. Update the version string in `src/code_aide/__init__.py` (`__version__`).
220
+ `pyproject.toml` reads it automatically via Hatchling.
221
+ 2. Run checks:
222
+ - `uv run pytest tests/ -v`
223
+ - `uv build`
224
+ 3. Commit the release version bump:
225
+ - `git add src/code_aide/__init__.py`
226
+ - `git commit -m "Bumped version to X.Y.Z"`
227
+ 4. Write useful commit messages before tagging:
228
+ - Start subject lines with an action verb in past tense (`Added`, `Changed`,
229
+ `Fixed`, `Removed`).
230
+ - Keep subjects user-facing so auto-generated release notes are meaningful.
231
+ - Group related changes into focused commits instead of one broad commit.
232
+ - Example: `Fixed timeout handling in status command`
233
+ 5. Tag and push to all remotes (origin/GitHub, gitlab, codeberg):
234
+ - `git tag vX.Y.Z`
235
+ - `git push origin main && git push origin vX.Y.Z`
236
+ - `git push gitlab main && git push gitlab vX.Y.Z`
237
+ - `git push codeberg main && git push codeberg vX.Y.Z`
238
+ 6. Confirm GitHub Actions:
239
+ - CI should pass.
240
+ - Publish workflow should upload to PyPI and create GitHub Release notes.
241
+ - Release notes should include generated notes plus a commit summary from the
242
+ previous tag to the current tag.
243
+
244
+ ## License
245
+
246
+ Apache-2.0
247
+
248
+ ## npm download cache lifetime
249
+
250
+ Standalone install, upgrade, removal (including migration), and installation
251
+ scripts use private download caches under
252
+ `~/.cache/code-aide/npm-operations/operation-*`. Each invocation gets its own
253
+ directory on the home filesystem instead of the temporary filesystem. npm
254
+ authentication, user configuration and install prefixes remain in effect; only
255
+ the download-cache setting is overridden in the child environment.
256
+
257
+ Downloads and npm logs in that directory are removed after success, failure,
258
+ timeouts supported by the command runner, and normal Python interruption.
259
+ Captured command errors are still reported. Existing user caches are preserved.
260
+ Dry runs create no operation cache. Concurrent operations never clean another
261
+ operation's cache. A hard kill or machine crash can leave an operation
262
+ directory; inspect it and establish that its operation has stopped before
263
+ explicitly removing it. There is no automatic age-based cleanup of these
264
+ directories.
@@ -1,3 +1,3 @@
1
1
  """code-aide - Manage AI coding CLI tools."""
2
2
 
3
- __version__ = "1.19.1"
3
+ __version__ = "1.20.1"