NanoCo Release Notes

[BREAKING]

A new Slack experience — per-agent provisioned Slack apps, agent spawning from Slack, and UX improvements — is available to classic single-bot Slack installs. Classic Slack keeps working unchanged; this gate asks for a decision, not a forced migration. New installs and non-Slack installs are unaffected. Migration: run /migrate-slack-agents — it detects classic state (exits cleanly otherwise) and either walks the upgrade or records the choice to stay on classic; both outcomes satisfy this requirement.

/add-codex now pins @openai/codex 0.146.0. The previous pin (0.138.0) defaults to GPT-5.4, which OpenAI retires from Codex on 2026-08-31 — codex-provider agents ride the CLI default model, so stock installs stop completing turns at retirement — and it rejects the newer GPT-5.6 models with a 400 asking for a newer Codex CLI. Existing codex installs are not re-pinned by re-running /add-codex (the manifest merge is keyed on package name): edit the @openai/codex entry in container/cli-tools.json to 0.146.0, rebuild the agent image (./container/build.sh), and restart.

[BREAKING]

Agent mailbox access now goes through storage-neutral host and runner registries. The built-in SQLite implementation preserves existing session data and runtime behavior, but custom source may need to replace raw session-database access, await mailbox writes, update moved runner state/heartbeat helpers, drop DeliveryActionHandler's database argument, use booleans for trigger/onWake, and use the closed inbound-kind set. Migration: follow the agent mailbox seam migration guide for the complete detect grep, old→new symbol map, verification, and rollback.

Scheduled-task lifecycle semantics are stricter. Deleting an isolated task cascades its session state, updates refuse already-due runs, recurring selection uses the active series snapshot, and generated task timestamps retain millisecond precision.

[BREAKING]

The container runtime moves behind the session driver seam. Session containers are composed as a validated, admission-checked spec and realized by a selectable driver (src/drivers/; Docker ships built-in and stays the default). Three surfaces break: (1) group folder names align to the runtime label grammar — at most 63 characters of [A-Za-z0-9_-], alphanumeric at both ends — so previously-legal 64-character names, trailing -/_, and unvalidated legacy imports refuse to spawn; (2) container names and invocation change from nanoclaw-v2-<folder>-<timestamp> to key-derived ncl-… names (the old human-readable name survives as the nanoclaw-container-name label) and from docker run to create + start --attach — name-based tooling, Docker-command allowlists, wrappers, and audit rules should match by label instead (docker ps --filter label=nanoclaw-session, or --filter label=nanoclaw-group-folder=<folder>); (3) internal container helpers moved into the driver module — customized installs importing hostGatewayArgs, readonlyMountArgs, stopContainer, ensureContainerRuntimeRunning, cleanupOrphans, or patching buildContainerArgs stop compiling. The use-native-credential-proxy skill is retired: the spec's admission rules refuse credential values in container env on every lane, by design — credentials ride the OneCLI vault, and custom Anthropic endpoints use the ANTHROPIC_BASE_URL + placeholder-token pattern from setup. Migration: run bun scripts/detect-driver-migration.ts — it detects all three surfaces in your install and prints one finding per line with a minimal fix instruction; hand the output to your coding agent. Nothing detected means nothing to do.

Host restarts now adopt running sessions instead of restarting them. A service restart no longer kills in-flight agent work; to apply image or runtime changes to a group, restart it deliberately with ncl groups restart. Pre-seam containers (spawned before this release) cannot be adopted and are removed at first upgraded startup, exactly as the old startup cleanup did.

Container gateway wiring is typed and admission-checked. The gateway's per-session contribution (proxy env, trust anchors, credential-stub mounts) merges into the session spec before validation instead of riding raw docker flags around it, and gateway selection becomes a registry (NANOCLAW_GATEWAY_PROVIDER, default onecli — an install that never sets it behaves as it always has).

