Tooling

Nexus Tools

Everything you need to connect local agents to the Nexus platform and manage project memory from the command line.

nexus-mcp

Publishedv0.10.1npm

The mandatory mediation layer between local agent runtimes and the shared backend. All reads and writes to project memory, coordination, and governance workflows flow through the MCP server. The server communicates exclusively with the Nexus HTTP API — no direct database access.

npm: @gwdn/nexus-mcp | Repository: github.com/gwnexus/nexus-mcp (private)

Available tools (58)

Layer 1 — Knowledge Access

kb_searchSearch project knowledge using keyword, semantic, or hybrid mode with relevance ranking

kb_memoryGet curated project context for agent bootstrapping (ADRs, tasks, sessions, letters)

kb_getFetch a single knowledge object in structured, markdown, or summary format

kb_relatedNavigate entity relationships and graph-neighbor entities

project_listList accessible projects for the authenticated user or agent

Layer 2 — Coordination: Nexus Dispatch

dispatch_createCreate a new routed Dispatch for agent-to-agent, agent-to-human, or cross-project coordination

dispatch_replyAppend a reply or timeline entry to an existing Dispatch with optional status transition

dispatch_inboxList Dispatches addressed to the calling agent or project — scoped by blocking, waiting-on-me, or cross-project filters

dispatch_outboxList Dispatches created by the calling agent or project

dispatch_ackAcknowledge receipt of a Dispatch, transitioning it from open to acknowledged

dispatch_assignAssign or reassign a Dispatch to an actor within the project registry

dispatch_forwardForward a Dispatch to another actor or linked project

dispatch_resolveMark a Dispatch as resolved with an optional resolution note

dispatch_closeClose a resolved Dispatch — terminal state, no further transitions

dispatch_sweepSession-start overview: blocking, overdue, waiting-on-me, new assignments, and recent updates in one call

dispatch_getFetch a full Dispatch with its append-only message timeline and participant list

dispatch_relatedFind structurally related Dispatches for loop prevention and duplicate detection

Layer 2 — Coordination: Tasks

task_createCreate a new task within a project scope

task_updateUpdate task status, priority, assignee, title, or description — at least one field required

task_noteAppend a note to a task for progress, blockers, or decisions

task_deleteHard-delete a task by UUID — use for cleanup of erroneous or duplicate tasks

task_listList tasks for a project with optional status filtering, ordered by creation date

Layer 2 — Coordination: Sessions

session_createCreate a new work session for a project

session_listList open sessions for a project, ordered by creation date

session_closeClose an open session with optional summary and next entry point

session_appendAppend an entry to an existing session with write isolation

session_deleteDelete empty closed sessions for cleanup

Layer 2 — Coordination: Decisions & Documents

dc_addAdd a comment to an ADR decision (append-only, supports human and agent actors)

dc_listList comments for an ADR decision in chronological order

doc_ingestPush text or markdown content into a project knowledge base

doc_listList ingested documents for a project with optional source filtering

doc_updateUpdate title, body, or source URL of an ingest item with full or append mode

doc_classifySet the classification of an ingest item (research_note, planning_item, decision_input, reference, archive)

doc_deletePermanently delete an ingest item from the project knowledge base

Layer 2 — Coordination: Skills

sk_listList skills for the current tenant with status filtering

sk_getGet full skill content by identifier or UUID

sk_createCreate a new skill in draft status with optional command auto-generation

sk_updateUpdate skill content, metadata, or command settings

sk_activateChange skill status (draft, active, archived)

sk_assignAssign a skill to a specific project scope

sk_unassignRemove a skill assignment from a project

sk_exportExport skill content for local agent bootstrap

Layer 2 — Coordination: Agent Files

af_listList agent files for the current tenant with status filtering

af_getGet full agent file content by identifier or UUID

af_createCreate a new agent file in draft status with license check

af_updateUpdate agent file content with automatic versioning

af_activateChange agent file status (draft, active, archived)

af_exportExport agent file content with template variable injection and directives

Layer 2 — Coordination: Project Directives

pd_createCreate a new project directive (rule/policy) that guides agent behavior

pd_getGet a specific project directive by UUID with full details

pd_listList project directives with optional enabled filter, ordered by priority

pd_updateUpdate directive title, body, category, priority, or enabled state

pd_deleteDelete a project directive by UUID (irreversible)

pd_toggleToggle a directive enabled/disabled — omit state to invert current

directive_exportExport all enabled directives for a project in CLI-compatible format

Utility

identityResolve current user/agent identity (whoami)

cost_summaryShow token usage and estimated cost for the current session

show_pluginsList all loaded Nexus plugins, their versions, and connection status

Layer 3 — Governance

adr_createCreate a new ADR in draft state with auto-assigned number

adr_submitSubmit an ADR for review (draft to under_review)

adr_decideAccept or reject an ADR with optional rationale and supersession tracking

Layer 4 — Reviews

rv_listList entity reviews filtered by status and entity type

rv_getGet review details including comments and decision history

rv_createRequest a review for any governed entity

