Upgrading

Recommended: /ari-update Command

The easiest way to upgrade ARI is with the /ari-update slash command in your Claude Code workspace. It handles the full upgrade process:

1. Adds the upstream remote if missing
2. Fetches the latest changes
3. Shows you what's new before merging
4. Merges after your confirmation
5. Runs post-update tasks: dependency installs, new SQL migrations, module registry regeneration, and env var changes

See Commands for more details.

Manual Upgrade

If you prefer to upgrade manually, follow the steps below.

What Gets Overwritten

When you upgrade from upstream, all files and modules inside modules-core will be overwritten. This directory is managed entirely by the upstream repository and should be treated as read-only. Any local changes you make directly to modules in modules-core will be lost on the next upgrade.

Protecting Your Customizations with modules-custom

If you want to modify a core module or create your own, place it in the modules-custom directory. This directory is ignored by upstream updates and is entirely yours to manage.

To customize an existing core module:

1. Copy the module folder from modules-core into modules-custom.
2. Make your changes in the modules-custom copy.
3. Upgrade freely — your custom version is safe.

Module Loading Priority

If the same module exists in both modules-core and modules-custom, only the version in modules-custom will be loaded. This allows you to override any core module with your own version without needing to delete or modify the original in modules-core.

This means you can:

• Fork a core module and tweak it to fit your workflow.
• Fix a bug in a core module locally while waiting for an upstream patch.
• Experiment with changes to a module without affecting the original.

Manual Upgrade Workflow

1. Commit or back up your work before pulling upstream changes.
2. Pull the latest changes from the upstream repository.
3. Review any conflicts — these should only occur if you edited files outside of modules-custom.
4. Test your modules to make sure everything still works with the updated core.

Summary

Keep your customizations in modules-custom and you can upgrade ARI with confidence.