nex-code 0.3.22 → 0.3.23

package/README.md

@@ -22,7 +22,7 @@
   <img src="https://img.shields.io/badge/Ollama_Cloud-supported-brightgreen.svg" alt="Ollama Cloud: supported">
   <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node >= 18">
   <img src="https://img.shields.io/badge/dependencies-2-green.svg" alt="Dependencies: 2">
-  <img src="https://img.shields.io/badge/tests-1855-blue.svg" alt="Tests: 1855">
+  <img src="https://img.shields.io/badge/tests-1944-blue.svg" alt="Tests: 1944">
 </p>
 
 ---
@@ -81,6 +81,9 @@ npm update -g nex-code
 | **Browser agent (headless)** | ✅ Playwright-based | ❌ | ⚠️ Experimental | ❌ |
 | **Grounded web search** | ✅ Perplexity/DDG | ❌ | ✅ Google grounded | ❌ |
 | **GitHub Actions tools** | ✅ native | ❌ | ❌ | ❌ |
+| **SSH server management** | ✅ native (AlmaLinux/macOS) | ❌ | ❌ | ❌ |
+| **Docker tools** | ✅ local + remote via SSH | ❌ | ❌ | ❌ |
+| **Deploy tool (rsync)** | ✅ named configs | ❌ | ❌ | ❌ |
 | **Open-source** | ✅ MIT | ❌ | ✅ Apache 2.0 | ✅ |
 | **Runtime dependencies** | **2** (axios, dotenv) | Many | Many | Heavy (Python) |
 | **Startup time** | **~100ms** | ~400ms | ~300ms | Slow |
@@ -154,6 +157,7 @@ DEFAULT_MODEL=qwen3-coder:480b # Active model on startup
 FALLBACK_CHAIN=anthropic,openai # Providers tried on failure (comma-separated)
 NEX_STALE_WARN_MS=60000        # Warn if no tokens received for N ms (default: 60000)
 NEX_STALE_ABORT_MS=120000      # Abort and retry stream after N ms of silence (default: 120000)
