Mac Agent Ops — Development skill for Claude Code

mac-agent-ops

Mac Agent Ops is a small control-room kit for operating remote Mac-based agents over SSH. It gives you reusable runbook templates, safe status checks, log tailing, port forwarding, remote reboot helpers, and an auth handoff pattern for services that need a browser on your local machine.

The project is intentionally plain shell and Python. It is meant to be copied into an ops repo, edited to fit your hosts, and kept readable during incidents.

What This Is For

• Remote Mac mini or Mac Studio agent hosts.
• Local-first agent stacks that run under LaunchAgents, terminal sessions, or app daemons.
• Incident runbooks for auth failures, stuck services, webhook delivery, and machine recovery.
• Small teams that want a repeatable "check, repair, verify" workflow without a full infrastructure platform.

What This Is Not

• A secrets store.
• A monitoring SaaS.
• A replacement for MDM, osquery, or endpoint management.
• A place to commit private hostnames, emails, tokens, chat IDs, internal database IDs, or customer data.

Quick Start

1. Copy .env.example to .env and set your host alias.
2. Customize AGENTS.md and CLAUDE.md from the templates.
3. Run a status check:

bin/mac-status.sh

1. Tail logs:

bin/mac-logs.sh ~/Library/Logs/example-agent.log

1. Open a tunnel to a remote service:

bin/mac-fwd.sh 8080 127.0.0.1 8080

Repository Layout

bin/          SSH helpers and local auth handoff utilities
docs/         Security, redaction, remote auth, and incident docs
examples/     Safe example configs with fake hosts and fake agents
templates/    Starter AGENTS.md, CLAUDE.md, and agent profile files

Safety Model

This repo is designed to be public-safe, but your fork may not be. Before publishing changes, read `docs/REDACTION.md` and run a secret scan. Keep private operational history in a separate private repo.

Typical Workflow

bin/mac-status.sh
bin/mac-logs.sh ~/Library/Log