Update NanoClaw

Pull upstream changes and merge them with the user's installation, preserving skills and customizations. Scripts live in

.claude/skills/update/scripts/

.

Principle: Handle everything automatically. Only pause for user confirmation before applying changes, or when merge conflicts need human judgment.

UX Note: Use

AskUserQuestion

for all user-facing questions.

1. Pre-flight

Check that the skills system is initialized:

test -d .nanoclaw && echo "INITIALIZED" || echo "NOT_INITIALIZED"

If NOT_INITIALIZED: Run

initSkillsSystem()

first:

npx tsx -e "import { initNanoclawDir } from './skills-engine/init.js'; initNanoclawDir();"

Check for uncommitted git changes:

git status --porcelain

If there are uncommitted changes: Warn the user: "You have uncommitted changes. It's recommended to commit or stash them before updating. Continue anyway?" Use

AskUserQuestion

with options: "Continue anyway", "Abort (I'll commit first)". If they abort, stop here.

2. Fetch upstream

Run the fetch script:

./.claude/skills/update/scripts/fetch-upstream.sh

Parse the structured status block between

<<< STATUS

and

STATUS >>>

markers. Extract:

• TEMP_DIR

  — path to extracted upstream files

• REMOTE

  — which git remote was used

• CURRENT_VERSION

  — version from local

  package.json

• NEW_VERSION

  — version from upstream

  package.json

• STATUS

  — "success" or "error"

If STATUS=error: Show the error output and stop.

If CURRENT_VERSION equals NEW_VERSION: Tell the user they're already up to date. Ask if they want to force the update anyway (there may be non-version-bumped changes). If no, clean up the temp dir and stop.

3. Preview

Run the preview to show what will change:

npx tsx scripts/update-core.ts --json --preview-only <TEMP_DIR>

This outputs JSON with:

currentVersion

,

newVersion

,

filesChanged

,

filesDeleted

,

conflictRisk

,

customPatchesAtRisk

.

Present to the user:

• "Updating from {currentVersion} to {newVersion}"
• "{N} files will be changed" — list them if <= 20, otherwise summarize
• If

  conflictRisk

  is non-empty: "These files have skill modifications and may conflict: {list}"
• If

  customPatchesAtRisk

  is non-empty: "These custom patches may need re-application: {list}"
• If

  filesDeleted

  is non-empty: "{N} files will be removed"

4. Confirm

Use

AskUserQuestion

: "Apply this update?" with options:

• "Yes, apply update"
• "No, cancel"

If cancelled, clean up the temp dir (

rm -rf <TEMP_DIR>

) and stop.

5. Apply

Run the update:

npx tsx scripts/update-core.ts --json <TEMP_DIR>

Parse the JSON output. The result has:

success

,

previousVersion

,

newVersion

,

mergeConflicts

,

backupPending

,

customPatchFailures

,

skillReapplyResults

,

error

.

If success=true with no issues: Continue to step 7.

If customPatchFailures exist: Warn the user which custom patches failed to re-apply. These may need manual attention after the update.

If skillReapplyResults has false entries: Warn the user which skill tests failed after re-application.

6. Handle conflicts

If backupPending=true: There are unresolved merge conflicts.

For each file in

mergeConflicts

:

1. Read the file — it contains conflict markers (

   <<<<<<<

   ,

   =======

   ,

   >>>>>>>

   )
2. Check if there's an intent file for this path in any applied skill (e.g.,

   .claude/skills/<skill>/modify/<path>.intent.md

   )
3. Use the intent file and your understanding of the codebase to resolve the conflict
4. Write the resolved file

After resolving all conflicts:

npx tsx scripts/post-update.ts

This clears the backup, confirming the resolution.

If you cannot confidently resolve a conflict: Show the user the conflicting sections and ask them to choose or provide guidance.

7. Run migrations

Run migrations between the old and new versions:

npx tsx scripts/run-migrations.ts <CURRENT_VERSION> <NEW_VERSION> <TEMP_DIR>

Parse the JSON output. It contains:

migrationsRun

(count),

results

(array of

{version, success, error?}

).

If any migration fails: Show the error to the user. The update itself is already applied — the migration failure needs manual attention.

If no migrations found: This is normal (most updates won't have migrations). Continue silently.

8. Verify

Run build and tests:

npm run build && npm test

If build fails: Show the error. Common causes:

• Type errors from merged files — read the error, fix the file, retry
• Missing dependencies — run

  npm install

  first, retry

If tests fail: Show which tests failed. Try to diagnose and fix. If you can't fix automatically, report to the user.

If both pass: Report success.

9. Cleanup

Remove the temp directory:

rm -rf <TEMP_DIR>

Report final status:

• "Updated from {previousVersion} to {newVersion}"
• Number of files changed
• Any warnings (failed custom patches, failed skill tests, migration issues)
• Build and test status

Troubleshooting

No upstream remote: The fetch script auto-adds

upstream

pointing to

https://github.com/qwibitai/nanoclaw.git

. If the user forked from a different URL, they should set the remote manually:

git remote add upstream <url>

.

Merge conflicts in many files: Consider whether the user has heavily customized core files. Suggest using the skills system for modifications instead of direct edits, as skills survive updates better.

Build fails after update: Check if

package.json

dependencies changed. Run

npm install

to pick up new dependencies.

Rollback: If something goes wrong after applying but before cleanup, the backup is still in

.nanoclaw/backup/

. Run:

npx tsx -e "import { restoreBackup, clearBackup } from './skills-engine/backup.js'; restoreBackup(); clearBackup();"