+NEX_LANGUAGE=auto              # Response language: "auto" (mirrors user's language, default) or e.g. "English", "Deutsch"
 ```
 
 ### Verify
@@ -319,6 +323,17 @@ Type `/` to see inline suggestions as you type. Tab completion is supported for
 | `/remember <text>` | Save a memory (persists across sessions) |
 | `/forget <key>` | Delete a memory |
 | `/memory` | Show all memories |
+| `/brain add <name>` | Add a document to the knowledge base |
+| `/brain list` | List all brain documents |
+| `/brain search <query>` | Search the knowledge base |
+| `/brain show <name>` | Show a brain document |
+| `/brain remove <name>` | Remove a brain document |
+| `/brain rebuild` | Rebuild keyword index |
+| `/brain embed` | Build/rebuild embedding index |
+| `/brain status` | Show brain status (docs, index, embeddings) |
+| `/brain review` | Review pending brain changes (git diff) |
+| `/brain undo` | Undo last brain write |
+| `/learn` | Reflect on session and auto-update memory + NEX.md |
 | `/permissions` | Show tool permissions |
 | `/allow <tool>` | Auto-allow a tool |
 | `/deny <tool>` | Block a tool |
@@ -335,14 +350,16 @@ Type `/` to see inline suggestions as you type. Tab completion is supported for
 | `/redo` | Redo last undone change |
 | `/history` | Show file change history |
 | `/review [file]` | Code review on current diff or a specific file |
+| `/k8s [user@host]` | Kubernetes overview: namespaces + pod health (remote via SSH optional) |
 | `/exit` | Quit |
 
 ---
 
 ## Tools
 
-The agent has 17 built-in tools:
+The agent has 39 built-in tools:
 
+### Core & File System
 | Tool | Description |
 |------|-------------|
 | `bash` | Execute shell commands (90s timeout, 5MB buffer) |
@@ -354,21 +371,67 @@ The agent has 17 built-in tools:
 | `search_files` | Regex search across files (like grep) |
 | `glob` | Fast file search by name/extension pattern |
 | `grep` | Content search with regex and line numbers |
+
+### Git & Web
+| Tool | Description |
+|------|-------------|
 | `git_status` | Git working tree status |
 | `git_diff` | Git diff with optional path filter |
 | `git_log` | Git commit history with configurable count |
 | `web_fetch` | Fetch content from a URL |
 | `web_search` | Grounded search via Perplexity (if `PERPLEXITY_API_KEY` set) or DuckDuckGo |
+
+### Interaction & Agents
+| Tool | Description |
+|------|-------------|
 | `ask_user` | Ask the user a question and wait for input |
 | `task_list` | Create and manage task lists for multi-step operations |
 | `spawn_agents` | Run parallel sub-agents with auto model routing |
+| `switch_model` | Switch active model mid-conversation |
+
+### Browser (optional — requires Playwright)
+| Tool | Description |
+|------|-------------|
 | `browser_open` | Open URL in headless browser, return text + links (JS-heavy pages) |
 | `browser_screenshot` | Screenshot a URL → saved file + vision-ready path |
 | `browser_click` | Click element by CSS selector or visible text |
 | `browser_fill` | Fill form field and optionally submit |
+
+### GitHub Actions
+| Tool | Description |
+|------|-------------|
 | `gh_run_list` | List GitHub Actions workflow runs |
 | `gh_run_view` | View run details and step logs |
 | `gh_workflow_trigger` | Trigger a workflow dispatch event |
+| `k8s_pods` | List Kubernetes pods (local kubectl or remote via SSH) |
+| `k8s_logs` | Fetch pod logs with `--tail` / `--since` filtering |
+| `k8s_exec` | Run a command inside a pod (with confirmation) |
+| `k8s_apply` | Apply a manifest file — `dry_run` mode supported (with confirmation) |
+| `k8s_rollout` | Rollout status / restart / history / undo for deployments |
+
+### SSH & Server Management
+Requires `.nex/servers.json` — run `/init` to configure. See [Server Management](#server-management).
+
+| Tool | Description |
+|------|-------------|
+| `ssh_exec` | Execute a command on a remote server via SSH |
+| `ssh_upload` | Upload a file or directory via SCP |
+| `ssh_download` | Download a file or directory via SCP |
+| `service_manage` | Start/stop/restart/reload/enable/disable a systemd service (local or remote) |
+| `service_logs` | Fetch journalctl logs (local or remote, with `--since` support) |
+
+### Docker
+| Tool | Description |
+|------|-------------|
+| `container_list` | List Docker containers (local or remote via SSH) |
+| `container_logs` | Fetch Docker container logs (`--tail`, `--since`) |
+| `container_exec` | Execute a command inside a running container |
+| `container_manage` | Start/stop/restart/remove/inspect a container |
+
+### Deploy
+| Tool | Description |
+|------|-------------|
+| `deploy` | rsync files to a remote server + optional post-deploy script. Supports named configs from `.nex/deploy.json`. |
 
 **Interactive commands** (vim, top, htop, ssh, tmux, fzf, etc.) are automatically detected and spawned with full TTY passthrough — no separate handling required.
 
@@ -378,6 +441,87 @@ Additional tools can be added via [MCP servers](#mcp) or [Skills](#skills).
 
 ---
 
+## Server Management
+
+nex-code has first-class support for remote server management via SSH, optimised for **AlmaLinux 9** and **macOS**.
+
+### Setup
+
+Run `/init` inside nex-code to interactively configure your servers:
+
+```
+> /init
+```
+
+Or create `.nex/servers.json` manually:
+
+```json
+{
+  "prod": {
+    "host": "94.130.37.43",
+    "user": "jarvis",
+    "port": 22,
+    "key": "~/.ssh/id_rsa",
+    "os": "almalinux9",
+    "sudo": true
+  },
+  "macbook": {
+    "host": "192.168.1.10",
+    "user": "lukas",
+    "os": "macos"
+  }
+}
+```
+
+**OS values**: `almalinux9`, `almalinux8`, `ubuntu`, `debian`, `macos`
+
+When `.nex/servers.json` exists, the agent automatically receives OS-aware context:
+- **AlmaLinux 9**: `dnf`, `firewalld`, `systemctl`, SELinux hints
+- **macOS**: `brew`, `launchctl`, `log show` instead of `journalctl`
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/servers` | List all configured server profiles |
+| `/servers ping` | Check SSH connectivity for all servers in parallel |
+| `/servers ping <name>` | Check a specific server |
+| `/docker` | List running containers across all servers + local |
+| `/docker -a` | Include stopped containers |
+| `/deploy` | List all named deploy configs |
+| `/deploy <name>` | Run a named deploy (with confirmation) |
+| `/deploy <name> --dry-run` | Preview without syncing |
+| `/init` | Interactive wizard: create `.nex/servers.json` |
+| `/init deploy` | Interactive wizard: create `.nex/deploy.json` |
+
+### Named Deploy Configs
+
+Create `.nex/deploy.json` (or use `/init deploy`):
+
+```json
+{
+  "prod": {
+    "server": "prod",
+    "local_path": "dist/",
+    "remote_path": "/var/www/app",
+    "exclude": ["node_modules", ".env"],
+    "deploy_script": "systemctl restart gunicorn"
+  }
+}
+```
+
+Then deploy with:
+```
+> /deploy prod
+```
+
+Or from within a conversation:
+```
+deploy the latest build to prod
+```
+
+---
+
 ## Features
 
 ### Compact Output
