@intent-systems/nexus 2026.1.5-3

package/README.md

@@ -0,0 +1,462 @@
+# 🦞 NEXUS — Personal AI Assistant
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nexus/nexus/main/docs/whatsapp-nexus.jpg" alt="NEXUS" width="400">
+</p>
+
+<p align="center">
+  <strong>EXFOLIATE! EXFOLIATE!</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/nexus/nexus/actions/workflows/ci.yml?branch=main"><img src="https://img.shields.io/github/actions/workflow/status/nexus/nexus/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
+  <a href="https://github.com/nexus/nexus/releases"><img src="https://img.shields.io/github/v/release/nexus/nexus?include_prereleases&style=for-the-badge" alt="GitHub release"></a>
+  <a href="https://discord.gg/nexus"><img src="https://img.shields.io/discord/1456350064065904867?label=Discord&logo=discord&logoColor=white&color=5865F2&style=for-the-badge" alt="Discord"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
+</p>
+
+**Nexus** is a *personal AI assistant* you run on your own devices.
+It answers you on the providers you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat), can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.
+
+If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.
+
+[Website](https://nexus.com) · [Docs](https://docs.nexus.bot) · Updating: [https://docs.nexus.bot/updating](https://docs.nexus.bot/updating) · Showcase: [https://docs.nexus.bot/showcase](https://docs.nexus.bot/showcase) · FAQ: [https://docs.nexus.bot/faq](https://docs.nexus.bot/faq) · Wizard: [https://docs.nexus.bot/wizard](https://docs.nexus.bot/wizard) · Nix: [https://github.com/nexus/nix-nexus](https://github.com/nexus/nix-nexus) · Docker: [https://docs.nexus.bot/docker](https://docs.nexus.bot/docker) · Discord: [https://discord.gg/nexus](https://discord.gg/nexus)
+
+Preferred setup: run the onboarding wizard (`nexus onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**.
+Works with npm, pnpm, or bun.
+
+**Subscriptions (OAuth):**
+- **Anthropic** (Claude Pro/Max)
+- **OpenAI** (ChatGPT/Codex)
+
+Model note: while any model is supported, I strongly recommend **Anthropic Pro/Max (100/200) + Opus 4.5** for long‑context strength and better prompt‑injection resistance. See [Onboarding](https://docs.nexus.bot/onboarding).
+
+## Recommended setup (from source)
+
+Do **not** download prebuilt binaries. Run from source.
+
+```bash
+# Clone this repo
+git clone https://github.com/nexus/nexus.git
+cd nexus
+
+bun install
+bun run ui:install
+bun run ui:build
+bun run nexus onboard
+```
+
+Note: `bun run build` is optional here (it produces `dist/` for running via Node / the packaged `nexus` binary). `bun run nexus ...` runs TypeScript directly.
+
+## Quick start (from source)
+
+Runtime: **Node ≥22**.
+
+From source, **pnpm** is the default workflow. Bun is supported as an optional local workflow; see [Bun](https://docs.nexus.bot/bun).
+
+```bash
+# Install deps (no Bun lockfile)
+bun install --no-save
+
+# Build TypeScript
+bun run build
+
+# Build Control UI
+bun install --cwd ui --no-save
+bun run --cwd ui build
+
+# Recommended: run the onboarding wizard
+bun run nexus onboard
+
+# Link WhatsApp (stores creds in ~/nexus/state/credentials)
+bun run nexus login
+
+# Start the gateway
+bun run nexus gateway --port 18789 --verbose
+
+# Dev loop (auto-reload on TS changes)
+bun run gateway:watch
+
+# Send a message
+bun run nexus send --to +1234567890 --message "Hello from Nexus"
+
+# Talk to the assistant (optionally deliver back to WhatsApp/Telegram/Slack/Discord)
+bun run nexus agent --message "Ship checklist" --thinking high
+```
+
+Upgrading? https://docs.nexus.bot/updating (and run `nexus doctor`; use `--non-interactive` for cron/CI to avoid TTY hangs).
+
+If you run from source, prefer `bun run nexus …` or `pnpm nexus …` (not global `nexus`).
+
+## Security defaults (DM access)
+
+Nexus connects to real messaging surfaces. Treat inbound DMs as **untrusted input**.
+
+Full security guide: https://docs.nexus.bot/security
+
+Default behavior on Telegram/WhatsApp/Signal/iMessage/Discord/Slack:
+- **DM pairing** (`dmPolicy="pairing"` / `discord.dm.policy="pairing"` / `slack.dm.policy="pairing"`): unknown senders receive a short pairing code and the bot does not process their message.
+- Approve with: `nexus pairing approve --provider <provider> <code>` (then the sender is added to a local allowlist store).
+- Public inbound DMs require an explicit opt-in: set `dmPolicy="open"` and include `"*"` in the provider allowlist (`allowFrom` / `discord.dm.allowFrom` / `slack.dm.allowFrom`).
+
+Run `nexus doctor` to surface risky/misconfigured DM policies.
+
+## Highlights
+
+- **[Local-first Gateway](https://docs.nexus.bot/gateway)** — single control plane for sessions, channels, tools, and events.
+- **[Multi-channel inbox](https://docs.nexus.bot/surface)** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat, macOS, iOS/Android.
+- **[Multi-agent routing](docs/configuration.md)** — route inbound channels/accounts/peers to isolated agents (workspaces + per-agent sessions).
+- **[Voice Wake](https://docs.nexus.bot/voicewake) + [Talk Mode](https://docs.nexus.bot/talk)** — always-on speech for macOS/iOS/Android with ElevenLabs.
+- **[Live Canvas](https://docs.nexus.bot/mac/canvas)** — agent-driven visual workspace with [A2UI](https://docs.nexus.bot/mac/canvas#canvas-a2ui).
+- **[First-class tools](https://docs.nexus.bot/tools)** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions.
+- **[Companion apps](https://docs.nexus.bot/macos)** — macOS menu bar app + iOS/Android [nodes](https://docs.nexus.bot/nodes).
+- **[Onboarding](https://docs.nexus.bot/wizard) + [skills](https://docs.nexus.bot/skills)** — wizard-driven setup with bundled/managed/workspace skills.
+
+## Everything we built so far
+
+### Core platform
+- [Gateway WS control plane](https://docs.nexus.bot/gateway) with sessions, presence, config, cron, webhooks, [Control UI](https://docs.nexus.bot/web), and [Canvas host](https://docs.nexus.bot/mac/canvas#canvas-a2ui).
+- [CLI surface](https://docs.nexus.bot/agent-send): gateway, agent, send, [wizard](https://docs.nexus.bot/wizard), and [doctor](https://docs.nexus.bot/doctor).
+- [Pi agent runtime](https://docs.nexus.bot/agent) in RPC mode with tool streaming and block streaming.
+- [Session model](https://docs.nexus.bot/session): `main` for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: [Groups](https://docs.nexus.bot/groups).
+- [Media pipeline](https://docs.nexus.bot/images): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio](https://docs.nexus.bot/audio).
+
+### Channels
+- [Channels](https://docs.nexus.bot/surface): [WhatsApp](https://docs.nexus.bot/whatsapp) (Baileys), [Telegram](https://docs.nexus.bot/telegram) (grammY), [Slack](https://docs.nexus.bot/slack) (Bolt), [Discord](https://docs.nexus.bot/discord) (discord.js), [Signal](https://docs.nexus.bot/signal) (signal-cli), [iMessage](https://docs.nexus.bot/imessage) (imsg), [WebChat](https://docs.nexus.bot/webchat).
+- [Group routing](https://docs.nexus.bot/group-messages): mention gating, reply tags, per-channel chunking and routing. Channel rules: [Channels](https://docs.nexus.bot/surface).
+
+### Apps + nodes
+- [macOS app](https://docs.nexus.bot/macos): menu bar control plane, [Voice Wake](https://docs.nexus.bot/voicewake)/PTT, [Talk Mode](https://docs.nexus.bot/talk) overlay, [WebChat](https://docs.nexus.bot/webchat), debug tools, [remote gateway](https://docs.nexus.bot/remote) control.
+- [iOS node](https://docs.nexus.bot/ios): [Canvas](https://docs.nexus.bot/mac/canvas), [Voice Wake](https://docs.nexus.bot/voicewake), [Talk Mode](https://docs.nexus.bot/talk), camera, screen recording, Bonjour pairing.
+- [Android node](https://docs.nexus.bot/android): [Canvas](https://docs.nexus.bot/mac/canvas), [Talk Mode](https://docs.nexus.bot/talk), camera, screen recording, optional SMS.
+- [macOS node mode](https://docs.nexus.bot/nodes): system.run/notify + canvas/camera exposure.
+
+### Tools + automation
+- [Browser control](https://docs.nexus.bot/browser): dedicated nexus Chrome/Chromium, snapshots, actions, uploads, profiles.
+- [Canvas](https://docs.nexus.bot/mac/canvas): [A2UI](https://docs.nexus.bot/mac/canvas#canvas-a2ui) push/reset, eval, snapshot.
+- [Nodes](https://docs.nexus.bot/nodes): camera snap/clip, screen record, [location.get](https://docs.nexus.bot/location-command), notifications.
+- [Cron + wakeups](https://docs.nexus.bot/cron); [webhooks](https://docs.nexus.bot/webhook); [Gmail Pub/Sub](https://docs.nexus.bot/gmail-pubsub).
+- [Skills platform](https://docs.nexus.bot/skills): bundled, managed, and workspace skills with install gating + UI.
+
+### Ops + packaging
+- [Control UI](https://docs.nexus.bot/web) + [WebChat](https://docs.nexus.bot/webchat) served directly from the Gateway.
+- [Tailscale Serve/Funnel](https://docs.nexus.bot/tailscale) or [SSH tunnels](https://docs.nexus.bot/remote) with token/password auth.
+- [Nix mode](https://docs.nexus.bot/nix) for declarative config; [Docker](https://docs.nexus.bot/docker)-based installs.
+- [Doctor](https://docs.nexus.bot/doctor) migrations, [logging](https://docs.nexus.bot/logging).
+
+## How it works (short)
+
+```
+WhatsApp / Telegram / Slack / Discord / Signal / iMessage / WebChat
+               │
+               ▼
+┌───────────────────────────────┐
+│            Gateway            │  ws://127.0.0.1:18789
+│       (control plane)         │  bridge: tcp://0.0.0.0:18790
+└──────────────┬────────────────┘
+               │
+               ├─ Pi agent (RPC)
+               ├─ CLI (nexus …)
+               ├─ WebChat UI
+               ├─ macOS app
+               └─ iOS/Android nodes
+```
+
+## Key subsystems
+
+- **[Gateway WebSocket network](https://docs.nexus.bot/architecture)** — single WS control plane for clients, tools, and events (plus ops: [Gateway runbook](https://docs.nexus.bot/gateway)).
+- **[Tailscale exposure](https://docs.nexus.bot/tailscale)** — Serve/Funnel for the Gateway dashboard + WS (remote access: [Remote](https://docs.nexus.bot/remote)).
+- **[Browser control](https://docs.nexus.bot/browser)** — nexus‑managed Chrome/Chromium with CDP control.
+- **[Canvas + A2UI](https://docs.nexus.bot/mac/canvas)** — agent‑driven visual workspace (A2UI host: [Canvas/A2UI](https://docs.nexus.bot/mac/canvas#canvas-a2ui)).
+- **[Voice Wake](https://docs.nexus.bot/voicewake) + [Talk Mode](https://docs.nexus.bot/talk)** — always‑on speech and continuous conversation.
+- **[Nodes](https://docs.nexus.bot/nodes)** — Canvas, camera snap/clip, screen record, `location.get`, notifications, plus macOS‑only `system.run`/`system.notify`.
+
+## Tailscale access (Gateway dashboard)
+
+Nexus can auto-configure Tailscale **Serve** (tailnet-only) or **Funnel** (public) while the Gateway stays bound to loopback. Configure `gateway.tailscale.mode`:
+
+- `off`: no Tailscale automation (default).
+- `serve`: tailnet-only HTTPS via `tailscale serve` (uses Tailscale identity headers by default).
+- `funnel`: public HTTPS via `tailscale funnel` (requires shared password auth).
+
+Notes:
+- `gateway.bind` must stay `loopback` when Serve/Funnel is enabled (Nexus enforces this).
+- Serve can be forced to require a password by setting `gateway.auth.mode: "password"` or `gateway.auth.allowTailscale: false`.
+- Funnel refuses to start unless `gateway.auth.mode: "password"` is set.
+- Optional: `gateway.tailscale.resetOnExit` to undo Serve/Funnel on shutdown.
+
+Details: [Tailscale guide](https://docs.nexus.bot/tailscale) · [Web surfaces](https://docs.nexus.bot/web)
+
+## Remote Gateway (Linux is great)
+
+It’s perfectly fine to run the Gateway on a small Linux instance. Clients (macOS app, CLI, WebChat) can connect over **Tailscale Serve/Funnel** or **SSH tunnels**, and you can still pair device nodes (macOS/iOS/Android) to execute device‑local actions when needed.
+
+- **Gateway host** runs the bash tool and provider connections by default.
+- **Device nodes** run device‑local actions (`system.run`, camera, screen recording, notifications) via `node.invoke`.
+In short: bash runs where the Gateway lives; device actions run where the device lives.
+
+Details: [Remote access](https://docs.nexus.bot/remote) · [Nodes](https://docs.nexus.bot/nodes) · [Security](https://docs.nexus.bot/security)
+
+## macOS permissions via the Gateway protocol
+
+The macOS app can run in **node mode** and advertises its capabilities + permission map over the Gateway WebSocket (`node.list` / `node.describe`). Clients can then execute local actions via `node.invoke`:
+
+- `system.run` runs a local command and returns stdout/stderr/exit code; set `needsScreenRecording: true` to require screen-recording permission (otherwise you’ll get `PERMISSION_MISSING`).
+- `system.notify` posts a user notification and fails if notifications are denied.
+- `canvas.*`, `camera.*`, `screen.record`, and `location.get` are also routed via `node.invoke` and follow TCC permission status.
+
+Elevated bash (host permissions) is separate from macOS TCC:
+
+- Use `/elevated on|off` to toggle per‑session elevated access when enabled + allowlisted.
+- Gateway persists the per‑session toggle via `sessions.patch` (WS method) alongside `thinkingLevel`, `verboseLevel`, `model`, `sendPolicy`, and `groupActivation`.
+
+Details: [Nodes](https://docs.nexus.bot/nodes) · [macOS app](https://docs.nexus.bot/macos) · [Gateway protocol](https://docs.nexus.bot/architecture)
+
+## Agent to Agent (sessions_* tools)
+
+- Use these to coordinate work across sessions without jumping between chat surfaces.
+- `sessions_list` — discover active sessions (agents) and their metadata.
+- `sessions_history` — fetch transcript logs for a session.
+- `sessions_send` — message another session; optional reply‑back ping‑pong + announce step (`REPLY_SKIP`, `ANNOUNCE_SKIP`).
+
+Details: [Session tools](https://docs.nexus.bot/session-tool)
+
+## Skills registry (NexusHub)
+
+NexusHub is a minimal skill registry. With NexusHub enabled, the agent can search for skills automatically and pull in new ones as needed.
+
+https://NexusHub.com
+
+## Chat commands
+
+Send these in WhatsApp/Telegram/Slack/WebChat (group commands are owner-only):
+
+- `/status` — health + session info (group shows activation mode)
+- `/new` or `/reset` — reset the session
+- `/compact` — compact session context (summary)
+- `/think <level>` — off|minimal|low|medium|high
+- `/verbose on|off`
+- `/restart` — restart the gateway (owner-only in groups)
+- `/activation mention|always` — group activation toggle (groups only)
+
+## Apps (optional)
+
+The Gateway alone delivers a great experience. All apps are optional and add extra features.
+
+If you plan to build/run companion apps, initialize submodules first:
+
+```bash
+git submodule update --init --recursive
+./scripts/restart-mac.sh
+```
+
+### macOS (Nexus.app) (optional)
+
+- Menu bar control for the Gateway and health.
+- Voice Wake + push-to-talk overlay.
+- WebChat + debug tools.
+- Remote gateway control over SSH.
+
+Note: signed builds required for macOS permissions to stick across rebuilds (see `docs/mac/permissions.md`).
+
+### iOS node (optional)
+
+- Pairs as a node via the Bridge.
+- Voice trigger forwarding + Canvas surface.
+- Controlled via `nexus nodes …`.
+
+Runbook: [iOS connect](https://docs.nexus.bot/ios).
+
+### Android node (optional)
+
+- Pairs via the same Bridge + pairing flow as iOS.
+- Exposes Canvas, Camera, and Screen capture commands.
+- Runbook: [Android connect](https://docs.nexus.bot/android).
+
+## Agent workspace + skills
+
+- Workspace root: `~/nexus/home` (configurable via `agent.workspace`).
+- Injected prompt files: `AGENTS.md`, `SOUL.md`, `TOOLS.md`.
+- Skills: `<workspace>/skills/<skill>/SKILL.md`.
+
+## Configuration
+
+Minimal `~/nexus/state/nexus.json` (model + defaults):
+
+```json5
+{
+  agent: {
+    model: "anthropic/claude-opus-4-5"
+  }
+}
+```
+
+[Full configuration reference (all keys + examples).](https://docs.nexus.bot/configuration)
+
+## Security model (important)
+
+- **Default:** tools run on the host for the **main** session, so the agent has full access when it’s just you.
+- **Group/channel safety:** set `agent.sandbox.mode: "non-main"` to run **non‑main sessions** (groups/channels) inside per‑session Docker sandboxes; bash then runs in Docker for those sessions.
+- **Sandbox defaults:** allowlist `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`; denylist `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`.
+
+Details: [Security guide](https://docs.nexus.bot/security) · [Docker + sandboxing](https://docs.nexus.bot/docker) · [Sandbox config](https://docs.nexus.bot/configuration)
+
+### [WhatsApp](https://docs.nexus.bot/whatsapp)
+
+- Link the device: `pnpm nexus login` (stores creds in `~/nexus/state/credentials`).
+- Allowlist who can talk to the assistant via `whatsapp.allowFrom`.
+- If `whatsapp.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
+
+### [Telegram](https://docs.nexus.bot/telegram)
+
+- Set `TELEGRAM_BOT_TOKEN` or `telegram.botToken` (env wins).
+- Optional: set `telegram.groups` (with `telegram.groups."*".requireMention`); when set, it is a group allowlist (include `"*"` to allow all). Also `telegram.allowFrom` or `telegram.webhookUrl` as needed.
+
+```json5
+{
+  telegram: {
+    botToken: "123456:ABCDEF"
+  }
+}
+```
+
+### [Slack](https://docs.nexus.bot/slack)
+
+- Set `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or `slack.botToken` + `slack.appToken`).
+
+### [Discord](https://docs.nexus.bot/discord)
+
+- Set `DISCORD_BOT_TOKEN` or `discord.token` (env wins).
+- Optional: set `discord.slashCommand`, `discord.dm.allowFrom`, `discord.guilds`, or `discord.mediaMaxMb` as needed.
+
+```json5
+{
+  discord: {
+    token: "1234abcd"
+  }
+}
+```
+
+### [Signal](https://docs.nexus.bot/signal)
+
+- Requires `signal-cli` and a `signal` config section.
+
+### [iMessage](https://docs.nexus.bot/imessage)
+
+- macOS only; Messages must be signed in.
+- If `imessage.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
+
+### [WebChat](https://docs.nexus.bot/webchat)
+
+- Uses the Gateway WebSocket; no separate WebChat port/config.
+
+Browser control (optional):
+
+```json5
+{
+  browser: {
+    enabled: true,
+    controlUrl: "http://127.0.0.1:18791",
+    color: "#FF4500"
+  }
+}
+```
+
+## Docs
+
+Use these when you’re past the onboarding flow and want the deeper reference.
+- [Start with the docs index for navigation and “what’s where.”](https://docs.nexus.bot)
+- [Read the architecture overview for the gateway + protocol model.](https://docs.nexus.bot/architecture)
+- [Use the full configuration reference when you need every key and example.](https://docs.nexus.bot/configuration)
+- [Run the Gateway by the book with the operational runbook.](https://docs.nexus.bot/gateway)
+- [Learn how the Control UI/Web surfaces work and how to expose them safely.](https://docs.nexus.bot/web)
+- [Understand remote access over SSH tunnels or tailnets.](https://docs.nexus.bot/remote)
+- [Follow the onboarding wizard flow for a guided setup.](https://docs.nexus.bot/wizard)
+- [Wire external triggers via the webhook surface.](https://docs.nexus.bot/webhook)
+- [Set up Gmail Pub/Sub triggers.](https://docs.nexus.bot/gmail-pubsub)
+- [Learn the macOS menu bar companion details.](https://docs.nexus.bot/mac/menu-bar)
+- [Platform guides: Windows](https://docs.nexus.bot/windows), [Linux](https://docs.nexus.bot/linux), [macOS](https://docs.nexus.bot/macos), [iOS](https://docs.nexus.bot/ios), [Android](https://docs.nexus.bot/android)
+- [Debug common failures with the troubleshooting guide.](https://docs.nexus.bot/troubleshooting)
+- [Review security guidance before exposing anything.](https://docs.nexus.bot/security)
+
+## Advanced docs (discovery + control)
+
+- [Discovery + transports](https://docs.nexus.bot/discovery)
+- [Bonjour/mDNS](https://docs.nexus.bot/bonjour)
+- [Gateway pairing](https://docs.nexus.bot/gateway/pairing)
+- [Remote gateway README](https://docs.nexus.bot/remote-gateway-readme)
+- [Control UI](https://docs.nexus.bot/control-ui)
+- [Dashboard](https://docs.nexus.bot/dashboard)
+
+## Operations & troubleshooting
+
+- [Health checks](https://docs.nexus.bot/health)
+- [Gateway lock](https://docs.nexus.bot/gateway-lock)
+- [Background process](https://docs.nexus.bot/background-process)
+- [Browser troubleshooting (Linux)](https://docs.nexus.bot/browser-linux-troubleshooting)
+- [Logging](https://docs.nexus.bot/logging)
+
+## Deep dives
+
+- [Agent loop](https://docs.nexus.bot/agent-loop)
+- [Presence](https://docs.nexus.bot/presence)
+- [TypeBox schemas](https://docs.nexus.bot/typebox)
+- [RPC adapters](https://docs.nexus.bot/rpc)
+- [Queue](https://docs.nexus.bot/queue)
+
+## Workspace & skills
+
+- [Skills config](https://docs.nexus.bot/skills-config)
+- [Default AGENTS](https://docs.nexus.bot/AGENTS.default)
+- [Templates: AGENTS](https://docs.nexus.bot/templates/AGENTS)
+- [Templates: BOOTSTRAP](https://docs.nexus.bot/templates/BOOTSTRAP)
+- [Templates: IDENTITY](https://docs.nexus.bot/templates/IDENTITY)
+- [Templates: SOUL](https://docs.nexus.bot/templates/SOUL)
+- [Templates: TOOLS](https://docs.nexus.bot/templates/TOOLS)
+- [Templates: USER](https://docs.nexus.bot/templates/USER)
+
+## Platform internals
+
+- [macOS dev setup](https://docs.nexus.bot/mac/dev-setup)
+- [macOS menu bar](https://docs.nexus.bot/mac/menu-bar)
+- [macOS voice wake](https://docs.nexus.bot/mac/voicewake)
+- [iOS node](https://docs.nexus.bot/ios)
+- [Android node](https://docs.nexus.bot/android)
+- [Windows app](https://docs.nexus.bot/windows)
+- [Linux app](https://docs.nexus.bot/linux)
+
+## Email hooks (Gmail)
+
+[Gmail Pub/Sub wiring (gcloud + gogcli), hook tokens, and auto-watch behavior are documented here.](https://docs.nexus.bot/gmail-pubsub)
+
+Gateway auto-starts the watcher when `hooks.enabled=true` and `hooks.gmail.account` is set; `nexus hooks gmail run` is the manual daemon wrapper if you don’t want auto-start.
+
+```bash
+nexus hooks gmail setup --account you@gmail.com
+nexus hooks gmail run
+```
+
+## Nexus
+
+Nexus was built for **Nexus**, a space lobster AI assistant. 🦞  
+by Peter Steinberger and the community.
+
+- https://nexus.me
+- https://soul.md
+- https://steipete.me
+
+## Community
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, maintainers, and how to submit PRs.  
+AI/vibe-coded PRs welcome! 🤖
+
+Thanks to all clawtributors:
+
+<p align="left">
+  <a href="https://github.com/steipete"><img src="https://avatars.githubusercontent.com/u/58493?v=4&s=48" width="48" height="48" alt="steipete" title="steipete"/></a> <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/joshp123"><img src="https://avatars.githubusercontent.com/u/1497361?v=4&s=48" width="48" height="48" alt="joshp123" title="joshp123"/></a> <a href="https://github.com/joaohlisboa"><img src="https://avatars.githubusercontent.com/u/8200873?v=4&s=48" width="48" height="48" alt="joaohlisboa" title="joaohlisboa"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/mukhtharcm"><img src="https://avatars.githubusercontent.com/u/56378562?v=4&s=48" width="48" height="48" alt="mukhtharcm" title="mukhtharcm"/></a> <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a> <a href="https://github.com/Nachx639"><img src="https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width="48" height="48" alt="Nachx639" title="Nachx639"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a>
+  <a href="https://github.com/mbelinky"><img src="https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width="48" height="48" alt="mbelinky" title="mbelinky"/></a> <a href="https://github.com/julianengel"><img src="https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width="48" height="48" alt="julianengel" title="julianengel"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a> <a href="https://github.com/omniwired"><img src="https://avatars.githubusercontent.com/u/322761?v=4&s=48" width="48" height="48" alt="omniwired" title="omniwired"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/vsabavat"><img src="https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width="48" height="48" alt="vsabavat" title="vsabavat"/></a>
+  <a href="https://github.com/scald"><img src="https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width="48" height="48" alt="scald" title="scald"/></a> <a href="https://github.com/sreekaransrinath"><img src="https://avatars.githubusercontent.com/u/50989977?v=4&s=48" width="48" height="48" alt="sreekaransrinath" title="sreekaransrinath"/></a> <a href="https://github.com/ratulsarna"><img src="https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width="48" height="48" alt="ratulsarna" title="ratulsarna"/></a> <a href="https://github.com/osolmaz"><img src="https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width="48" height="48" alt="osolmaz" title="osolmaz"/></a> <a href="https://github.com/conhecendocontato"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendocontato" title="conhecendocontato"/></a> <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a> <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a> <a href="https://github.com/jamesgroat"><img src="https://avatars.githubusercontent.com/u/2634024?v=4&s=48" width="48" height="48" alt="jamesgroat" title="jamesgroat"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="djangonavarro220" title="djangonavarro220"/></a>
+  <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a> <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a>
+  <a href="https://github.com/adamgall"><img src="https://avatars.githubusercontent.com/u/706929?v=4&s=48" width="48" height="48" alt="adamgall" title="adamgall"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/mneves75"><img src="https://avatars.githubusercontent.com/u/2423436?v=4&s=48" width="48" height="48" alt="mneves75" title="mneves75"/></a> <a href="https://github.com/regenrek"><img src="https://avatars.githubusercontent.com/u/5182020?v=4&s=48" width="48" height="48" alt="regenrek" title="regenrek"/></a> <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="tobiasbischoff" title="tobiasbischoff"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/dbhurley"><img src="https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width="48" height="48" alt="dbhurley" title="dbhurley"/></a>
+  <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="Iamadig" title="Iamadig"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/nachoiacovino"><img src="https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width="48" height="48" alt="nachoiacovino" title="nachoiacovino"/></a> <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a> <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=48" width="48" height="48" alt="claude" title="claude"/></a> <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a>
+</p>

package/dist/agents/agent-paths.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { resolveUserPath } from "../utils.js";
+export function resolveNexusAgentDir() {
+    const override = process.env.NEXUS_AGENT_DIR?.trim();
+    if (override)
+        return resolveUserPath(override);
+    const agentId = process.env.NEXUS_AGENT_ID?.trim() || "default";
+    return path.join(resolveStateDir(), "agents", agentId);
+}
+export function ensureNexusAgentEnv() {
+    const dir = resolveNexusAgentDir();
+    if (!process.env.NEXUS_AGENT_DIR)
+        process.env.NEXUS_AGENT_DIR = dir;
+    return dir;
+}

package/dist/agents/agent-scope.js

@@ -0,0 +1,44 @@
+import os from "node:os";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { DEFAULT_AGENT_ID, normalizeAgentId, parseAgentSessionKey, } from "../routing/session-key.js";
+import { resolveUserPath } from "../utils.js";
+import { DEFAULT_AGENT_WORKSPACE_DIR } from "./workspace.js";
+export function resolveAgentIdFromSessionKey(sessionKey) {
+    const parsed = parseAgentSessionKey(sessionKey);
+    return normalizeAgentId(parsed?.agentId ?? DEFAULT_AGENT_ID);
+}
+export function resolveAgentConfig(cfg, agentId) {
+    const id = normalizeAgentId(agentId);
+    const agents = cfg.routing?.agents;
+    if (!agents || typeof agents !== "object")
+        return undefined;
+    const entry = agents[id];
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    return {
+        workspace: typeof entry.workspace === "string" ? entry.workspace : undefined,
+        agentDir: typeof entry.agentDir === "string" ? entry.agentDir : undefined,
+    };
+}
+export function resolveAgentWorkspaceDir(cfg, agentId) {
+    const id = normalizeAgentId(agentId);
+    const configured = resolveAgentConfig(cfg, id)?.workspace?.trim();
+    if (configured)
+        return resolveUserPath(configured);
+    if (id === DEFAULT_AGENT_ID) {
+        const legacy = cfg.agent?.workspace?.trim();
+        if (legacy)
+            return resolveUserPath(legacy);
+        return DEFAULT_AGENT_WORKSPACE_DIR;
+    }
+    return path.join(os.homedir(), `nexus-${id}`);
+}
+export function resolveAgentDir(cfg, agentId) {
+    const id = normalizeAgentId(agentId);
+    const configured = resolveAgentConfig(cfg, id)?.agentDir?.trim();
+    if (configured)
+        return resolveUserPath(configured);
+    const root = resolveStateDir(process.env, os.homedir);
+    return path.join(root, "agents", id, "agent");
+}