Technical Briefing: clawdcursor

Overview

clawdcursor is a desktop automation server that gives AI agents eyes, hands, and ground-truth verification on Windows, macOS, and Linux. It wraps the desktop as 42 callable tools (mouse, keyboard, screen, windows, browser) that any function-calling AI model can use. The repository is model-agnostic and works with Claude, GPT, Gemini, Llama, or any compatible model, with free operation using local models.

Key metrics: 234 files total, 140 in src/, 163 code files analyzed. Primary language: TypeScript (145 files). Package manager: npm. CI: GitHub Actions.

Architecture & Entry Points

Execution starts from several entry points. The primary is run at src/pipeline/index.ts:104, which reaches 171 functions and is called by nothing else in the repo. Other entry points include:

  • start at src/native-helper.ts:115 (16 functions reached)
  • execute at src/pipeline/agent/compound.ts:84 (103 functions reached, called from 1 place)
  • executeStrategy at src/pipeline/index.ts:265 (159 functions reached)
  • runOneSubtask at src/pipeline/index.ts:207 (161 functions reached)

The v2 architecture (--v2 flag) introduces a PlatformAdapter abstraction with platform-specific code in src/v2/platform/{macos,windows,linux}.ts, replacing 142+ scattered if (IS_MAC) branches across 34 files.

What the Code Touches Outside Itself

  • 39 functions read or write files
  • 3 functions call a model for inference
  • 1 function makes an outbound network call
  • 2 functions perform cryptographic or secret-generating operations

Traced paths from entry points to external effects:

  • run → recognizeScreen [filesystem via fs.writeFileSync]
  • execute → screenshot [filesystem via fs.readFileSync]
  • main → runAsyncDebugWriteTests [filesystem via fs.writeFileSync]

Code Health & Measured Findings

Static analysis identified 87 issues across 14 high, 73 medium, 0 low severity:

High severity findings:

  • Import cycle member x8: src/providers.ts, src/credentials.ts, src/pipeline/playbooks/index.ts participate in circular imports. Fix: extract shared types, invert dependency, or defer import.
  • Oversized file x13: src/providers.ts (684 lines), src/llm-client.ts, src/native-desktop.ts. Fix: split into cohesive units by responsibility.
  • High branching density x22: src/accessibility.ts, src/llm-client.ts, src/browser-config.ts (178 branch points over 548 lines). Fix: decompose decision-heavy logic.
  • Deep nesting x6: src/pipeline/agent/prompt.ts, src/a11y-reasoner.ts, src/browser-layer.ts (max indentation depth 8). Fix: flatten with early returns/guard clauses.
  • Hub module x8: src/v2/platform/types.ts, src/providers.ts, src/accessibility.ts (18 modules depend on these). Fix: keep stable and small; move volatile logic out.
  • Duplicated code blocks: 440 repeated 6-line blocks across 31 files including perf/perf-test.ts, src/ai-brain.ts, scripts/mac/find-element.sh. Fix: extract shared helpers.

Code Health Audit (7 findings, 0 critical):

  • Declare least-privilege permissions for GITHUB_TOKEN in .github/workflows/cross-platform.yml
  • Enable Dependabot or Renovate (currently unconfigured)
  • Gate pull requests on dependency vulnerability scan
  • Set persist-credentials: false on checkout
  • Review install lifecycle script and disable scripts in CI
  • Set timeout-minutes on workflow jobs
  • Add repository convention files (.editorconfig, .gitattributes, formatter config)

Relevant Module Graph

Most connected modules (Ca = importers, Ce = imports):

  • src/agent Ca 2 Ce 26 instability 0.93
  • src/providers Ca 17 Ce 1 instability 0.06 (IN CYCLE)
  • src/v2/platform/types Ca 18 Ce 0 instability 0
  • src/accessibility Ca 16 Ce 1 instability 0.06
  • src/tools/types Ca 16 Ce 0 instability 0
  • src/types Ca 16 Ce 0 instability 0
  • src/native-desktop Ca 12 Ce 3 instability 0.2
  • src/tools/index Ca 3 Ce 12 instability 0.8 (IN CYCLE)

Projects & Hygiene

Three internal projects: src (140 files), scripts (25 files), perf (9 files). Repository hygiene: tests present, CI present, Dockerfile absent, license present, lockfile present, no committed secrets.

Setup & Running

Installation commands are provided via the project website (clawdcursor.com), with platform-specific setup scripts. Configuration requires environment variables for AI provider selection and API keys. First run auto-detects the AI provider from environment variables.

Bottom Line

This repository provides a functional desktop automation layer for AI agents with reasonable OS coverage and model agnosticism. The v2 architecture refactor addresses long-standing code quality issues around platform branching and cognitive load. However, the import cycles, duplicated code blocks, and absence of dependency vulnerability scanning in CI represent tangible risks for maintenance and security. Teams requiring stable, extensible desktop automation should evaluate the v2 path while accounting for the measured code health findings.

Analysis based on deterministic static analysis of 163 code files. Findings reflect measured code patterns, not opinion.