@swarmai/local-agent 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+# SwarmAI Local Agent
+
+CLI agent that runs on your computer (Windows/Mac/Linux) and connects to a SwarmAI server, giving the agentic AI direct access to your device — shell commands, file system, screenshots, clipboard, MCP tools, and CLI AI sessions.
+
+## Architecture
+
+```
+Local Agent CLI  →  WebSocket (wss://{server}/local-agent)  →  SwarmAI Backend
+                    ├── systemInfo         (OS, CPU, RAM, disk)
+                    ├── screenshot         (desktop capture → upload)
+                    ├── shell              (execute commands, streaming output)
+                    ├── fileRead / fileList (browse & read files)
+                    ├── fileTransfer       (upload/download files)
+                    ├── clipboard          (read/write system clipboard)
+                    ├── capture            (camera/microphone, opt-in only)
+                    ├── cliSession         (claude/gemini/opencode CLI)
+                    ├── mcp               (MCP server tool execution)
+                    ├── aiChat            (proxy to local Ollama/LM Studio)
+                    └── kill              (terminate running command)
+```
+
+## Setup
+
+### Prerequisites
+- Node.js 16+
+
+### Install & Login
+
+```bash
+cd local-agent
+npm install
+
+# Authenticate with SwarmAI server (opens browser for OAuth)
+node index.js login --api https://agents.northpeak.app --name "My Laptop"
+
+# Start the agent
+node index.js start
+```
+
+### Global Install (optional)
+
+```bash
+npm install -g .
+swarmai-agent login --api https://agents.northpeak.app
+swarmai-agent start
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `login` | Authenticate this device with SwarmAI server |
+| `start` | Connect and begin listening for commands |
+| `startup enable` | Auto-start on system boot |
+| `startup disable` | Remove auto-start |
+| `startup status` | Check auto-start status |
+| `status` | Show connection status |
+
+### Login Options
+
+```bash
+swarmai-agent login \
+  --api <url>      # Server URL (default: https://agents.northpeak.app)
+  --name <name>    # Device name (default: hostname)
+```
+
+## Device Commands (AI Tools)
+
+When connected, the SwarmAI agentic AI can execute these commands on your device:
+
+| Command | Description | Security |
+|---------|-------------|----------|
+| `systemInfo` | OS, CPU, RAM, disk, network info | Always allowed |
+| `notification` | Show desktop notification | Always allowed |
+| `screenshot` | Capture desktop screenshot | Always allowed |
+| `shell` | Execute shell commands (streaming) | Blocklist filtered |
+| `fileRead` | Read file contents | Path-restricted (configurable) |
+| `fileList` | List directory contents | Path-restricted (configurable) |
+| `fileTransfer` | Upload/download files to/from server | Always allowed |
+| `clipboard` | Read/write system clipboard | Requires approval |
+| `capture` | Camera/microphone access | Opt-in only (`allowCapture`) |
+| `cliSession` | Run Claude/Gemini/OpenCode CLI | Requires approval |
+| `mcp` | Execute MCP server tools | Always allowed |
+| `aiChat` | Chat with local AI (Ollama, LM Studio) | Always allowed |
+| `kill` | Terminate a running command | Always allowed |
+
+## MCP Server Integration
+
+The agent can spawn and manage local MCP servers. Built-in recipes:
+
+| Recipe | Description |
+|--------|-------------|
+| `playwright` | Browser automation via Playwright |
+| `filesystem` | Local filesystem access |
+| `sqlite` | SQLite database operations |
+| `git` | Git repository operations |
+| `docker` | Docker container management |
+
+Custom MCP servers can be configured via the SwarmAI dashboard.
+
+## Security
+
+### Configuration
+
+Security settings in `~/.swarmai/config.json`:
+
+```json
+{
+  "security": {
+    "shellBlocklist": [],
+    "fileRootPaths": [],
+    "requireApprovalFor": ["cliSession", "clipboard"],
+    "allowCapture": false
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `shellBlocklist` | `[]` | Additional blocked shell patterns (on top of built-in: `rm -rf /`, `format`, `mkfs`, etc.) |
+| `fileRootPaths` | `[]` | Restrict file access to these paths. Empty = allow all. |
+| `requireApprovalFor` | `["cliSession", "clipboard"]` | Commands that are blocked unless user opts in |
+| `allowCapture` | `false` | Camera/mic access (must explicitly enable) |
+
+### Workspace
+
+The agent manages a local workspace for file operations:
+
+```
+~/SwarmAI/          (Linux/Mac)
+C:/SwarmAI/         (Windows)
+├── temp/           # Temporary files (auto-cleanup: 24h)
+├── downloads/      # Downloaded files (auto-cleanup: 7d)
+└── workspace/      # Persistent working directory
+```
+
+Configurable in `~/.swarmai/config.json` under `"workspace"` key.
+
+## Project Structure
+
+```
+local-agent/
+├── index.js                # Entry point (CLI)
+├── package.json
+└── src/
+    ├── cli.js              # Commander.js CLI definitions
+    ├── auth.js             # OAuth browser login flow
+    ├── config.js           # ~/.swarmai/config.json management
+    ├── connection.js       # Socket.io WebSocket client
+    ├── commands.js         # Command handlers (shell, screenshot, etc.)
+    ├── mcpManager.js       # MCP server lifecycle management
+    ├── toolScanner.js      # Discover local CLI tools
+    ├── aiProviderScanner.js # Detect local AI (Ollama, LM Studio)
+    ├── workspace.js        # Local workspace/file management
+    └── startup.js          # OS auto-start (systemd, launchd, Task Scheduler)
+```
+
+## Backend Integration
+
+The server-side gateway lives at:
+- **Gateway:** `server/services/LocalAgentGateway.cjs`
+- **Routes:** `server/routes/local-agents.cjs`
+- **AI Tools:** `executeOnLocalAgent`, `uploadToTempStorage` (available to agentic AI when a local agent is online)
+
+### WebSocket Events
+
+| Event | Direction | Description |
+|-------|-----------|-------------|
+| `command:execute` | Server → Agent | Execute a command |
+| `command:result` | Agent → Server | Command result (sync) |
+| `command:output` | Agent → Server | Streaming output chunk |
+| `command:async-result` | Agent → Server | Async CLI completion |
+| `agent:heartbeat` | Agent → Server | Health pulse (every 15s) |
+| `agent:capabilities` | Agent → Server | Supported commands + MCP tools |

package/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+/**
+ * SwarmAI Local Agent CLI
+ * Entry point
+ */
+
+const { createCli } = require('./src/cli');
+
+const program = createCli();
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@swarmai/local-agent",
+  "version": "0.1.0",
+  "description": "SwarmAI Local Agent CLI - Connect your device to SwarmAI",
+  "main": "index.js",
+  "bin": {
+    "swarmai-agent": "index.js"
+  },
+  "files": [
+    "index.js",
+    "src/"
+  ],
+  "scripts": {
+    "start": "node index.js start",
+    "login": "node index.js login"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "open": "^8.4.2",
+    "screenshot-desktop": "^1.5.3",
+    "socket.io-client": "^4.7.4"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "keywords": [
+    "swarmai",
+    "local-agent",
+    "cli",
+    "ai-agent",
+    "swarm-intelligence"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swarmai/swarmai.git",
+    "directory": "local-agent"
+  },
+  "homepage": "https://agents.northpeak.app",
+  "license": "MIT"
+}

package/src/agenticChatClaudeMd.js

@@ -0,0 +1,92 @@
+/**
+ * CLAUDE.md Template Builder for Agentic Chat
+ *
+ * Generates workspace CLAUDE.md content for Claude Code CLI
+ * when running with Ollama as the backend provider.
+ *
+ * Pure function — no I/O, easily testable.
+ */
+
+const SENTINEL = '<!-- swarm_agentic_chat_injected -->';
+
+/**
+ * Build CLAUDE.md content for an agenticChat workspace.
+ *
+ * @param {object} options
+ * @param {string} options.profileName - Agent profile name
+ * @param {string} [options.systemPrompt] - Agent personality / instructions
+ * @param {string} [options.model] - Ollama model being used
+ * @param {string} [options.taskContext] - Current task description
+ * @param {string} [options.outputDir] - Absolute path to output directory
+ * @returns {string} CLAUDE.md content
+ */
+function buildAgenticChatClaudeMd(options = {}) {
+  const {
+    profileName = 'SwarmAI Agent',
+    systemPrompt = '',
+    model = 'unknown',
+    taskContext = '',
+    outputDir = './output',
+  } = options;
+
+  const timestamp = new Date().toISOString();
+
+  const sections = [];
+
+  // Header
+  sections.push(`# ${profileName} — Agentic Workspace`);
+  sections.push('');
+  sections.push(SENTINEL);
+  sections.push('');
+  sections.push(`- Agent: ${profileName}`);
+  sections.push(`- Model: ${model}`);
+  sections.push(`- Updated: ${timestamp}`);
+  sections.push('');
+
+  // Agent Instructions
+  if (systemPrompt) {
+    sections.push('## Agent Instructions');
+    sections.push('');
+    sections.push(systemPrompt);
+    sections.push('');
+  }
+
+  // Task Context
+  if (taskContext) {
+    sections.push('## Current Task');
+    sections.push('');
+    sections.push(taskContext);
+    sections.push('');
+  }
+
+  // File Generation Protocol
+  sections.push('## File Generation Protocol');
+  sections.push('');
+  sections.push('When you create or generate any file, you MUST:');
+  sections.push(`1. Save files to the \`${outputDir}\` directory`);
+  sections.push('2. After saving, output a marker on its own line: `[FILE_GENERATED: /absolute/path/to/file]`');
+  sections.push('3. This marker is required for the system to detect and deliver generated files');
+  sections.push('4. Always use absolute paths in the marker');
+  sections.push('');
+
+  // Output Rules
+  sections.push('## Output Rules');
+  sections.push('');
+  sections.push('- Be concise and direct in your responses');
+  sections.push('- If the task requires creating files, follow the File Generation Protocol above');
+  sections.push('- If you encounter an error, explain it clearly and suggest a fix');
+  sections.push('- Do not ask clarifying questions — work with the information given');
+  sections.push('- You have full filesystem access within this workspace');
+  sections.push('');
+
+  return sections.join('\n');
+}
+
+/**
+ * Check if a CLAUDE.md content was generated by agenticChat
+ */
+function isAgenticChatClaudeMd(content) {
+  return typeof content === 'string' && content.includes(SENTINEL);
+}
+
+module.exports = { buildAgenticChatClaudeMd, isAgenticChatClaudeMd, SENTINEL };