Claude Code Control

Programmatically control Claude Code in visible macOS Terminal windows via AppleScript for command input, screenshots, session logging, and terminal management.

Security Scan

The skill largely matches its stated purpose (driving Claude Code in a visible Terminal window), but there are multiple inconsistencies and extra capabilities (unused network-capable dependency, multiple different implementations that execute shell commands, references to author-local paths, missing/odd package metadata) that merit caution before installation.

Purpose & Capability

The name/description (AppleScript-driven visible Terminal control of Claude Code) matches the code in index.js which uses osascript, screencapture, and System Events. However the repo also contains multiple alternate implementations (index-old.js, index-shell.js, index-v2.js) that run claude as a subprocess and execute arbitrary shell commands (execSync/spawn). package-lock.json/package.json list @anthropic-ai/sdk and other network-capable packages even though the runtime files shown don't import or use that SDK. package.json claims a CLI entry ('cli.js') not present in the file list shown. These extra dependencies and missing/mismatched metadata are disproportionate or unexplained for the stated, local-only Terminal control purpose.

Instruction Scope

SKILL.md accurately describes the primary behavior (open Terminal.app, type commands, capture screenshots, save JSON logs) and the code follows that: it types into Terminal, sends Enter, takes targeted screenshots, writes session logs and files under /tmp or user-provided paths. The instructions and code do not appear to read or transmit data to external network endpoints. That said, many files (examples and tests) demonstrate running arbitrary shell commands (ls, cat, pytest, writing files), so the agent will be able to execute arbitrary commands in whatever project path it's given — which is expected but a high-capability action the user should be aware of.

Install Mechanism

There is no remote download/install step in the registry metadata (instruction-only install), and nothing in the files indicates downloading arbitrary code at runtime. package-lock.json is included (bundled dependencies), but there are no install scripts that fetch code from untrusted URLs. This is lower risk than a 'download and execute' installer, but bundling node dependencies (including those that enable network calls) increases the code surface that will run on install/use.

Credentials

The skill declares no required env vars or credentials, which aligns with a local Terminal automation tool. However package-lock/package.json include @anthropic-ai/sdk and network-related packages (node-fetch, form-data, etc.) that are not reflected in SKILL.md and aren't required or explained—these normally imply remote API usage that often requires API keys. The presence of those dependencies without declared credentials is an unexplained mismatch and raises the risk that future or hidden code paths could make network calls or require API keys.

Persistence & Privilege

The skill is not marked always:true and does not declare elevated platform privileges. However it requires Accessibility permissions for Terminal.app and System Events (as described in SKILL.md) so it can (when granted) type into apps and capture screenshots. Combined with autonomous invocation being allowed by default, this capability increases blast radius — an autonomously-invoked skill that can type arbitrary commands and take screenshots could do significant local actions if misused. This is expected for its purpose but important to understand.

What to consider before installing

What to check before installing or running this skill: - Trust and provenance: The code can type arbitrary commands into your Terminal, execute shell commands, create and read files in the project path, and capture screenshots. Only install if you trust the author/source. The registry metadata lacks a homepage and the source is 'unknown'. - Accessibility and screenshots: You will need to grant Accessibility permissions to Terminal.app and Script Editor (System Settings → Privacy & Security → Accessibility). Granting these allows the skill to simulate keystrokes and capture parts of your screen — treat this like giving a program control of your keyboard and screen. - Review package.json / dependencies locally: package-lock.json shows a dependency on @anthropic-ai/sdk and other network-capable modules, but SKILL.md and the shown code do not use an external API or request API keys. This mismatch is unexplained — open package.json and the code to confirm there are no hidden network calls before running. If you do not plan to use any cloud features, consider removing unused dependencies. - Limit workspace and permissions: Run the skill in a limited test account or VM first; point it at a directory you control (not your home dir or production codebase). The examples and tests run arbitrary commands (pytest, cat, mkdir, etc.), so avoid pointing it at sensitive paths. - Check for missing/odd metadata: package.json appears to reference a 'cli.js' binary that is not in the manifest shown; that inconsistency suggests the package may not have been packaged/tested correctly — inspect package.json and the top-level files before using. - If you need autonomous agent use: Be cautious. Autonomous invocation plus the ability to execute shell commands and take screenshots can lead to wide impact. If you must enable autonomous runs, restrict the skill's allowed inputs and workspace and monitor actions closely. If you want, I can (1) list the exact files/lines that reference network or unusual behavior, (2) inspect package.json for the missing CLI entry and dependencies, or (3) suggest a minimal, safer configuration (remove network deps, or switch to a pure-AppleScript-only implementation) you could ask the publisher to provide.

Control Claude Code programmatically through visible Terminal.app windows on macOS.

How It Works

Uses AppleScript to:

1. Open Terminal.app and launch claude code in a project directory
2. Type commands via System Events keystrokes
3. Capture screenshots of just the Terminal window (not full screen)
4. Record full sessions with timestamped logs

Requirements

• macOS
• Node.js 18+
• Claude Code installed and authenticated
• Accessibility permissions for Terminal.app + Script Editor (System Settings → Privacy & Security → Accessibility)

Usage

const cc = require('./index');

// Launch Claude Code visibly
const session = await cc.launch('/path/to/project');

// Send a command (types it + presses Enter)
const result = await cc.send(session, 'write tests for app.py', 30);
// result.screenshot → path to Terminal window screenshot

// Save session recording
await cc.saveSession(session, './recording.json');

// Close
await cc.close(session);

API

Function	Description
launch(path, opts?)	Open Terminal + start Claude Code. Returns session ID
send(id, command, waitSec?)	Type command, wait, screenshot. Returns {screenshot, duration_ms}
verifyScreen(id, desc)	Take a verification screenshot
approveSecurity(id)	Handle "trust this folder" prompt
handleLogin(id)	Send /login command
saveSession(id, path)	Save session log to JSON
close(id) / closeAll()	Exit Claude Code gracefully
takeScreenshot(path?)	Capture Terminal window
focusTerminal()	Bring Terminal to front

Pro Features (Coming Soon)

• 🎬 Video recording of sessions
• 🤖 Multi-agent / multi-terminal orchestration
• 📊 Session analytics
• 🔄 Session replay
• 🌐 Remote control via SSH