Non-root hosts get an explicit container identity. Every non-root host now passes --user <uid>:<gid> and HOME=/home/node (previously uid-1000 hosts relied on the image's node user). On uid-1000 systems whose primary gid is not 1000, files the agent writes into mounted workspaces now carry the host's gid — which is the intended behavior.

CONTAINER_MEMORY_LIMIT is validated at spawn. Invalid values refuse the spawn with a named error instead of surfacing as a raw Docker error; blank and 0 still mean uncapped.

An unknown NANOCLAW_RUNTIME_DRIVER aborts startup (new variable — installs that never set it are unaffected), and drivers that cannot rebuild images in place deny install_packages and --rebuild at request time instead of failing later.

[BREAKING]

The host runtime now requires Node.js 22 or newer. Node 20 is not supported by the upgraded better-sqlite3 release used for current Node runtimes. Migration: run bash setup/install-node.sh, verify node --version reports v22 or newer, then rerun /update-nanoclaw; stay on the previous NanoClaw release if Node cannot yet be upgraded.

New NanoClaw installs now use OneCLI gateway 1.41.0. Existing 1.36.0 gateways remain compatible because NanoClaw does not depend on any 1.41-only behavior. See the OneCLI upgrade guide to upgrade an existing gateway.

[BREAKING]

Central database access is now asynchronous behind DbDriver. SQLite remains the default and existing data/v2.db files are unchanged, but custom source and installed channel/provider extensions must await central reads and writes and adopt the retyped host seams. Migration: follow the central database async migration guide to find affected calls, preserve transaction boundaries, update extensions, verify SQLite behavior, or roll back.

Central DB composition and migrations are backend-ready. A one-slot driver registry keeps backend selection in src/db/compose.ts; pnpm run migrate is the explicit schema-change path, host validation can fail closed without DDL, and a shared conformance suite pins transaction, parameter, ordering, and timestamp behavior. SQLite remains the installed default.

New Contributors

@teran13 made their first contribution in #3230

@brentkearney made their first contribution in #3210

Contributors

Thanks to everyone who landed work in this release:

• ci: let verify-agent-image run on every PR so it can gate by @gavrielc in #3238
• ci: open the agent-image bump PR from a dispatch by @gavrielc in #3240
• verify-agent-image: pin the publisher identity, and check attestations per arch by @gavrielc in #3158
• ci: let a verified signature be the approving review by @gavrielc in #3241
• verify-agent-image: arming auto-merge is not a verdict by @gavrielc in #3243
• fix(poll-loop): stopped loops leaked their active query's follow-up poller by @gavrielc in #3268
• engine: bump OneCLI gateway pin to 1.41.0 by @amit-shafnir in #3277
• Permissions: registerChannelCardInterceptor seam before registration cards (A4) by @gavrielc in #3266
• Agent-to-agent: CreateAgentOptions.suppressCreatedNotify (A3) by @gavrielc in #3265
• Delivery: registerDeliveryBatchPreview hook over each undelivered batch (A2) by @gavrielc in #3264
• Channel registry: hot-start a registered adapter after boot (A1) by @gavrielc in #3263
• channels: Chat SDK bridge agent-mode DM surface — app-context capture, DM-thread normalization, dm-opened hook (A8 + C4) by @gavrielc in #3262
• channels: optional adapter capabilities — status-bearing setTyping, setThreadTitle, setSuggestedPrompts + registry passthroughs by @gavrielc in #3261
• permissions: 'decline_notify' unknown-sender policy — polite decline + one-line owner FYI, no approval card by @gavrielc in #3260
• setup/tooling: skill-apply heading-ordinal strip, headless browser URL surfacing, inherit-script extraction by @gavrielc in #3259
• container: mid-turn streaming is the single delivery door — cross-segment assembly, DB-backed echo suppression, no result-door sends by @gavrielc in #3284
• Preserve structured chat links by @Koshkoshinsk in #3283
• fix: idle container with no heartbeat file is exempt from the absolute-ceiling kill forever by @gavrielc in #3252
• fix(skills): stop removal docs pointing at the retired data/env mirror by @teran13 in #3230
• docs(container): tell the agent where received attachments land by @brentkearney in #3210
• fix(container): bump pnpm and npm past fixable-critical tar CVE by @gabi-simons in #3207
• Add AnyDoc document conversion skill by @amit-shafnir in #3198
• Cross-session context for multi-session agent groups (batching, delivery-resolution, and detached-state prerequisites included) by @gavrielc in #3285
• channels: generic membership-event hook on the Chat SDK bridge by @gavrielc in #3295
• agent-runner: extendTool — additive MCP tool schema and description extension by @gavrielc in #3296
• delivery: post-delivery hook with first-delivery context by @gavrielc in #3294
• router: session-created hook for brand-new engaged sessions by @gavrielc in #3293
• setup: per-channel pre-step and companion-skill declarations for the wizard by @gavrielc in #3297
• channels: bridge inbound-policy registration seam by @gavrielc in #3292
• channels: adapter-declared session-mode context defaults (threads stamp derived) by @gavrielc in #3304
• fix(update): make NanoClaw upgrades transactional by @glifocat in #3195
• cross-session context: extend new-session backfill to group conversations by @gavrielc in #3312
• skills: channel welcome addenda, matched host-side (zero cost when absent) by @gavrielc in #3313
• setup: optional automatic Slack app provisioning behind an opt-in flag by @gavrielc in #3314
• Fix Telegram skill copy list by @Koshkoshinsk in #3316
• ci: add zvi-fried to core team roster by @gabi-simons in #3348
• drivers: a session-runtime driver seam, with Docker as the built-in realization by @gavrielc in #3306
• host: route session lifecycle through the driver seam by @gavrielc in #3307
• groups: refuse to create a group over a folder that already exists undisposed by @gavrielc in #3308
• refactor(db): prepare the central database for portable drivers by @moshe-nanoco in #3332
• refactor(db): add async central database seam by @moshe-nanoco in #3333
• [BREAKING] refactor(db): adopt async central database safely by @moshe-nanoco in #3334
• refactor(db): add backend composition and portable tests by @moshe-nanoco in #3335
• fix setup ping folder compatibility by @amit-shafnir in #3350
• docs(telegram): document approved group connection flow by @amit-shafnir in #3352
• setup: --slack-agents installs the whole Slack agents feature by @Koshkoshinsk in #3357
• fix(setup): fail closed when a stored sign-in cannot be verified by @gavrielc in #3339
• feat(setup): forward optional client metadata on Slack service requests by @gavrielc in #3345
• fix(approvals): record the delivering instance on pending_approvals by @gavrielc in #3340
• fix: support current Node runtimes by @Koshkoshinsk in #3360
• fix: expose decline notification overrides by @Koshkoshinsk in #3361
• feat(cli): accept bounded JSON from stdin by @zvi-fried in #3218
• fix(add-codex): bump @openai/codex pin 0.138.0 → 0.146.0 before GPT-5.4 retires from Codex (2026-08-31) by @chiptoe-svg in #3299
• Log a warning for unrecognized engage_mode instead of silent drop by @wakqasahmed in #3317
• feat: add agent mailbox seam and registry by @zvi-fried in #3349
• fix(setup): manage template agents after install by @amit-shafnir in #3365
• fix(setup): allow choosing a different Slack workspace by @Koshkoshinsk in #3383
• fix(permissions): disclose shared agent-group scope on approval cards by @Koshkoshinsk in #3386
• fix(setup): drop stale Slack experimental/public-URL copy, modal-agnostic app-creation walkthrough by @Koshkoshinsk in #3389
• feat(setup): finish Slack app installs the workspace must approve by @gavrielc in #3399
• setup: the managed Slack experience becomes the default by @gavrielc in #3404
• feat: add /migrate-slack-agents upgrade path for classic Slack installs by @Koshkoshinsk in #3391
• fix(permissions): assert the scope warning via its constant, not a copy of it by @gavrielc in #3407
• docs+setup: announce one-click Slack agents by @gavrielc in #3421
• feat(drivers): ratify the attach surface — a driver describes its exec argv by @gavrielc in #3429
• fix: restore stable CI required check by @zvi-fried in #3430
• [main] fix(providers): accept provider file events by @zvi-fried in #3402
• [main] fix(matrix): use a refresh-safe ESM patch by @zvi-fried in #3403
• [main] ci: test registry-backed skills by @zvi-fried in #3424
• feat(setup): add Dial to the channel picker + wizard/skills (runChannelSkill model) by @OmriBenShoham in #3050
• chore(container): bump claude-code to 2.1.238 and agent SDK to 0.3.238 by @gavrielc in #3439
• fix(add-dial-number): use nc directives by @zvi-fried in #3433
• feat(drivers): validate runtimeTier against driver isolation capabilities; select the tier from group config by @gavrielc in #3442
• fix(upgrade-state): accept a version-matching marker when Git cannot identify the checkout by @gavrielc in #3444
• build: drop better-sqlite3 from onlyBuiltDependencies — use its bundled prebuilds by @gavrielc in #3443
• fix(setup): skip Slack auto-provisioning when a bot is already saved by @Koshkoshinsk in #3390
• fix(telegram-setup): pairing card says 6 digits by @amit-shafnir in #3431
• fix(chat-sdk): polling adapters do not open the webhook server by @amit-shafnir in #3434
• feat(setup): carry the adapter instance through pairing, init-first-agent and the CLI welcome by @amit-shafnir in #3478
• docs(add-telegram): add-another-bot path, instance-aware pairing and wiring by @amit-shafnir in #3479
• feat(setup): the wizard offers "add another Telegram bot" when one is already configured by @Koshkoshinsk in #3480
• chore(release): v2.3.0 by @gavrielc in #3495

Full Changelog: v2.2.0...v2.3.0

Original source

Stamped plugins update in place through ncl groups create --template <ref>. When a group already carries the template's plugin, the same command becomes an in-place update instead of minting a duplicate agent: a dry run prints a plan of every plugin-owned surface (plugin files, skills, MCP servers, persona, context files, tasks), flagging locally customized files whose edits would be lost; --yes applies, --id picks among several stamped groups, --new deliberately stamps another agent. Agent state the plugin does not own (memory, plugin-data/, user-added MCP servers, task pause/resume state, wiring) is never touched. Plugin-stamped MCP servers now carry an ownership marker and refuse direct edits via ncl groups config add-mcp-server / remove-mcp-server or the agent's add_mcp_server tool: update the plugin and restamp instead.

[BREAKING] Agent templates are now Agent Plugins 1.0.0 directories

plugin.json replaces context/instructions.md as the required file; MCP servers move to a spec-shaped mcp.json; persona, extra context, and tasks move under the ai.nanoco.nanoclaw/ extension dir. Templates become portable to other plugin clients, and any conformant third-party plugin stamps as a NanoClaw agent. Migration: re-fetch templates from the registry (the pre-plugin layout fails with a migration error); to convert a local custom template, see docs/templates.md.

Plugin MCP servers may declare a working directory. cwd in mcp.json (fixed forms ./p, ${PLUGIN_ROOT}[/p], ${PLUGIN_DATA}[/p]) now launches the server in that directory instead of being skipped: resolved to an absolute container path at runtime, consumed natively by providers that support it and via a cd-then-exec launch shim on Claude. A stdio server that omits cwd runs from the plugin root (the spec default).

Setup can stamp the first agent from a template. The wizard offers the NanoClaw template library (or local templates/) when creating the first agent; --template-path <ref> or the advanced screen presets the pick. A rerun over a partial install updates the stamped agent in place (dry-run plan + confirm) instead of duplicating it, the pick persists across wizard re-execs and reruns, and a template failure warns and continues instead of aborting setup.

Remote MCP servers can use Streamable HTTP. Register them with ncl groups config add-mcp-server --name <name> --url <url> or the existing admin-approved add_mcp_server tool. Local stdio MCP commands keep their current command / args / env behavior; remote credentials remain OneCLI-managed: URLs with userinfo, fragments, or credential-looking query parameters are rejected. HTTPS is required except for localhost / host.docker.internal.

[BREAKING] Host modules now use one lifecycle registry

Custom modules that import onShutdown() or getShutdownCallbacks() from response-registry.ts must move to the host lifecycle API. Migration: follow the host lifecycle migration guide to detect affected code, update it, verify the cutover, or roll back.

Agent-to-agent messaging no longer loses to Claude Code's built-in SendMessage. That built-in addresses the SDK's own in-session subagents, so an agent that had just run create_agent reached for it by name and got No agent named 'x' is currently addressable — reading as "the group was never provisioned" while mcp__nanoclaw__send_message (the real path) was never called. SendMessage joins AskUserQuestion in SDK_DISALLOWED_TOOLS, so the PreToolUse hook now blocks it and points at the nanoclaw equivalent.

[BREAKING] Existing Claude installs should review the hardened agent image

Local builds remain supported, but the Echo-built image is recommended for patched sandbox components. Migration: follow the hardened-image guide to detect your current image source, switch, verify, or roll back.

Release publication tolerates GitHub API propagation. The Release workflow now retries bounded post-publication read-backs when the new Release is not listed yet or its immutable state is not visible yet. Exact title, body, tag, or SHA mismatches still fail immediately.

The add-tavily-tool skill adds Tavily Search and Extract as keyless remote MCP tools for selected agent groups, bridged through a pinned mcp-remote.

Scheduled tasks now run with their effective scheduled occurrence as the task time, plus a task-only current_time (weekday included, in the agent group's timezone) instead of the creation timestamp.

Accumulated messages stay available as context without spuriously triggering warm-container follow-up turns; group-scoped agents can inspect their wirings and request approved engagement-policy updates; invalid engagement regexes are rejected.

Hosted iMessage setup now provisions the line's user row directly and prints the assigned number to text once; that first message is the opt-in the delivery plane checks, and re-runs reuse the existing row.

Resolved approval cards keep their title and request details, replace buttons with the decision and actor (or a timeout status), and survive host restarts and delayed resolution.

Setup failure assist now offers diagnosis through the provider the operator picked instead of always offering to install Claude.

ensureUserDm gains an opt-in privacy-safe logging mode for security-sensitive flows: user IDs, handles, messaging-group IDs, and raw adapter errors are omitted while non-identifying channel context is kept.

The stale add-gcal-tool, add-gmail-tool, and get-qodo-rules skills were removed.

The recommended hardened agent image is repinned to hardened-2026-08-13.

The package description now says personal AI assistant: NanoClaw is provider-agnostic, not Claude-only.

Docs: skills define a single-responsibility integration rule, and the hardened-image guide states that install_packages covers apt and npm packages only.

New Contributors

@dim0627 made their first contribution in #3187
@zvi-fried made their first contribution in #3211
@stumpjumper made their first contribution in #3216
@manisrinivasan2k1 made their first contribution in #3190

Contributors

Thanks to everyone who landed work in this release:

fix(setup): dispatch failure assist to the picked provider by @glifocat in #3170
fix(release): retry post-publish readback by @glifocat in #3176
Preserve resolved approval card content by @Koshkoshinsk in #3143
fix(imessage): opt in via first message to the assigned line by @glifocat in #3181
Fix engagement consistency and expose self-serve wiring controls by @Koshkoshinsk in #3137
fix(update): surface hardened image migration by @gabi-simons in #3180
versions: repin the agent image to hardened-2026-08-02 by @gavrielc in #3182
fix(agent-runner): give scheduled tasks current run time by @Koshkoshinsk in #3154
fix(agent-runner): disallow built-in SendMessage so agent-to-agent messaging works by @dim0627 in #3187
chore(skills): remove stale qodo and Google MCP skills by @glifocat in #3172
docs(skills): define single-responsibility integration rule by @zvi-fried in #3211
refactor(db): add module migration registry by @zvi-fried in #3212
refactor(host): unify module lifecycle hooks by @zvi-fried in #3214
refactor(channels): register question renderers by @zvi-fried in #3213
feat(permissions): add opt-in privacy-safe DM logs by @zvi-fried in #3222
docs(hardened-image): note that install_packages covers apt and npm only by @stumpjumper in #3216
feat: support remote Streamable HTTP MCP servers by @amit-shafnir in #3092
feat: add Tavily MCP tool skill by @manisrinivasan2k1 in #3190
feat!: agent templates become Agent Plugins 1.0.0 directories by @amit-shafnir in #3220
feat(setup): template setup flow in the wizard and first-agent stamping by @amit-shafnir in #2909
versions: repin the agent image to hardened-2026-08-13 by @gavrielc in #3236
chore(release): v2.2.0 by @glifocat in #3237

Full Changelog: v2.1.54...v2.2.0

Original source

Rollup release covering v2.1.18 through v2.1.54 — everything merged since the v2.1.17 tag.

[BREAKING] iMessage unified into one imessage channel with two backends via /add-imessage: Local (this Mac's chat.db via the Chat SDK) or Hosted (native Photon via spectrum-ts, no Mac relay). Backend chosen at install or via IMESSAGE_BACKEND=local|hosted. The legacy Chat-SDK remote mode (IMESSAGE_SERVER_URL/IMESSAGE_API_KEY) and the separate imessage-cloud channel + /add-imessage-cloud skill are removed. See docs/imessage.md.

[BREAKING] Provider-agnostic memory. All providers now share one OKF v0.1-compatible memory/ tree, while persona lives in instructions.prepend.md; startup, clear, and compact reload memory automatically. Existing groups with legacy memory must run /migrate-memory before use. See memory and provider migration.

New groups can inherit an instance-wide default provider. DEFAULT_AGENT_PROVIDER sets the provider used when a new agent group is created without an explicit provider. Each group's stored provider still overrides it, and existing groups are unchanged.

[BREAKING] Channel install skills are now the single source of truth. The setup wizard installs channels by applying the same /add-<channel> SKILL.md a coding agent would follow — a deterministic engine executes the skill's mechanical steps directly from the document, so wizard and skill cannot drift, and anything the engine cannot do falls back to an agent reading the prose. Migration: the bespoke non-interactive channel installers (setup/add-<channel>.sh, setup/install-<channel>.sh) and per-channel wizard flows (setup/channels/<channel>.ts) are deleted. Anything that invoked them should apply the skill instead: interactively via /add-<channel> or the setup wizard, or programmatically via skill directives.

One guard for privileged actions. Every privileged action crossing the container or channel boundary now passes through guard() before execution: allow, hold, or deny. Approved replays carry the approval row as a grant and re-run checks against current state; forged, consumed, mismatched, or newly unauthorized grants fail closed. Guarded delivery actions can no longer be re-registered without their guard specification.

[BREAKING] whatsapp-formatting and slack-formatting moved from trunk to the channels branch. They now install with their channel, so installations without those channels no longer carry channel-specific formatting instructions in every agent's context. Migration — only if the channel is installed: re-run /add-whatsapp or /add-slack after updating. Do not run an add-skill preemptively; it installs the full adapter.

[BREAKING] Scheduled tasks moved from MCP tools to ncl tasks. Agents and operators now manage tasks with ncl tasks list/get/create/update/cancel/pause/resume/delete/run/append-log; task sessions are isolated from the chat session that created them. Migration: follow the scheduled-task migration guide.

[BREAKING] Task delivery is explicit and uses one door. Every send_message and send_file call requires a named to destination; task-session final output becomes the run summary, while only explicitly addressed tool calls deliver. Migration: rebuild the agent image, restart NanoClaw, update custom instructions that omit to, and clear or compact existing sessions. Failed pre-task scripts now back their recurring series off and auto-pause after eight consecutive failures instead of spinning.

[BREAKING] Chat SDK and channel adapters are pinned to 4.29.0. The bridge and adapter must use the same ChatInstance type, so exact pins replace caret ranges. Core installations without a channel are unaffected. Migration: if a channel is installed, re-run its /add-<channel> skill after updating.

Hardened agent images are available as an opt-in setup path. A digest-pinned, multi-architecture image can be fetched from the NanoClaw registry and retagged to the same local name used by builds; architecture, lockfile, provenance, size, and optional publisher-signature checks fail closed. Local builds remain the default and require no account. See hardened images.

Agent containers now start with safer defaults. New spawns always drop all Linux capabilities, set no-new-privileges, and use Docker's init process; these controls have no per-group override. A PID limit defaults to 2048 and can be changed installation-wide with CONTAINER_PIDS_LIMIT (0 disables it). The Vercel CLI is now opt-in instead of being baked into every image.

Agent containers can have installation-wide resource caps. CONTAINER_CPU_LIMIT and CONTAINER_MEMORY_LIMIT pass --cpus and --memory to Docker for every agent container. Both remain empty by default, so existing installations keep their current behavior.

Per-agent-group timezones. ncl groups config update --timezone <IANA> overrides the install timezone for that group's scheduling, run-log display, and container TZ; "" clears the override. Host-side operator display remains in the install timezone.

Agent templates and reusable skills expanded. Local templates can stamp persona, context, MCP configuration, and skills through ncl groups create --template; templates can also seed scheduled tasks and timezone. /learn distills a reusable skill from an existing workflow, and /add-clidash installs a read-only CLI-derived dashboard.

A clearer, safer ncl control plane. Verbs now declare and validate their arguments, generate deep help, preserve dashed IDs, render human-readable output on the host, and flush large responses before exit. Creating groups and wirings now provisions their required companion rows transactionally, fixing first-spawn failures and silently dropped replies.

Approval and agent-to-agent controls are more expressive. Connected agents can require per-message approval; rejection reasons reach the requester; OneCLI approval cards use the gateway's structured summary; and shared-channel cards retain who approved or rejected an action.

Delivery and provider failures stop disappearing. Missing adapters route messages into retry instead of marking them delivered, agent image builds no longer block the host, and Claude rate-limit telemetry only aborts a turn when the SDK reports a rejection. Billing exhaustion and transient rate limits remain distinct.

Setup and update recovery improved. Setup can parse wrapped Claude OAuth captures, offer Slack Socket Mode, and reap dead peer-service registrations. Re-applying an updated skill rebuilds the container when needed, and a missing session folder is re-provisioned so the documented reset path works.

Security fixes. Inbox attachment writes reject symlink escapes, approved CLI calls preserve the original caller context, command-gate checks no longer fail open, mount allowlists honor readOnly, and stale v1 secret/config mirrors were removed.

Documentation was refreshed across architecture, database schemas, security boundaries, provider configuration, SDK behavior, skills, and registry-branch maintenance. A Korean README is now available.

New Contributors

@arkjun made their first contribution in #2806

@sturdy4days made their first contribution in #2803

@moshe-nanoco made their first contribution in #2793

@cben0ist made their first contribution in #2859

@johnmathews made their first contribution in #2880

@thisdotrob made their first contribution in #2885

@leetwito made their first contribution in #2795

@Shufel83 made their first contribution in #3003

@boazdori made their first contribution in #2748

Contributors

Thanks to everyone who landed work in this release:

fix(setup): parse Claude OAuth token from wrapped PTY capture by @amit-shafnir in #2805

docs: add Korean README by @arkjun in #2806

refactor: remove dead resolveGroupIpcPath by @sturdy4days in #2803

refactor: mirror .claude skills + CLAUDE.md into .agents via symlinks by @Koshkoshinsk in #2810

feat(agent-to-agent): per-message approval policies on connected agents by @moshe-nanoco in #2793

fix(setup): allow env-selected agent provider by @amit-shafnir in #2811

chore(deps): move chat SDK + channel-adapter pins to 4.29.0 by @gabi-simons in #2834

fix(update-skills): nudge into skill updates, rebuild container on re-apply by @Koshkoshinsk in #2826

fix(setup): reap dead peer service registrations whose binary is gone by @amit-shafnir in #2830

feat(container): per-container CPU/memory limits (opt-in) by @omri-maya in #2856

feat: add /learn skill — distill or refine a reusable skill from anything by @robbyczgw-cla in #2843

feat(approvals): reject with reason by @moshe-nanoco in #2832

fix(migrate-v2): don't SELECT is_main from v1 registered_groups by @cben0ist in #2859

fix(ncl): default messaging-groups create instance to channel_type by @omri-maya in #2882

fix(security): contain inbox symlink escapes in attachment writes (#2828) by @johnmathews in #2880

fix(setup): offer Slack Socket Mode in the guided setup flow by @thisdotrob in #2885

feat(templates): local template loader, ncl --template, and docs by @amit-shafnir in #2890

[security] fix(cli): preserve caller context after approval by @Hinotoi-agent in #2611

Unregister the mock provider from the production container barrel by @gavrielc in #2927

Remove the dead /workspace/global mount and untrack v1 group seed files by @gavrielc in #2928

feat(approvals): render OneCLI approval requests from the gateway's structured summary by @gavrielc in #2929

command-gate: restore the /start filter and remove the fail-open admin check by @gavrielc in #2930

Fix ncl positional IDs for generated (dashed) identifiers by @gavrielc in #2932

feat: add /add-clidash — read-only CLI-derived dashboard skill by @leetwito in #2795

feat(approvals): colored buttons on approval cards (Slack primary/danger) by @gavrielc in #2933

Make the security-perimeter env vars reachable under the shipped service by @gavrielc in #2934

Delete dead v1 config knobs and the broken pnpm auth script by @gavrielc in #2935

Clean up dead ncl CLI protocol vocabulary by @gavrielc in #2936

Re-provision a missing session folder so the documented reset works by @gavrielc in #2937

Delete one-DB-era @deprecated shims and dead exports by @gavrielc in #2940

Fix the agent-to-agent in_reply_to stamp (cross-process no-op) by @gavrielc in #2942

Mount allowlist: honor the readOnly key and stop caching parse errors by @gavrielc in #2943

Rewrite the security docs to match the v2 perimeter by @gavrielc in #2945

Remove the dead data/env/env secrets mirror by @gavrielc in #2946

Fix stale architecture, scheduling, provider-config, and overlay docs by @gavrielc in #2948

Build agent images asynchronously instead of blocking the host by @gavrielc in #2931

docs: correct stale mount topology row + removed env var by @glifocat in #2953

docs: fix stale claims across README, CONTRIBUTING, CLAUDE.md and operational docs by @glifocat in #2961

docs: sync DB schema and entity docs with migrations 010-018 by @glifocat in #2962

docs: rewrite architecture.md and agent-runner-details.md to match current code by @glifocat in #2963

docs: update SDK deep-dive from 0.2.x to 0.3.197 by @glifocat in #2964

fix(agent-runner): match rate_limit_event as a top-level SDK message type by @glifocat in #2965

Wizard UX + add-slack Socket Mode fixes by @Koshkoshinsk in #2972

ncl CLI: verb-level args, deep help, server-rendered human view by @omri-maya in #2980

ci: auto-label PRs from core team members by @gabi-simons in #2978

Scheduled tasks: ncl tasks control plane, isolated sessions, script gate by @omri-maya in #2981

fix(cli): provision companion rows on ncl groups create and ncl wirings create by @glifocat in #2416

fix: stamp task rows with ISO timestamps by @gavrielc in #3005

fix: ISO storage + local-time display for all timestamps by @gavrielc in #3006

docs(agent-browser): require bounded waits for custom conditions by @Shufel83 in #3003

Move channel formatting skills (whatsapp, slack) from trunk to the channels branch by @gavrielc in #3009

feat: adapter-declared channel defaults (engage mode, threading, sender policy) by @gavrielc in #3010

add-teams: Teams-CLI-first credentials flow in SSF directive grammar by @Koshkoshinsk in #2958

Warn before connecting a shared WhatsApp number by @Koshkoshinsk in #3021

Guard seam: one decision function for every privileged action (guarded-actions phase 2) by @moshe-nanoco in #2986

feat: lean harness defaults for new agent groups by @gabi-simons in #3031

Tasks: one-door delivery — send_message is the only path out of a task session by @omri-maya in #2988

fix(agent-runner): log when an errored batch is acked completed by @glifocat in #2966

fix(delivery): route missing-adapter messages into the retry path by @glifocat in #2996

fix(container): warn when a real entry blocks a shared skill symlink by @glifocat in #3002

Structured skill format: setup installs channels by applying the SKILL.md by @gavrielc in #3035

feat: instance-wide default agent provider for new groups by @Koshkoshinsk in #2906

fix(self-mod): render full MCP server payload on the approval card by @glifocat in #2998

feat: support scheduled tasks in templates by @amit-shafnir in #3022

fix(skills): switch Telegram deep-link from t.me to telegram.me by @amit-shafnir in #3043

feat(memory): add provider-agnostic persistent memory by @amit-shafnir in #3012

docs(add-whatsapp-cloud): document webhook route + state-namespace migration for instance key by @glifocat in #2914

docs(changelog): drop duplicated Unreleased bullets by @glifocat in #3063

fix(agent-runner): compact_boundary must not surface as a result by @gavrielc in #3083

test(runner): drop temporary diagnostics from the /clear-abort test by @gavrielc in #3084

fix(claude): only abort on a rejected rate_limit_event; split rate_limit vs quota by @javexed in #3077

docs: rewrite branch maintenance guide for the registry-branch model by @glifocat in #3095

security: harden agent containers (cap-drop, no-new-privileges, pids-limit) by @boazdori in #2748

feat: per-agent-group timezone override by @Koshkoshinsk in #3125

setup: fetch a hardened agent image instead of building it by @gavrielc in #3150

container: make the Vercel CLI opt-in rather than baked into every image by @gavrielc in #3159

versions: repin the agent image to hardened-2026-07-30 by @gavrielc in #3160

fix(release): restore the v2.1.54 release path by @glifocat in #3163

Hosted iMessage (Photon): supersede #2999 with a working registration flow by @glifocat in #3164

fix(release): close post-merge safety gaps by @glifocat in #3168

Full Changelog: v2.1.17...v2.1.54

Original source

Changes

[BREAKING] @onecli-sh/sdk 0.5.0 → 2.2.1 — requires a OneCLI server with the /v1 API. Older servers 404 every SDK call. The sanctioned gateway and CLI versions are now pinned in versions.json, and the onecli setup step enforces them. The gateway is a separate component — updating NanoClaw does not upgrade it for you: /update-nanoclaw upgrades the gateway when its pin moves, otherwise upgrade manually. See docs/onecli-upgrades.md.

New agent provider: Codex (OpenAI) — run /add-codex. Full runtime via codex app-server (planning, MCP tools, server-side history, resume). Trunk ships the seams and the skill; the payload installs from the providers branch — via the skill, the setup picker, or --step provider-auth codex. Auth is vault-only; no credential ever enters a container.

Setup can now select, install, and authenticate a non-default agent provider. A provider registry feeds the setup picker, an installer pulls the provider's payload from its branch, a vault auth walkthrough runs (--step provider-auth), and the picked provider is set on the first agent — a DB property — before its first spawn. Default Claude installs are unaffected: picking Claude changes nothing.

Provider choice is explicit per group — no install-wide default. Provider is a DB property set via ncl groups config update --provider plus a restart; group creation is provider-agnostic.

/migrate-memory runs the cross-provider memory move; runtime never touches it. Each provider keeps its own memory store, so fresh groups on a surfaces-owning provider see no stale CLAUDE.* files left over from another provider's writes. See docs/provider-migration.md.

/update-nanoclaw now upgrades the OneCLI gateway when its pinned version moves. Pairs with the OneCLI SDK 2.2.1 BREAKING above: the gateway upgrade that used to require a manual step is folded into the standard /update-nanoclaw flow when the pin in versions.json shifts. Hosts whose gateway pin hasn't moved are unaffected.

Budget/billing-exhausted turns now reach the user instead of being silently dropped. When a turn ends in a non-retryable provider error — for example an Anthropic 403 billing_error — with no <message> wrapping, the agent-runner now delivers the provider's notice to the originating channel and stops re-nudging the failing gateway. providers/claude.ts surfaces the SDK's is_error flag and the error subtype's errors[] text; poll-loop.ts delivers that text and skips the re-wrap retry. Fixes the case where a spend-limit notice produced silence plus a turn-after-turn retry loop.

Command-gate denials now reach the sender. writeOutboundDirect was opening the session's outbound DB through the readonly opener, so the INSERT it ran threw SQLITE_READONLY on every call — the router's Permission denied response never delivered and the throw aborted further routing for that inbound event. Switched to the read-write opener (openOutboundDbRw, DELETE journal, busy_timeout); the host-side write stays even-seq, the container stays odd-seq, no contention.

Slash commands now interrupt an in-flight turn. A runner-handled command (/clear, /compact, /cost, …) arriving mid-turn aborts the active stream and runs immediately instead of waiting for the turn to finish.

Container boot failures now say why. A 10-line stderr tail is kept per spawn and surfaced at warn level on a non-zero exit (code !== null && code !== 0). Previously, a container that died at boot — unknown provider, missing binary, bad config — logged only at debug, which is below the default level, so the failure vanished into a silent crash loop.

Egress lockdown (opt-in). Containers can be pinned to an allowlisted egress set via ncl groups config update --egress-lockdown; outbound network calls outside the allowlist fail closed. Off by default. See docs/egress-lockdown.md.

Channel instances as a first-class dimension. A single channel kind — WhatsApp, Slack, … — can now run multiple independent instances per install, each with its own credentials, Chat SDK state, and webhook routes. Existing single-instance installs are preserved; the dispatcher falls back to channelType when no instance is set.

Native uninstaller. bash uninstall.sh from a checkout, or nanoclaw.sh --uninstall from the installed launcher, removes the service, the data directory, and the host registration in one step — no more manual launchctl bootout / systemctl --user disable. Includes --dry-run and a confirmation prompt; OneCLI agent registration is cleaned up alongside.

Interactive setup handoffs auto-submit context as Claude's first prompt. Mid-flow ? escapes and on-failure handoffs used to drop their context into --append-system-prompt with no user message, leaving Claude at an empty REPL while the operator re-explained themselves. Context now goes in as the first user message; handoffs in a single setup run also share a session-id (--session-id on the first spawn, --resume on the next), so the conversation thread survives across mid-flow escapes.

Raw-route webhook registry. Channels register raw HTTP routes through a registry instead of patching the host's route table directly, so a new channel can be added without touching core. The non-Chat-SDK webhook suite kept its own file path to make the diff reviewable.

Delivery-action getter. Channels expose a typed getDeliveryAction so the host can route a message to the right send / edit / react path without channel-side branching at the call site. Read side of the action registry; the write side stays in the channel adapters.

Approval-resolved callback registry. Channels can register a callback that fires when an approval resolves — approved or rejected — used for in-channel acknowledgment cards and audit-trail edits.

Per-exchange archiving is provider-owned. The onExchangeComplete hook fires per turn; the markdown writer ships with the provider that needs it (codex payload), and the runner stops archiving on a provider's behalf. Dormant for the default Claude provider.

[security] A2A symlink guard. Inbound A2A payload resolution now fails closed on any symlink escape from the per-group sandbox — the resolver rejects forwarded attachments that traverse out via a symlink.

[security] Approval admin authorization tightened. Approval response endpoints now require admin status and check the approver's scope against the request's group before executing — no cross-scope approvals.

[security] create_agent host-side authorization. Agent creation is now authorized on the host side as well as the API edge: for confined groups, host-side approval is required, so a compromised channel can't spawn agents it isn't entitled to.

host-sweep now respects a per-group wake grace so it doesn't tear down a container that just woke and still has a stale processing claim.

Global agent-container CLI installs are data-driven via container/cli-tools.json — skills add a CLI by appending a {name, version} JSON entry instead of patching the Dockerfile. agent-browser is now pinned to 0.27.1 (what latest last resolved to); the rest is byte-for-byte unchanged.

Four skills retired (broken on v2 architecture): claw, x-integration, add-parallel, convert-to-apple-container. References cleaned up in README.md, docs/SPEC.md, CONTRIBUTING.md, and CLAUDE.md.

Skills install model documented; see docs/skills-as-branches.md.

Twelve skills retrofitted to the current skill contract: add-dashboard, add-atomic-chat-tool, add-deltachat, add-slack, add-ollama-tool, migrate-from-openclaw, channel-family, opencode provider, codex provider, mcp, capability, use-native-credential-proxy.

Ollama docs guide added for making the Ollama prompt cache hit on the Claude-Code → Ollama path: a small proxy filters the per-request cch=<hash> the Claude Agent SDK prepends; in a 31B-on-Apple-Silicon setup, follow-up replies went ~80 s → ~4 s. Numbers vary by model. See docs/ollama.md.

chat-sdk-bridge records the acting user on resolved approval/question cards in shared channels — appends a — <userName> byline to the edited card so the audit trail of who clicked Approve or Reject survives the button removal.

@anthropic-ai/claude-code 2.1.170 and @anthropic-ai/claude-agent-sdk 0.3.170.

New Contributors

First NanoClaw PRs from @omri-maya, @markbala, @amit-shafnir, and @assapin landed in this release — welcome all four:

• @omri-maya — #2713
• @markbala — #2710
• @amit-shafnir — #2719
• @assapin — #2759

Want to be in the next one? Anyone can open a PR — pick up a good first issue or propose your own change directly. Discord is there if you want a hand getting started.

Contributors

Thanks to everyone who landed work in this release:

• @gavrielc — #2698, #2707, #2720, #2721, #2733, #2734, #2735, #2736, #2737, #2738, #2739, #2741, #2758
• @omri-maya — #2713, #2745, #2746, #2754, #2756
• @Koshkoshinsk — #2769, #2773, #2774, #2775
• @Hinotoi-agent — #2468, #2478
• @amit-shafnir — #2719
• @markbala — #2710
• @assapin — #2759
• @glifocat — #2764

Full Changelog: v2.1.0...v2.1.17

Original source

Rollup release covering v2.0.65 through v2.1.0 — every package.json bump merged since the v2.0.64 tag.

Changes

[BREAKING] Startup now requires an upgrade marker. The host refuses to boot unless data/upgrade-state.json records that this install reached the current version through a sanctioned path (/setup, /update-nanoclaw, /migrate-nanoclaw). After this update completes — and before restarting the service — stamp the marker by running pnpm exec tsx scripts/upgrade-state.ts set. If the host has already tripped on restart with "update did not go through the supported path", that same command clears it. (The tripwire code actually shipped in v2.1.1; v2.1.0 is the meaningful release boundary because the version bump and the feature merge sequenced in that order — every install on v2.1.1 or higher carries the tripwire.) See docs/upgrade-recovery.md.

/upload-trace ships the session transcript to Hugging Face. A runner-handled slash command (admin-gated, like /clear) pushes the current session's Claude Code transcript to the user's own private {hf_user}/nanoclaw-traces dataset, browsable in the HF Agent Trace Viewer. Auth runs through the OneCLI gateway: the HF token is injected by HTTPS_PROXY and never touches agent code; a missing or unassigned token returns a clear setup message pointing at the gateway URL.

New /add-rtk skill. Installs rtk into agent containers via host binary mount + a Claude Code PreToolUse hook, routing dev-loop commands through an output-summarizing proxy that saves 60–90% of tokens on compile/test/lint turns. Off by default — the skill opts a group in.

New whatsapp-formatting container skill. Inlined into every group's CLAUDE.md on container spawn (via claude-md-compose.ts) so agents see WhatsApp's mention syntax — @<phone-digits> sourced from content.sender, never display names — on every reply. Without this, agents defaulted to @<displayName>, which WhatsApp can't tag: the @ rendered as plain text with no notification. Mirrors the existing container/skills/slack-formatting/ layout; pairs with the channels-branch fix that wires mentions through to Baileys' contextInfo.

ncl groups delete now cascades cleanly. Sessions, destinations, members, wirings, scheduled tasks, and dropped messages tied to a deleted group are removed in the same transaction — no orphan rows, no follow-up sweep needed.

Long-lived hub sessions now rotate their transcript before resume. The Claude provider checks the on-disk .jsonl backing the stored continuation before each --resume; if it exceeds 12 MB or its first entry is older than 14 days, an archived markdown summary is written to conversations/ and a fresh session starts. Caps are operator-overridable via CLAUDE_TRANSCRIPT_ROTATE_BYTES and CLAUDE_TRANSCRIPT_ROTATE_AGE_DAYS; both honor a zero/negative value as "disabled". Fixes the symptom where a hub that was responsive for days goes silent on a heavy turn because the SDK reloads the full transcript on every resume and the first turn alone exceeds the host's 30-min idle ceiling.

Outbound <messages> envelope dropped — fixes the N>1 pending-message retry loop. When 2+ pending messages were bundled into <messages>...</messages>, the Claude Agent SDK returned a synthetic stub (model="<synthetic>", content="No response requested.") instead of calling the real API. The poll loop never marked the inbound row complete, the container exited, host-sweep respawned it with the same batch, and the transcript ballooned until tries=5 → failed. Single-message turns were unaffected because they skipped the wrapper. Each <message id=... from=...> block is already self-contained, so dropping the outer envelope lets N>1 turns work the same way N=1 always has.

Persistent inbound.db corruption now exits the container so host-sweep can respawn with a fresh mount. On Docker Desktop macOS, the kernel page cache for the bind-mounted inbound.db can latch a torn snapshot mid-host-write (a known virtiofs / gRPC-FUSE coherency issue); every fresh handle in the same process then sees the same broken view and emits database disk image is malformed at the poll rate. Reopening the handle inside the container does not recover — only a fresh container mount does. After ~5s of consecutive corruption errors (CORRUPTION_STREAK_EXIT), the runner exits with code 75 and host-sweep respawns it. Transient single torn reads are still tolerated.

Bumped @anthropic-ai/claude-code to 2.1.154 and @anthropic-ai/claude-agent-sdk to 0.3.154.

WhatsApp QR rendering wrapped so the QR block stays intact when piped through line-wrapping terminals.

OneCLI base URL moved from app. to api. to match the new gateway DNS.

setup-register scope tightened so it can't register a group outside the operator's scope.

Channel approval targets are now authorized against the approving admin's scope — no cross-group approvals via crafted payloads.

signal-cli 0.13+ identity field accepted; earlier versions kept working.

/add-teams CLI docs corrected — previous version referenced flags that had been renamed.

Photon integration URL corrected from photon.im to photon.codes to match the new authoritative domain.

CLAUDE.local.md writes now go through the SDK's settingSources plumbing so they survive a session reset.

New Contributors

First NanoClaw PRs from @claudiopostinghel, @snymanpaul, @mmahmed, @kartast, and @jonnychesthair-crypto landed in this release — welcome all five:

• @claudiopostinghel — #2551
• @snymanpaul — #2584
• @mmahmed — #2592
• @kartast — #2597
• @jonnychesthair-crypto — #2598

Want to be in the next one? Anyone can open a PR — pick up a good first issue or propose your own change directly. Discord is there if you want a hand getting started.

Contributors

Thanks to everyone who landed work in this release:

• @IamAdamJowett — #2553, #2556, #2586, #2595, #2596
• @gavrielc — #2637, #2648, #2690, #2691
• @glifocat — #2526
• @claudiopostinghel — #2551
• @guyb1 — #2558
• @kky — #2563
• @Hinotoi-agent — #2566
• @ira-at-work — #2571
• @snymanpaul — #2584
• @mmahmed — #2592
• @kartast — #2597
• @jonnychesthair-crypto — #2598

Full Changelog: v2.0.64...v2.1.0

Original source

Changes

ncl destinations add and remove through the approval flow now reach the receiver immediately. Approved destinations weren't being projected into the receiving agent's local session state, so a freshly-added destination silently failed at send_message with unknown destination, and a removed destination stayed resolvable until the next container restart. Both now take effect the moment the approval executes. Direct (non-approval) calls were unaffected.

Contributors

@glifocat — #2509, #2510, #2536

Full Changelog: v2.0.63...v2.0.64

Original source

First properly published release. Starting with v2.0.63, the goal is to publish a GitHub Release for every package.json version bump that lands on main — releases are cut manually by a maintainer, so there can be lag. Until now only the bumps landed and tags were sporadic, which made it hard for packagers and users to pin to a known version. See RELEASING.md for the policy.

Rollup release covering v2.0.55 through v2.0.63 — everything merged since the v2.0.54 tag.

Changes

[BREAKING] Service names are now per-install. On v2 installs the launchd label and systemd unit are slugged to your project root: com.nanoclaw.<sha1(projectRoot)[:8]> and nanoclaw-<slug>.service. The old com.nanoclaw / nanoclaw.service names no longer match a real service — update any copy-pasted restart or status commands. Find your install's names with source setup/lib/install-slug.sh && launchd_label (macOS) or systemd_unit (Linux). The ncl transport-error help text and 26 skill files now use the canonical helper-driven pattern; see setup/lib/install-slug.sh.

Compaction destination reminder placement fixed. The reminder injected after SDK auto-compaction now appears at the end of the compaction summary so it isn't stripped during truncation. Replaces the placement shipped in v2.0.54.

Stronger message-wrapping enforcement. The poll loop nudges the agent when its output lacks <message> wrapping, and CLAUDE.md core instructions now require wrapping even for single-destination agents. The welcome flow no longer double-greets.

OneCLI credentials after MCP install. MCP servers added through add_mcp_server now inherit OneCLI gateway routing — fixes the case where the agent kept asking for API keys after installing a new server.

CLI scope hardening. scopeField now fails closed when scope is missing, and sessions get is guarded against cross-group oracle access from group-scoped agents.

gmail/gcal skills aligned with v2. /add-gmail-tool and /add-gcal-tool now reflect the v2 container-config model — DB-backed mounts, no dead TOOL_ALLOWLIST edits, no container.json writes that get clobbered on next spawn. Manual sqlite3/JSON1 invocations corrected.

Repo-rename cleanup. Remaining qwibitai/nanoclaw references swept to nanocoai/nanoclaw across code and docs; CI workflow guards updated so they no longer no-op after the rename.

Slack scope checklist now includes files:read and files:write for skills that read or post attachments.

The internal-tag description in destination instructions no longer mentions scratchpads (which confused agents into routing them incorrectly).

Container startup is now graceful when the on_wake column is missing on older sessions DBs.

New Contributors

First NanoClaw PRs from @dvirarad and @intentionaleva landed in this release — welcome both:

• @dvirarad — #2400
• @intentionaleva — #2460

Want to be in the next one? Anyone can open a PR — pick up a good first issue or propose your own change directly. Discord is there if you want a hand getting started.

Contributors

Thanks to everyone who landed work in this release:

• @johnnyfish — #2384
• @glifocat — #2392, #2402, #2408, #2489, #2493
• @dvirarad — #2400
• @gavrielc — #2410, #2412, #2413, #2414
• @Koshkoshinsk — #2442, #2467, #2473
• @intentionaleva — #2460

Full Changelog: v2.0.54...v2.0.63

Original source

refactor: implement channel architecture and dynamic setup

Introduced ChannelRegistry for dynamic channel loading
Decoupled WhatsApp from core index.ts and config.ts
Updated setup wizard to support ENABLED_CHANNELS selection
Refactored IPC and group registration to be channel-aware
Verified with 359 passing tests and clean typecheck

style: fix formatting in config.ts to pass CI

refactor(setup): full platform-agnostic transformation

Harmonized all instructional text and help prompts
Implemented conditional guards for WhatsApp-specific steps
Normalized CLI terminology across all 4 initial channels
Unified troubleshooting and verification logic
Verified 369 tests pass with clean typecheck

feat(skills): transform WhatsApp into a pluggable skill

Created .claude/skills/add-whatsapp with full 5-phase interactive setup
Fixed TS7006 'implicit any' error in IpcDeps
Added auto-creation of STORE_DIR to prevent crashes on fresh installs
Verified with 369 passing tests and clean typecheck

refactor(skills): move WhatsApp from core to pluggable skill

Move src/channels/whatsapp.ts to add-whatsapp skill add/ folder
Move src/channels/whatsapp.test.ts to skill add/ folder
Move src/whatsapp-auth.ts to skill add/ folder
Create modify/ for barrel file (src/channels/index.ts)
Create tests/ with skill package validation test
Update manifest with adds/modifies lists
Remove WhatsApp deps from core package.json (now skill-managed)
Remove WhatsApp-specific ghost language from types.ts
Update SKILL.md to reflect skill-apply workflow
Co-Authored-By: Claude Opus 4.6 [email protected]

refactor(skills): move setup/whatsapp-auth.ts into WhatsApp skill

The WhatsApp auth setup step is channel-specific — move it from core
to the add-whatsapp skill so core stays minimal.
Co-Authored-By: Claude Opus 4.6 [email protected]

refactor(skills): convert Telegram skill to pluggable channel pattern

Replace the old direct-integration approach (modifying src/index.ts,
src/config.ts, src/routing.test.ts) with self-registration via the
channel registry, matching the WhatsApp skill pattern.
Co-Authored-By: Claude Opus 4.6 [email protected]

fix(skills): fix add-whatsapp build failure and improve auth flow

Add missing @types/qrcode-terminal to manifest npm_dependencies
(build failed after skill apply without it)
Make QR-browser the recommended auth method (terminal QR too small,
pairing codes expire too fast)
Remove "replace vs alongside" question — channels are additive
Add pairing code retry guidance and QR-browser fallback
Co-Authored-By: Claude Opus 4.6 [email protected]

fix: remove hardcoded WhatsApp default and stale Baileys comment

ENABLED_CHANNELS now defaults to empty (fresh installs must configure
channels explicitly via /setup; existing installs already have .env)
Remove Baileys-specific comment from storeMessageDirect() in db.ts
Co-Authored-By: Claude Opus 4.6 [email protected]

refactor(skills): convert Discord, Slack, Gmail skills to pluggable channel pattern

All channel skills now use the same self-registration pattern:
registerChannel() factory at module load time
Barrel file append (src/channels/index.ts) instead of orchestrator modifications
No more *_ONLY flags (DISCORD_ONLY, SLACK_ONLY) — use ENABLED_CHANNELS instead
Removed ~2500 lines of old modify/ files (src/index.ts, src/config.ts, src/routing.test.ts)
Gmail retains its container-runner.ts and agent-runner modifications (MCP
mount + server config) since those are independent of channel wiring.
Co-Authored-By: Claude Opus 4.6 [email protected]

refactor: use getRegisteredChannels instead of ENABLED_CHANNELS

Remove the ENABLED_CHANNELS env var entirely. The orchestrator now
iterates getRegisteredChannelNames() from the channel registry —
channels self-register via barrel imports and their factories return
null when credentials are missing, so unconfigured channels are
skipped automatically.
Deleted setup/channels.ts (and its tests) since its sole purpose was
writing ENABLED_CHANNELS to .env. Refactored verify, groups, and
environment setup steps to detect channels by credential presence
instead of reading ENABLED_CHANNELS.
Co-Authored-By: Claude Opus 4.6 [email protected]

docs: add breaking change notice and whatsapp migration instructions

CHANGELOG.md documents the pluggable channel architecture shift and
provides migration steps for existing WhatsApp users.
CLAUDE.md updated: Quick Context reflects multi-channel architecture,
Key Files lists registry.ts instead of whatsapp.ts, and a new
Troubleshooting section directs users to /add-whatsapp if WhatsApp
stops connecting after upgrade.
Co-Authored-By: Claude Opus 4.6 [email protected]

docs: rewrite READMEs for pluggable multi-channel architecture

Reflects the architectural shift from a hardcoded WhatsApp bot to a
pluggable channel platform. Adds upgrading notice, Mermaid architecture
diagram, CI/License/TypeScript/PRs badges, and clarifies that slash
commands run inside the Claude Code CLI.
Co-Authored-By: Claude Opus 4.6 [email protected]

docs: move pluggable channel architecture details to SPEC.md

Revert READMEs to original tone with only two targeted changes:
Add upgrading notice for WhatsApp breaking change
Mention pluggable channels in "What It Supports"
Move Mermaid diagram, channel registry internals, factory pattern
explanation, and self-registration walkthrough into docs/SPEC.md.
Update stale WhatsApp-specific references in SPEC.md to be
channel-agnostic.
Co-Authored-By: Claude Opus 4.6 [email protected]

docs: move upgrading notice to CHANGELOG, add changelog link

Remove the "Upgrading from Pre-Pluggable Versions" section from
README.md — breaking change details belong in the CHANGELOG. Add a
Changelog section linking to CHANGELOG.md.
Co-Authored-By: Claude Opus 4.6 [email protected]

docs: expand CHANGELOG with full PR #500 changes

Cover all changes: channel registry, WhatsApp moved to skill, removed
core dependencies, all 5 skills simplified, orchestrator refactored,
setup decoupled. Use Claude Code CLI instructions for migration.
Co-Authored-By: Claude Opus 4.6 [email protected]

chore: bump version to 1.2.0 for pluggable channel architecture

Minor version bump — new functionality (pluggable channels) with a
managed migration path for existing WhatsApp users. Update version
references in CHANGELOG and update skill.
Co-Authored-By: Claude Opus 4.6 [email protected]

Fix skill application

fix: use slotted barrel file to prevent channel merge conflicts

Pre-allocate a named comment slot for each channel in
src/channels/index.ts, separated by blank lines. Each skill's
modify file only touches its own slot, so three-way merges
never conflict when applying multiple channels.
Co-Authored-By: Claude Opus 4.6 [email protected]

fix: resolve real chat ID during setup for token-based channels

Instead of registering with pending@telegram (which never matches
incoming messages), the setup skill now runs an inline bot that waits
for the user to send /chatid, capturing the real chat ID before
registration.
Co-Authored-By: Claude Opus 4.6 [email protected]

fix: setup delegates to channel skills, fix group sync and Discord metadata

Restructure setup SKILL.md to delegate channel setup to individual
channel skills (/add-whatsapp, /add-telegram, etc.) instead of
reimplementing auth/registration inline with broken placeholder JIDs
Move channel selection to step 5 where it's immediately acted on
Fix setup/groups.ts: write sync script to temp file instead of passing
via node -e which broke on shell escaping of newlines
Fix Discord onChatMetadata missing channel and isGroup parameters
Add .tmp-* to .gitignore for temp sync script cleanup
Co-Authored-By: Claude Opus 4.6 [email protected]

fix: align add-whatsapp skill with main setup patterns

Add headless detection for auth method selection, structured inline
error handling, dedicated number DM flow, and reorder questions to
match main's trigger-first flow.
Co-Authored-By: Claude Opus 4.6 [email protected]

fix: add missing auth script to package.json

The add-whatsapp skill adds src/whatsapp-auth.ts but doesn't add
the corresponding npm script. Setup and SKILL.md reference npm run auth
for WhatsApp QR terminal authentication.
Co-Authored-By: Claude Opus 4.6 [email protected]

fix: update Discord skill tests to match onChatMetadata signature

The onChatMetadata callback now takes 5 arguments (jid, timestamp,
name, channel, isGroup) but the Discord skill tests only expected 3.
This caused skill application to roll back on test failure.
Co-Authored-By: Claude Opus 4.6 [email protected]

docs: replace 'pluggable' jargon with clearer language

User-facing text now says "multi-channel" or describes what it does.
Developer-facing text uses "self-registering" or "channel registry".
Also removes extra badge row from README.
Co-Authored-By: Claude Opus 4.6 [email protected]

docs: align Chinese README with English version

Remove extra badges, replace pluggable jargon, remove upgrade section
(now in CHANGELOG), add missing intro line and changelog section,
fix setup FAQ answer.
Co-Authored-By: Claude Opus 4.6 [email protected]

fix: warn on installed-but-unconfigured channels instead of silent skip

Channels with missing credentials now emit WARN logs naming the exact
missing variable, so misconfigurations surface instead of being hidden.
Co-Authored-By: Claude Opus 4.6 [email protected]

docs: simplify changelog to one-liner with compare link

Co-Authored-By: Claude Opus 4.6 [email protected]

feat: add isMain flag and channel-prefixed group folders

Replace MAIN_GROUP_FOLDER constant with explicit isMain boolean on
RegisteredGroup. Group folders now use channel prefix convention
(e.g., whatsapp_main, telegram_family-chat) to prevent cross-channel
collisions.
Add isMain to RegisteredGroup type and SQLite schema (with migration)
Replace all folder-based main group checks with group.isMain
Add --is-main flag to setup/register.ts
Strip isMain from IPC payload (defense in depth)
Update MCP tool description for channel-prefixed naming
Update all channel SKILL.md files and documentation
Co-Authored-By: Claude Opus 4.6 [email protected]

Co-authored-by: Claude Opus 4.6 [email protected]
Co-authored-by: gavrielc [email protected]
Co-authored-by: Koshkoshinski [email protected]

Original source