rv_decideApprove or reject a pending review with rationale

rv_commentAdd a comment to an active review thread

Quick start

# Run via npx (recommended — no local install needed)
npx @gwdn/nexus-mcp

# Or add to your MCP client configuration:
# OpenCode (opencode.json)
{
  "mcp": {
    "nexus": {
      "type": "local",
      "command": ["npx", "@gwdn/nexus-mcp"],
      "environment": {
        "NEXUS_API_URL": "https://nexus.gatewarden.eu",
        "NEXUS_PRIVATE_TOKEN": "nxs_pat_..."
      }
    }
  }
}

# Claude Code (.claude/mcp.json)
{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["@gwdn/nexus-mcp"],
      "env": {
        "NEXUS_API_URL": "https://nexus.gatewarden.eu",
        "NEXUS_PRIVATE_TOKEN": "nxs_pat_..."
      }
    }
  }
}

nexus-cli

Publishedv0.9.2Rust

A fast, native CLI client for the Nexus platform. nexus-cli scaffolds complete agentic workspaces — pulling skills, agent files, directives, MCP server configs, OpenCode plugins, and multi-agent support files (.cursorrules, .github/copilot-instructions.md, .rtk/filters.toml) from the Nexus backend into customer repositories. All Nexus-generated files are written exclusively to .nexus/ — existing .claude/ configurations are never modified. The CLI authenticates via the same API token model as the MCP server and communicates exclusively through the Nexus HTTP API.

Repository: github.com/gwnexus/nexus-cli (open source)

Commands

Project Setup

nexus initInitialize a Nexus project workspace (scaffold .nexus/, MCP configs, agent files)

