Update

Update NanoClawbster

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 .nanoclawbster && 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 >> 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 CURRENTVERSION equals NEWVERSION: 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 

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 `) and stop.

5. Apply

Run the update:

npx tsx scripts/update-core.ts --json 

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//modify/.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   

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 

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/nanoclawbster.git. If the user forked from a different URL, they should set the remote manually: git remote add upstream .

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 .nanoclawbster/backup/. Run:

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sskarz
• Source: sskarz/nanoclawbster
• License: MIT
• Homepage: https://nanoclaw.dev

Install and usage instructions live in the source repository linked above.