@@ -401,6 +545,10 @@ When the model runs tools but produces no visible text, an automatic nudge force
 ### Response Quality
 The system prompt enforces substantive responses: the model always presents findings as formatted text after using tools (users only see 1-line tool summaries). Responses use markdown with headers, bullet lists, and code blocks. The model states its approach before non-trivial tasks and summarizes results after completing work.
 
+**Language:** By default (`NEX_LANGUAGE=auto`), the model mirrors the language of the user's message — write in German, get a German response; write in English, get an English response. Set `NEX_LANGUAGE=English` (or any language) to force a fixed response language.
+
+**Code examples:** The model is instructed to always show actual, working code — never pseudocode or placeholder snippets.
+
 ### Performance
 - **Asynchronous I/O**: The entire CLI is built on non-blocking I/O. File reads, writes, and git operations never block the main thread, keeping the UI responsive even during heavy tasks.
 - **Fast Startup**: Pre-bundled with `esbuild` to minimize module loading overhead, achieving sub-100ms startup times.
@@ -470,6 +618,20 @@ Persistent project memory that survives across sessions:
 
 Also loads `NEX.md` from project root for project-level instructions.
 
+### Brain — Persistent Knowledge Base
+A project-scoped knowledge base stored in `.nex/brain/`. The agent automatically retrieves relevant documents for each query and can write new entries as it discovers useful patterns, decisions, or context:
+```
+/brain add auth-flow         # add a document (prompted for content)
+/brain search "jwt token"    # keyword + semantic search
+/brain list                  # list all documents
+/brain show auth-flow        # display a document
+/brain remove auth-flow      # delete a document
+/brain status                # index health (docs, keywords, embeddings)
+/brain review                # git diff of recent brain writes
+/brain undo                  # undo last brain write
+```
+The agent uses the `brain_write` tool to save discoveries automatically. All writes are tracked in git so you can review, revert, or audit what the agent has stored.
+
 ### Plan Mode
 Analyze before executing — the agent explores the codebase with read-only tools, produces a structured plan, then you approve before any changes are made:
 ```
@@ -593,8 +755,8 @@ Four features that make Nex Code significantly more reliable with open-source mo
 
 **Tool Tiers** — Dynamically reduces the tool set based on model capability:
 - **essential** (5 tools): bash, read_file, write_file, edit_file, list_directory
-- **standard** (13 tools): + search_files, glob, grep, ask_user, git_status, git_diff, git_log, task_list
-- **full** (17 tools): all tools
+- **standard** (21 tools): + search_files, glob, grep, ask_user, git_status, git_diff, git_log, task_list, ssh_exec, service_manage, service_logs, container_list, container_logs, container_exec, container_manage, deploy
+- **full** (33 tools): all tools
 
 Models are auto-classified, or override per-model in `.nex/config.json`:
 ```json
@@ -719,7 +881,7 @@ Or place executable scripts in `.nex/hooks/`:
 ```
 bin/nex-code.js          # Entrypoint (shebang, .env, startREPL)
 cli/
-├── index.js             # REPL + ~38 slash commands + history persistence + AbortController
+├── index.js             # REPL + ~39 slash commands + history persistence + AbortController
 ├── agent.js             # Agentic loop + conversation state + compact output + résumé + abort handling
 ├── providers/           # Multi-provider abstraction
 │   ├── base.js          # Abstract provider interface