nexus importScan workspace for existing agentic files (CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md, .windsurf/rules/*.md, GEMINI.md), extract directives, resolve Markdown links, and import into the linked Nexus project. Supports --dry-run and -y/--yes flags.

nexus linkBind the current directory to a Nexus project

nexus unlinkRemove project binding from the workspace

nexus deinitRemove all Nexus/AI scaffold files from the workspace

Platform

nexus loginAuthenticate with the Nexus platform (PAT-based)

nexus logoutRemove stored credentials

nexus statusShow auth, project, and workspace status

nexus preflightRun environment readiness checks (git, node, npm, auth, API)

Sync

nexus pullPull skills, agent files, directives, and MCP configs from Nexus into the workspace

nexus skills exportExport enabled skills for the linked project as JSON

Configuration

nexus config showDisplay current CLI configuration

nexus config setUpdate a config value (api_url, default_output, no_color, mcp_source)

nexus config pathShow the config file path

Shadow Mode

nexus shadow onExclude workspace agentic files from Git tracking via .git/info/exclude

nexus shadow offRe-enable Git tracking for agentic scaffold files

nexus shadow statusShow current shadow mode status

Maintenance

nexus upgradeUpgrade the Nexus CLI to the latest release version

Quick start

# Install via oneliner
curl -fsSL https://nexus.gatewarden.eu/install.sh | bash

# Or install from source
cargo install --git https://github.com/gwnexus/nexus-cli.git nexusctl

# Authenticate
nexus login

# Initialize a customer project
nexus init --project-id <uuid>

# Pull skills and configuration
nexus pull

# Check environment readiness
nexus preflight

Notable flags

--shadowed-ai[DEPRECATED in v0.6.4] Superseded by automatic .git/info/exclude management (ADR-0029)

--yes / -yAccept all defaults without interactive prompts (non-interactive mode)

--force / -fOverwrite existing scaffold files during init

nexus-link

Publishedv0.8.7Rust

Hardware telemetry agent for the Nexus platform. Connects on-premise AI hardware nodes (NVIDIA DGX Spark, DGX A100/H100) to the Nexus backend with live GPU/CPU/memory metrics and remote compose management — without requiring inbound network access into your infrastructure. Uses a hybrid data channel: outbound telemetry push plus an inbound HTTPS command service for remote operations. Designed for private-network (WireGuard / LAN) deployments.

Repository: github.com/gwnexus/nexus-link (open source)

Architecture

┌──────────────────────────────────────────────────────────────────┐
│  On-Premise Node (e.g. DGX Spark)                                │
│                                                                  │
│  nexus-link-agent ──────────────► Nexus API                      │
│  (telemetry push, 30s interval)    POST /api/nodes/:id/telemetry │
│                                                                  │
│  nexus-link-service ◄──────────── Nexus App                      │
│  (axum HTTPS :8443)               signed command payloads        │
└──────────────────────────────────────────────────────────────────┘

Commands

Node Management

nexus-link registerRegister this node with the Nexus platform. Pass --token <nxs_node_*> and --cmd-token <nxs_cmd_*> from the dashboard wizard. Runs preflight check automatically.

nexus-link preflightRun device compatibility check (architecture, GPU, Docker, network, disk)

nexus-link statusShow node registration and agent status

nexus-link refreshRotate the node token with a 24h grace period. Run with --token <new_nxs_node_*> from the dashboard.

nexus-link refresh-cmdApply a rotated command token immediately. Run with --cmd-token <new_nxs_cmd_*>. No service restart required.

Agent

nexus-link agent startStart the telemetry agent and command service as systemd units (push metrics every 30s)

nexus-link agent stopStop the running agent and command service

nexus-link agent logsShow agent logs (supports -t flag for tail count)

Compose Management (via Dashboard)

GET /api/compose/fileRead docker-compose.yaml and companion config files (.env, .conf, .toml) from the compose directory

PUT /api/compose/fileWrite docker-compose.yaml atomically (YAML validation, optional git commit). Requires nxs_cmd_* token + Ed25519 signature.

POST /api/compose/activateRun docker compose up -d on the node (120s timeout). Returns stdout/stderr. Requires nxs_cmd_* token + Ed25519 signature.

GET /api/compose/logsStream docker compose logs as Server-Sent Events. Query: ?tail=200&service=<name>

Configuration

nexus-link config showDisplay all configuration: node token prefix, cmd token status, signing key, compose dir, service port

nexus-link config set <key> <value>Update a config value. Keys: api_url, push_interval, listen_addr, port, name, tags, compose_dir, compose.cmd_token, compose.require_signatures

Supported Devices

Device	Identifier	Notes
NVIDIA DGX Spark	`gb10`	GB10 Grace Blackwell, 128 GB, aarch64
NVIDIA DGX Station A100	`a100`	4x A100 80GB, AMD EPYC, x86_64
NVIDIA DGX A100	`dgx-a100`	8x A100 80GB, AMD EPYC, x86_64
NVIDIA DGX H100	`dgx-h100`	8x H100 80GB, x86_64

Security model

nexus-link uses two independent credentials per device (ADR-0051). This separates read-only telemetry from write-capable compose management — a compromised telemetry process cannot trigger service restarts or file changes.

nxs_node_*

Node token — telemetry channel. Used by the long-running nexus-link-agent to push metrics every 30s and by heartbeat/unregister flows. Stored in ~/.nexus-link/config.toml. Supports a 24h rotation grace period so the device never loses connectivity during token rotation.

nxs_cmd_*

Command token — compose control channel. Required by nexus-link-service for all /api/compose/* routes (file read/write, activate, log stream). Stored encrypted (AES-256-GCM) in the backend database — never exposed to the browser. Rotated immediately via the dashboard with no grace period.

Write operations (PUT /api/compose/file, POST /api/compose/activate) are additionally protected by Ed25519 request signing. The Nexus backend signs each request with a private key that never leaves the server. The device verifies using the public key delivered at registration and stored in ~/.nexus-link/signing_key.pub. A ±5-minute timestamp window and a random nonce prevent replay attacks. Signature enforcement is opt-in via nexus-link config set compose.require_signatures true.

⚠

nexus-link is designed for private-network deployments (LAN or WireGuard VPN). Exposing port 8443 to the public internet is not recommended while the security audit is in progress. The service endpoint is auto-detected from the device private IP at registration — no DNS or reverse-proxy setup required for WireGuard setups.

Quick start

# Install via oneliner
curl -fsSL https://nexus.gatewarden.eu/install-link.sh | bash

# Or install from source (requires Rust >= 1.85)
cargo install --git https://github.com/gwnexus/nexus-link.git nexus-link-cli

# Register node — both tokens from the Nexus dashboard wizard
nexus-link register \
  --token     <nxs_node_*> \
  --cmd-token <nxs_cmd_*>

# Start telemetry agent + command service
nexus-link agent start

# Check status (shows both token channels and signing key state)
nexus-link status

OpenCode Plugins

3 Free4 Alpha

Nexus provides open-source plugins for OpenCode that extend the editor runtime with platform-aware behavior. Plugins are distributed as TypeScript source files via nexus init and nexus pull — no npm install required. They load automatically from the .opencode/plugins/ directory at startup.

Plugin	Version	Status	Description	Repo
nexus-compaction-plus	v1.8.0	Published	Preserves Nexus session context across OpenCode compaction events and records each compaction as an auditable session entry.	GitHub
nexus-cost-control	v2.0.0	Published	Token usage and cost tracking for Nexus sessions using native OpenCode message data. Zero external dependencies.	GitHub
nexus-headroom-intercept	v0.1.0	Published	Pre-injection context compression for Nexus MCP tool outputs via the tool.execute.after hook.	GitHub
nexus-vault-shield	v0.1.0	Alpha	Classification-driven encryption for documents and project artifacts based on customer/project confidentiality levels.	—
nexus-knowledge-graph	v0.1.0	Alpha	Transforms uploaded documents into a searchable knowledge graph with entity and relationship extraction.	—
nexus-llm-bridge	v0.1.0	Alpha	Connect your own vLLM/LLM inference stack and auto-configure it as a dedicated provider in OpenCode workspaces.	—
nexus-ci-bridge	v0.1.0	Alpha	CI/CD pipeline integration — validates PRs against ADRs, generates review comments, and reports results to Nexus sessions.	—

View dedicated plugin catalog →