@rmbk/compeek 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 compeek contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# compeek — AI Eyes & Hands for Any Desktop
+
+> A computer use agent framework powered by Claude. Define goals in natural language, point at any software, watch the agent work.
+
+**No APIs. No plugins. No integrations. Just screen and keyboard.**
+
+[Dashboard](https://compeek.rmbk.me) | [Docker Image](https://ghcr.io/uburuntu/compeek) | [npm](https://www.npmjs.com/package/compeek)
+
+## Quick Start
+
+```bash
+# One-line install (Linux/macOS/WSL2)
+curl -fsSL https://compeek.rmbk.me/install.sh | bash
+
+# Or via npx
+npx compeek start --open
+
+# Or docker directly
+docker run -d -p 3001:3000 -p 6081:6080 --shm-size=512m ghcr.io/uburuntu/compeek
+```
+
+The container prints a **connection string** and a **clickable dashboard link** — no manual port entry needed. Check `docker logs compeek-1`.
+
+Open the [dashboard](https://compeek.rmbk.me), paste your Anthropic API key in Settings, and start a workflow.
+
+## What is compeek?
+
+**compeek** (компик + peek) turns Claude into an autonomous desktop agent. It sees any application through screenshots, interacts via mouse and keyboard, and validates its own work — all without requiring any integration with the target software.
+
+- **See** — screenshot any application + zoom into details
+- **Think** — extended thinking for transparent reasoning
+- **Act** — mouse clicks, keyboard input, scrolling
+- **Read** — extract data from document photos (passports, IDs, invoices)
+- **Validate** — self-check by comparing filled forms against expected data
+- **Observe** — real-time dashboard showing what the AI sees and thinks
+
+## Architecture
+
+```
+Browser (React dashboard)          Docker Container
+┌──────────────────────┐          ┌──────────────────────┐
+│  Agent Loop          │          │  Xvfb + Mutter       │
+│  ├─ Anthropic API    │  HTTP    │  ├─ Firefox          │
+│  └─ Tool dispatch ───┼─────────┼─▸ Tool Server :3000  │
+│                      │          │  │  └─ xdotool/scrot │
+│  Session Manager     │          │  ├─ noVNC :6080      │
+│  Settings (API key)  │          │  └─ VNC :5900        │
+└──────────────────────┘          └──────────────────────┘
+```
+
+The agent loop runs **in the browser** — it calls the Anthropic API directly and sends mouse/keyboard commands to Docker containers via HTTP. Each container is a stateless virtual desktop with a lightweight tool server. No backend needed.
+
+## Desktop Modes
+
+Set `DESKTOP_MODE` when starting a container:
+
+| Mode | What starts | Use case |
+|------|-------------|----------|
+| `full` (default) | Xvfb + Mutter + Tint2 + Firefox + target app | QA testing with pre-loaded app |
+| `browser` | Xvfb + Mutter + Firefox | General web browsing agent |
+| `minimal` | Xvfb + Mutter only | Agent launches everything itself |
+| `headless` | Xvfb + tool server only | API-only, bash commands only |
+
+```bash
+npx compeek start --mode browser
+# or
+docker run -d -e DESKTOP_MODE=browser -p 3001:3000 -p 6081:6080 --shm-size=512m ghcr.io/uburuntu/compeek
+```
+
+## Connection Strings
+
+Containers print a base64-encoded config and a dashboard link on startup:
+
+```
+Connection string: eyJuYW1lIj...
+Dashboard link:    https://compeek.rmbk.me/#config=eyJuYW1lIj...
+```
+
+Three ways to connect:
+1. **Click the link** — auto-adds the session
+2. **Paste the string** in the Add Session dialog
+3. **Manual entry** — type host and ports
+
+## CLI
+
+```bash
+npx compeek start          # Pull image, start container, print connection info
+npx compeek start --open   # Same + open dashboard in browser
+npx compeek stop           # Stop all compeek containers
+npx compeek stop 1         # Stop compeek-1
+npx compeek status         # List running containers
+npx compeek logs           # Follow container logs
+npx compeek open           # Open dashboard with auto-connect URL
+```
+
+Flags for `start`: `--name`, `--api-port`, `--vnc-port`, `--mode`, `--no-pull`, `--open`.
+
+## Development
+
+```bash
+npm install
+npm run dev:client         # Vite dev server on :5173
+npm run build              # tsc + vite build
+npm test                   # 19 tests
+docker compose up --build  # 3 containers on ports 3001-3003 / 6081-6083
+```
+
+## Project Structure
+
+```
+compeek/
+├── src/
+│   ├── agent/             # Shared tools, types, prompts
+│   ├── app/               # React dashboard (Vite)
+│   ├── container/         # Express tool server (Docker)
+│   └── lib/               # Logger
+├── bin/compeek.mjs        # CLI (npx compeek)
+├── install.sh             # One-line installer
+├── docker/                # Dockerfile + entrypoint
+├── target-app/            # Demo form application
+└── docker-compose.yml
+```
+
+## Built for
+
+**"Built with Opus 4.6: a Claude Code Hackathon"** by Anthropic (Feb 2026)
+
+## License
+
+MIT

package/bin/compeek.mjs

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+
+// compeek CLI — zero dependencies, Node.js built-ins only
+// Usage: npx compeek [start|stop|status|logs|open]
+
+import { execSync, spawn } from 'node:child_process';
+import http from 'node:http';
+
+const IMAGE = 'ghcr.io/uburuntu/compeek:latest';
+const CONTAINER_PREFIX = 'compeek-';
+const DASHBOARD_URL = 'https://compeek.rmbk.me';
+const HEALTH_TIMEOUT = 30_000;
+const HEALTH_INTERVAL = 1_000;
+
+// ── Helpers ──────────────────────────────────────────────
+
+function run(cmd, opts = {}) {
+  try {
+    return execSync(cmd, { encoding: 'utf-8', stdio: opts.stdio || 'pipe', ...opts }).trim();
+  } catch (e) {
+    if (opts.allowFail) return '';
+    throw e;
+  }
+}
+
+function hasDocker() {
+  try {
+    run('docker info', { allowFail: false });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function listContainers() {
+  const out = run(
+    `docker ps -a --filter "name=^${CONTAINER_PREFIX}" --format "{{.Names}}\\t{{.Status}}\\t{{.Ports}}"`,
+    { allowFail: true },
+  );
+  if (!out) return [];
+  return out.split('\n').map(line => {
+    const [name, ...rest] = line.split('\t');
+    return { name, status: rest[0] || '', ports: rest[1] || '' };
+  });
+}
+
+function findNextPorts() {
+  const containers = listContainers();
+  const usedApi = new Set();
+  const usedVnc = new Set();
+  for (const c of containers) {
+    const apiMatch = c.ports.match(/0\.0\.0\.0:(\d+)->3000/);
+    const vncMatch = c.ports.match(/0\.0\.0\.0:(\d+)->6080/);
+    if (apiMatch) usedApi.add(parseInt(apiMatch[1]));
+    if (vncMatch) usedVnc.add(parseInt(vncMatch[1]));
+  }
+  let apiPort = 3001;
+  while (usedApi.has(apiPort)) apiPort++;
+  let vncPort = 6081;
+  while (usedVnc.has(vncPort)) vncPort++;
+  return { apiPort, vncPort };
+}
+
+function findNextName() {
+  const containers = listContainers();
+  let n = 1;
+  const names = new Set(containers.map(c => c.name));
+  while (names.has(`${CONTAINER_PREFIX}${n}`)) n++;
+  return `${CONTAINER_PREFIX}${n}`;
+}
+
+function waitForHealth(host, port, timeout) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const check = () => {
+      const req = http.get(`http://${host}:${port}/api/health`, { timeout: 2000 }, (res) => {
+        let body = '';
+        res.on('data', d => body += d);
+        res.on('end', () => {
+          try {
+            const data = JSON.parse(body);
+            if (data.status === 'ok') return resolve(data);
+          } catch { /* retry */ }
+          retry();
+        });
+      });
+      req.on('error', retry);
+      req.on('timeout', () => { req.destroy(); retry(); });
+    };
+    const retry = () => {
+      if (Date.now() - start > timeout) return reject(new Error('Health check timed out'));
+      setTimeout(check, HEALTH_INTERVAL);
+    };
+    check();
+  });
+}
+
+function buildConnectionString(name, apiHost, apiPort, vncHost, vncPort) {
+  const config = JSON.stringify({ name, type: 'compeek', apiHost, apiPort, vncHost, vncPort });
+  return Buffer.from(config).toString('base64');
+}
+
+function openUrl(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start'
+    : 'xdg-open';
+  try {
+    execSync(`${cmd} "${url}"`, { stdio: 'ignore' });
+  } catch {
+    console.log(`  Open manually: ${url}`);
+  }
+}
+
+// ── Commands ─────────────────────────────────────────────
+
+async function cmdStart(args) {
+  if (!hasDocker()) {
+    console.error('Docker is not available. Install Docker first: https://docs.docker.com/get-docker/');
+    process.exit(1);
+  }
+
+  const flags = parseFlags(args);
+  const name = flags.name || findNextName();
+  const { apiPort: defaultApi, vncPort: defaultVnc } = findNextPorts();
+  const apiPort = parseInt(flags['api-port']) || defaultApi;
+  const vncPort = parseInt(flags['vnc-port']) || defaultVnc;
+  const mode = flags.mode || 'full';
+  const sessionName = name.replace(CONTAINER_PREFIX, '').replace(/^(\d+)$/, 'Desktop $1');
+
+  if (!flags['no-pull']) {
+    console.log(`Pulling ${IMAGE}...`);
+    try {
+      run(`docker pull ${IMAGE}`, { stdio: 'inherit' });
+    } catch {
+      console.log('Pull failed, using cached image if available.');
+    }
+  }
+
+  console.log(`Starting ${name} (api:${apiPort}, vnc:${vncPort}, mode:${mode})...`);
+
+  // Remove existing container with same name if stopped
+  run(`docker rm -f ${name}`, { allowFail: true });
+
+  run([
+    'docker run -d',
+    `--name ${name}`,
+    `-p ${apiPort}:3000`,
+    `-p ${vncPort}:6080`,
+    `--shm-size=512m`,
+    `-e DISPLAY=:1`,
+    `-e DESKTOP_MODE=${mode}`,
+    `-e COMPEEK_SESSION_NAME=${sessionName}`,
+    `--security-opt seccomp=unconfined`,
+    IMAGE,
+  ].join(' '));
+
+  console.log('Waiting for container to be ready...');
+
+  try {
+    await waitForHealth('localhost', apiPort, HEALTH_TIMEOUT);
+    console.log('Container is ready.');
+  } catch {
+    console.error('Container did not become healthy. Check logs: npx compeek logs');
+    process.exit(1);
+  }
+
+  const connStr = buildConnectionString(sessionName, 'localhost', apiPort, 'localhost', vncPort);
+
+  console.log('');
+  console.log('=========================================');
+  console.log(`  ${name}`);
+  console.log('=========================================');
+  console.log(`  Tool API : http://localhost:${apiPort}`);
+  if (mode !== 'headless') {
+    console.log(`  noVNC    : http://localhost:${vncPort}`);
+  }
+  console.log('');
+  console.log('  Connection string:');
+  console.log(`  ${connStr}`);
+  console.log('');
+  console.log('  Dashboard link:');
+  console.log(`  ${DASHBOARD_URL}/#config=${connStr}`);
+  console.log('=========================================');
+
+  if (flags.open) {
+    openUrl(`${DASHBOARD_URL}/#config=${connStr}`);
+  }
+}
+
+function cmdStop(args) {
+  const target = args[0];
+  if (target) {
+    const name = target.startsWith(CONTAINER_PREFIX) ? target : `${CONTAINER_PREFIX}${target}`;
+    console.log(`Stopping ${name}...`);
+    run(`docker rm -f ${name}`, { allowFail: true, stdio: 'inherit' });
+  } else {
+    const containers = listContainers();
+    if (containers.length === 0) {
+      console.log('No compeek containers running.');
+      return;
+    }
+    for (const c of containers) {
+      console.log(`Stopping ${c.name}...`);
+      run(`docker rm -f ${c.name}`, { allowFail: true });
+    }
+    console.log(`Stopped ${containers.length} container(s).`);
+  }
+}
+
+function cmdStatus() {
+  const containers = listContainers();
+  if (containers.length === 0) {
+    console.log('No compeek containers found.');
+    return;
+  }
+  console.log('NAME\t\t\tSTATUS\t\t\t\tPORTS');
+  console.log('─'.repeat(80));
+  for (const c of containers) {
+    console.log(`${c.name}\t\t${c.status}\t\t${c.ports}`);
+  }
+}
+
+function cmdLogs(args) {
+  const target = args[0];
+  let name;
+  if (target) {
+    name = target.startsWith(CONTAINER_PREFIX) ? target : `${CONTAINER_PREFIX}${target}`;
+  } else {
+    const containers = listContainers();
+    if (containers.length === 0) {
+      console.error('No compeek containers found.');
+      process.exit(1);
+    }
+    name = containers[0].name;
+  }
+  const child = spawn('docker', ['logs', '-f', '--tail', '50', name], { stdio: 'inherit' });
+  child.on('exit', code => process.exit(code || 0));
+}
+
+function cmdOpen(args) {
+  const target = args[0];
+  let name;
+  if (target) {
+    name = target.startsWith(CONTAINER_PREFIX) ? target : `${CONTAINER_PREFIX}${target}`;
+  } else {
+    const containers = listContainers().filter(c => c.status.startsWith('Up'));
+    if (containers.length === 0) {
+      console.error('No running compeek containers found.');
+      process.exit(1);
+    }
+    name = containers[0].name;
+  }
+
+  // Extract ports from docker inspect
+  const inspect = run(`docker inspect --format '{{json .NetworkSettings.Ports}}' ${name}`, { allowFail: true });
+  if (!inspect) {
+    console.error(`Container ${name} not found.`);
+    process.exit(1);
+  }
+
+  try {
+    const ports = JSON.parse(inspect);
+    const apiBinding = ports['3000/tcp']?.[0];
+    const vncBinding = ports['6080/tcp']?.[0];
+    const apiPort = apiBinding ? parseInt(apiBinding.HostPort) : 3001;
+    const vncPort = vncBinding ? parseInt(vncBinding.HostPort) : 6081;
+    const sessionName = name.replace(CONTAINER_PREFIX, '').replace(/^(\d+)$/, 'Desktop $1');
+
+    const connStr = buildConnectionString(sessionName, 'localhost', apiPort, 'localhost', vncPort);
+    const url = `${DASHBOARD_URL}/#config=${connStr}`;
+    console.log(`Opening ${url}`);
+    openUrl(url);
+  } catch (e) {
+    console.error('Failed to read container ports:', e.message);
+    process.exit(1);
+  }
+}
+
+// ── Flag parsing ─────────────────────────────────────────
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      if (key === 'open' || key === 'no-pull') {
+        flags[key] = true;
+      } else if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+        flags[key] = args[++i];
+      }
+    }
+  }
+  return flags;
+}
+
+// ── Main ─────────────────────────────────────────────────
+
+const [command = 'start', ...rest] = process.argv.slice(2);
+
+switch (command) {
+  case 'start':
+    cmdStart(rest);
+    break;
+  case 'stop':
+    cmdStop(rest);
+    break;
+  case 'status':
+    cmdStatus();
+    break;
+  case 'logs':
+    cmdLogs(rest);
+    break;
+  case 'open':
+    cmdOpen(rest);
+    break;
+  case '--help':
+  case '-h':
+  case 'help':
+    console.log(`
+compeek — AI desktop agent
+
+Usage: npx compeek [command] [options]
+
+Commands:
+  start       Start a new container (default)
+  stop [name] Stop one or all compeek containers
+  status      List running containers
+  logs [name] Follow container logs
+  open [name] Open dashboard with auto-connect URL
+
+Start options:
+  --name <n>       Container name (default: compeek-N)
+  --api-port <p>   Host port for tool API (default: auto)
+  --vnc-port <p>   Host port for noVNC (default: auto)
+  --mode <m>       Desktop mode: full|browser|minimal|headless
+  --no-pull        Skip docker pull
+  --open           Open dashboard after start
+`);
+    break;
+  default:
+    console.error(`Unknown command: ${command}. Run "npx compeek --help" for usage.`);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@rmbk/compeek",
+  "version": "0.2.0",
+  "description": "AI eyes and hands for any desktop application — a general-purpose computer use agent framework powered by Claude Opus 4.6",
+  "license": "MIT",
+  "author": "rmbk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uburuntu/compeek.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "computer-use",
+    "ai-agent",
+    "claude",
+    "opus",
+    "anthropic",
+    "desktop-automation",
+    "rpa",
+    "vision"
+  ],
+  "type": "module",
+  "bin": {
+    "compeek": "bin/compeek.mjs"
+  },
+  "files": [
+    "bin/"
+  ],
+  "scripts": {
+    "dev:client": "vite",
+    "build": "tsc && vite build",
+    "build:server": "tsc",
+    "build:client": "vite build",
+    "start": "node dist/container/server.js",
+    "docker:build": "docker build -f docker/Dockerfile -t compeek .",
+    "docker:run": "docker run -p 3000:3000 -p 6080:6080 -p 5900:5900 --shm-size=512m -it compeek",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.0",
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.20",
+    "jsdom": "^28.0.0",
+    "postcss": "^8.4.49",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^3.4.15",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vitest": "^4.0.18"
+  }
+}