NanoClaw Upstream

Setup

Enable upstream tracking

Run once during or after initial setup:

npx tsx setup/index.ts --step upstream --enable

This does three things atomically:

1. Adds a nanoclaw git remote pointing to codeberg.org/NanoClaw/NanoClaw.git
2. Runs git fetch nanoclaw --no-tags (read-only, no tag pollution)
3. Writes NANOCLAW_UPSTREAM_ENABLED=true to your .env

Check status

npx tsx setup/index.ts --step upstream --status

Disable

npx tsx setup/index.ts --step upstream --disable

Sets NANOCLAW_UPSTREAM_ENABLED=false in .env. The remote stays configured — re-enable any time without re-fetching history.

Not the same as skills-memory bootstrap

Upstream tracking and preloaded skills memory solve different problems. The upstream toggle helps maintainers follow NanoClaw evolution. The skills-memory bootstrap helps operators get through install with fewer setup-time LLM calls by importing precomputed vectors into the database jail.

Agent tool: check_upstream_updates

Once upstream is enabled, the agent has a check_upstream_updates MCP tool available in every session. Ask from chat:

The tool returns one of three results:

The tool runs against the host project directory (/workspace/project) from inside the agent jail — it does not need network access and never modifies any files.

Automatic fetch (optional cron)

The scripts/fetch-upstream.ts script is designed for cron. It fetches the remote, prints a divergence summary, and exits. Nothing is modified on the working tree.

Typical weekly cron (run as the agent user):

# crontab -e (as clawdie user)
0 3 * * 1  cd /home/clawdie/clawdie-ai && npx tsx scripts/fetch-upstream.ts >> logs/upstream.log 2>&1

Sample output:

[13.03.2026, 03:00:01] Fetching nanoclaw/main...
! 3 upstream commit(s) available:
a4f2c11 feat: add add-image-vision skill
9e3b881 fix: channel registry disconnect edge case
1d0a9c4 chore: bump @modelcontextprotocol/sdk to 1.9.0
  (7 local commit(s) ahead of upstream)

Set NANOCLAW_UPSTREAM_ENABLED=false in .env to skip the fetch silently — useful if you need to temporarily disable without removing the cron entry.

Applying upstream changes

Upstream commits are never applied automatically. The standard workflow after reviewing what's available:

# Inspect a commit before touching your tree
git show a4f2c11

# Apply one commit
git cherry-pick a4f2c11

# Apply a range of commits
git cherry-pick 9e3b881^..a4f2c11

# Just read for ideas — the FreeBSD port often diverges intentionally
git diff HEAD...nanoclaw/main -- src/channels/registry.ts

Option A vs Option B

Two architectures for upstream tracking. Option A is implemented and running. Option B is documented in Phase 7 of the refactor plan — deferred until Option A proves insufficient.

Switching from Option A to Option B: update NANOCLAW_REMOTE_URL in setup/upstream.ts to point to your Gitea instance, re-run --step upstream --enable. The NANOCLAW_UPSTREAM_ENABLED flag and all agent tools remain the same.

How it works

The upstream setup step lives in setup/upstream.ts and registers in the standard setup step registry in setup/index.ts. It uses the same emitStatus / logger pattern as every other setup step.

The check_upstream_updates MCP tool is registered directly in jail/agent-runner/src/ipc-mcp-stdio.ts — the same server used for task scheduling and messaging. It calls git log HEAD..nanoclaw/main --oneline --no-merges against /workspace/project (the host repo mounted read-only into the jail) and returns the result as text.

The cron script at scripts/fetch-upstream.ts runs on the host (not inside a jail) and is intentionally minimal — it has no dependencies beyond Node.js and git.