@halfagiraf/clawx 0.1.14 → 0.1.16

package/README.md

@@ -6,6 +6,8 @@
 
 Terminal-first coding agent — runs locally with Ollama, DeepSeek, OpenAI, or any OpenAI-compatible endpoint.
 
+> **Beta** — Clawx is under active development. It works well with the providers we've tested (Ollama, DeepSeek, OpenAI, Anthropic) but not every combination has been battle-tested yet. If you hit a bug, [open an issue](https://github.com/stevenmcsorley/clawx/issues) — we fix things fast.
+
 Clawx started because tools like OpenClaw kept getting heavier. Prompts ballooned, context windows filled up, and local models choked. We wanted the good parts — the tool-calling loop, the terminal UI, the coding tools — without the bloat. So we built something lean on top of the open-source [pi-coding-agent](https://github.com/badlogic/pi-mono) SDK: an agent that runs local models on modest hardware, hits DeepSeek when you need more muscle, and scales up to frontier models when the task calls for it. No token budget wasted on platform overhead. Just the model, the tools, and your prompt.
 
 > **Fair warning:** Clawx runs with the guardrails off. It will create files, delete files, install packages, and execute shell commands — all without asking you first. That's the point. No confirmation dialogs, no "are you sure?", no waiting around. You give it a task, it gets on with it. This makes it ideal for disposable environments, home labs, Raspberry Pis, VMs, and machines you're happy to let rip. If you're pointing it at a production server with your life's work on it... maybe don't do that. Or do.
@@ -568,11 +570,54 @@ The agent will create files, install dependencies, build, and verify — iterati
 
 ### Remote scaffolding via SSH
 
+Clawx can SSH into other machines on your network and run commands — from installing packages to deploying services. You describe what you want on your desktop; it happens on the remote machine.
+
+**1. Configure an SSH target** in `clawx.json` (in your working directory):
+
+```json
+{
+  "sshTargets": {
+    "pi": {
+      "host": "192.168.1.198",
+      "username": "dev",
+      "privateKeyPath": "~/.ssh/id_ed25519"
+    }
+  }
+}
+```
+
+**2. Run a prompt that references the target:**
+
+```bash
+clawx run "SSH into the pi and run: hostname && uname -a"
+```
+
+**3. Clawx connects and executes:**
+
+```
+[tool] ssh_run target="pi" command="hostname && uname -a"
+  [pi] exit=0 (943ms)
+ubuntu
+Linux ubuntu 6.14.0-1019-raspi aarch64 GNU/Linux
+```
+
+Tested and verified with DeepSeek API → Raspberry Pi 4 (Ubuntu aarch64) over local network.
+
+**More SSH examples:**
+
 ```bash
-# With SSH targets configured in .env or clawx.json
-clawx run "SSH into my Pi and set up a Node.js service that monitors CPU temperature and exposes it as a Prometheus metric on port 9100"
+# Install and start a service on a remote Pi
+clawx run "SSH into the pi, install Node.js, create an Express API with a /hello endpoint, start it on port 3000, and verify it's running with curl"
+
+# Set up monitoring
+clawx run "SSH into the pi and set up a Node.js service that monitors CPU temperature and exposes it as a Prometheus metric on port 9100"
+
+# Deploy to a server
+clawx run "SSH into server, pull the latest code from git, run npm install, and restart the PM2 process"
 ```
 
+You can define multiple targets (pi, server, vm, etc.) and reference them by name in your prompts.
+
 ### Interactive basic REPL
 
 ```bash
@@ -647,6 +692,46 @@ Next time you run `clawx`, the correct `fd` binary will be downloaded automatica
 
 If you set up clawx via `clawx init`, your configured model should appear in `/models`. If it doesn't, check that your `~/.clawx/config` file has the correct `CLAWDEX_PROVIDER`, `CLAWDEX_MODEL`, and `CLAWDEX_API_KEY` values.
 
+### Model doesn't produce tool calls
+
+If the agent responds with text but never creates files or runs commands, your model likely doesn't support **structured tool calling**. It needs to return `tool_calls` objects in the API response, not text like `<tool_call>`. Check the [model compatibility table](#model-compatibility-and-benchmarks) — models marked "Not compatible" won't work with the agent loop.
+
+### Connection errors
+
+```
+[error] Connection error.
+```
+
+This means clawx can't reach the model endpoint. Check:
+- Is Ollama running? (`ollama serve` or check if the service is active)
+- Is the base URL correct? (`http://localhost:11434/v1` for Ollama)
+- Is the model pulled? (`ollama list` to check)
+- For API providers: is your API key valid?
+
+### Reporting bugs
+
+Clawx is in beta — if something breaks, we want to know. [Open an issue](https://github.com/stevenmcsorley/clawx/issues) with:
+
+1. **What you ran** — the command and prompt
+2. **What happened** — error message or unexpected behaviour
+3. **Your setup** — OS, provider, model, clawx version (`clawx --version`)
+4. **Verbose output** — run with `-v` flag for debug logs: `clawx run -v "your prompt"`
+
+### Tested vs untested providers
+
+| Provider | Status |
+|----------|--------|
+| Ollama | Tested on Windows + Linux |
+| DeepSeek API | Tested |
+| OpenAI API | Tested |
+| Anthropic API | Tested |
+| LM Studio | Untested — should work (OpenAI-compatible) |
+| vLLM | Untested — should work (OpenAI-compatible) |
+| llama.cpp server | Tested — tool calling depends on model |
+| Google / Mistral | Untested |
+
+If you test a provider that isn't listed, let us know how it went.
+
 ## License
 
 MIT. Built on the open-source [pi-coding-agent](https://github.com/badlogic/pi-mono) SDK (MIT).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halfagiraf/clawx",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Terminal-first coding agent — runs locally with Ollama, DeepSeek, OpenAI, or any OpenAI-compatible endpoint",
   "type": "module",
   "bin": {