Setup Agent Workstation

A Codex skill for auditing, planning, and configuring macOS or Windows development workstations for AI agent engineering.

This project helps an AI coding agent turn a fresh or newly migrated computer into a usable development environment without jumping straight into a risky one-shot install script. It starts with read-only inventory, builds a staged plan, separates required and optional tools, and keeps secrets and existing configuration safe.

What It Helps Set Up

• macOS and Windows developer baselines
• Git, SSH, GitHub CLI, terminal, shell, and editor setup
• Python and Node/TypeScript runtimes
• uv, Corepack, pnpm, and project dependency bootstrapping
• Docker, WSL2, browser automation, and local services
• AI agent tooling, local model tooling, GPU-aware paths, and cloud CLIs as opt-in categories
• Reproducible migration notes for future computers

Design Goals

• Audit before installing anything.
• Generate reviewable plans; do not auto-install software.
• Keep global installs small and project dependencies local to each repo.
• Keep default profiles conservative; heavy tools stay opt-in.
• Support both macOS and Windows with OS-specific data and references.
• Protect dotfiles, shell profiles, SSH config, and secrets.

Quick Start

Generate a reviewable Markdown setup plan:

python scripts/generate_setup_plan.py --os auto --profile agent

Generate a JSON plan for another machine:

python scripts/generate_setup_plan.py --os windows --profile minimal --format json
python scripts/generate_setup_plan.py --os macos --profile gpu --format json

List categories:

python scripts/generate_setup_plan.py --os macos --list-categories

Include or exclude categories:

python scripts/generate_setup_plan.py --os macos --profile full --exclude cloud
python scripts/generate_setup_plan.py --os windows --profile agent --include gpu

The generator only prints commands and checklists. It does not install packages.

Inventory

Run a read-only workstation inventory before deciding what to install.

Windows:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/inventory_windows.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/inventory_windows.ps1 -Format json

macOS:

bash scripts/inventory_macos.sh
bash scripts/inventory_macos.sh --format json

Inventory scripts report OS, architecture, package managers, Git, GitHub CLI, Python, uv, Node, Corepack, pnpm, Docker, WSL or GPU status where relevant, and common editors. They do not install packages, modify shell profiles, create SSH keys, or read secrets.

Profiles

Profile	Use case
minimal	Git, shell, editor, package manager, Python/Node basics, and small CLI utilities.
agent	Default AI agent engineering setup with containers, browser automation readiness, runtimes, GitHub CLI, and quality tools.
gpu	Local model inference or training, CUDA, Apple Silicon acceleration, WSL GPU support, or native build support.
full	Broader workstation setup with databases, local model tools, cloud CLIs, and extra services.

Install As A Codex Skill

Clone this repository into your Codex skills directory:

git clone https://github.com/NJX-njx/setup-agent-workstation.git ~/.codex/skills/setup-agent-workstation

On Windows:

git clone https://github.com/NJX-njx/setup-agent-workstation.git "$env:USERPROFILE\.codex\skills\setup-agent-workstation"

Then invoke it in Codex:

Use $setup-agent-workstation to audit this new computer and create a staged setup plan for AI agent engineering.

Repository Structure

.
|-- SKILL.md
|-- agents/openai.yaml
|-- data/
|   |-- macos.json
|   |-- profiles.json
|   `-- windows.json
|-- references/
|-- scripts/
|   |-- generate_setup_plan.py
|   |-- inventory_macos.sh
|   |-- inventory_windows.ps1
|   `-- validate_skill.py
`-- .github/

Data Model

Package catalogs live in data/*.json so they can be reviewed without editing Python code. Each tool entry includes:

• id
• manager
• note
• install_command
• verify_commands
• manual
• categories

Manual or machine-specific items should set manual to true and explain the required review step.

Local Validation

python -m py_compile scripts/generate_setup_plan.py scripts/validate_skill.py
python scripts/validate_skill.py .
python scripts/generate_setup_plan.py --os windows --profile minimal --format json
python scripts/generate_setup_plan.py --os macos --profile agent

Contributing

Use CONTRIBUTING.md for local checks and package request guidance. Use GitHub issues for bugs and tool requests. Include official package IDs and verification commands when proposing new tools.

Safety Notes

• Verify package IDs before installing fast-moving AI tools or editor apps.
• Do not paste private keys or API tokens into chat, issues, PRs, logs, or examples.
• Back up or diff shell profiles, dotfiles, SSH config, and package manager config before replacing them.
• Prefer per-project dependency files over global package installs.
• Treat GPU, CUDA, drivers, and local model runtimes as machine-specific.

License

MIT