AI intro 2. Setting Up the macOS Environment for AI Vibecoding in Claude Code

This lesson describes the correct order for preparing macOS to work with Claude Code (Codex), GitHub, Python, JavaScript, audio, Google services, plugins, MCP, AGENTS.md, skills, and the command folder structure.

Step 1. Up-to-date macOS and a macOS account with administrator rights

Before setting up an environment for AI vibecoding with Claude Code (Codex), you need to make sure that the computer itself is ready for this kind of work at the operating system level.

1. Use a modern macOS

You must work with Claude Code (Codex) only on a current, modern version of macOS 26 Tahoe with update support. You cannot work on old operating system versions that are 3–5 years old.

An old macOS will almost inevitably lead to problems:

access errors;
permission errors;
incompatibility with modern development tools;
issues installing packages and dependencies;
unstable operation of the terminal, browsers, IDEs, Claude Code (Codex), and related tools.

For AI vibecoding, it is important that the system supports modern versions of developer tools, shell tools, browsers, Node.js, Python, Docker/OrbStack, GitHub CLI, and other environment components.

2. Install all available macOS updates

It is not enough just to have a new macOS . Before you start setting up the AI environment on your Desktop or Laptop, you need to install all system updates available as of the current day.

Check through:

System Settings -> General -> Software Update

If macOS offers updates, they must be installed before setting up the Claude Code (Codex) environment.

This reduces the risk of random errors related to:

outdated system libraries;
incomplete security updates;
Xcode Command Line Tools incompatibility;
permission issues;
unstable operation of the terminal, shell scripts, and package managers.

3. Work from the primary administrator account

You need to configure and use the AI vibecoding environment from the primary macOS account with administrator rights.

Do not start setup from a restricted account, a guest account, or a profile without admin access.

Administrator rights are needed for:

installing developer tools;
installing Homebrew and system dependencies;
configuring the shell and paths;
managing macOS permissions;
installing browsers, IDEs, CLI tools, and local services;
resolving issues with access to files, certificates, keys, and local servers.

Rule

The first step before any installation:

macOS must be modern, fully updated, and used from an administrator account.

If this condition is not met, it is better not to start setting up the environment for Claude Code (Codex): subsequent errors will look like issues with Claude Code, Node.js, Python, Git, or Homebrew, while the real cause will be an unprepared system.

Step 2. Install Claude Code and create a working project folder

After checking macOS, updates, and administrator rights, the next step is to install Claude Code (Codex) and prepare a place in the file system where projects for AI vibecoding will be stored.

1. Where to store Claude Code projects on macOS

On macOS, the equivalent of the familiar "My Documents" folder is:

~/Documents

For working with Claude Code (Codex), it is better to create a separate folder inside it:

~/Documents/Claude
~/Documents/Codex

This is where you should place the project folders that Claude Code will work with:

~/Documents/Claude/
  AI/
  Product/
  Project-1/
  Project-2/
  Product-docs/
  Experiments/

For basic team onboarding, you can create two starting folders right away:

~/Documents/Claude/
  AI/
  Product/

AI is a folder for Claude Code setup, training, handoff documents, experiments with AI tools, and materials on the AI workflow.

Product is a folder for product work: PRDs, specifications, transcripts, Markdown documents, a knowledge base, and files that can later sync with GitHub, Confluence, or other team systems.

It is better to write folder names in Latin characters: AI, Product, Claude. This makes you less likely to encounter issues in shell scripts, paths, CI, package managers, and development tools.

Why it is better to use exactly `~/Documents/Claude, rather than random folders on the desktop or in Downloads:

the path is understandable to a person and an agent;
correct access permissions for folders and files in AI projects (the most important thing);
projects are located in one predictable place;
less risk of losing files among downloads and temporary documents;
it is easier to give Claude context: "work in the project from ~/Documents/Claude/...";
it is easier to make backups;
it is easier to transfer the working structure to a new Mac.

You can create the folder through Finder or through Terminal:

mkdir -p "$HOME/Documents/Claude"

2. Install Claude Code CLI

Claude Code CLI is needed to work from the terminal: open a project folder, run claude, give the agent a task, allow it to read files, edit code, and run commands.

The current official installation method on macOS/Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

After installation, you need to check that the command is available:

codex --version

Then you can go to the working folder and launch Claude Code (Codex):

cd "$HOME/Documents/Claude Code (Codex)"
codex

On the first launch, Claude Code (Codex) will ask you to sign in through a ChatGPT account or an OpenAI API key.

3. Install the Claude Code desktop app

After the CLI, you need to install the Claude Code (Codex) desktop app on macOS. For full work with AI infrastructure, you need the desktop version of Claude specifically, which contains Claude Code and Claude Co-work. Working with Claude only through the browser version significantly limits your capabilities.

The Claude Code (Codex) app is needed for:

working with locally installed folders and files
working with locally installed programming languages
full work with plugins, connecting to Google, Atlassian, Github services
coding and vibecoding
using the voice interface and image/screenshot interface in coding
working with multiple projects;
running actions such as dev server, tests, build;
more convenient everyday AI vibecoding than using only the terminal.

When installing the Codex Desktop app on a Mac with Apple Silicon, you need to choose the build for Apple Silicon. On Macs with Intel Core processors, choose the build for Intel.

4. What the basic structure on a Mac should look like

The minimum local folder structure at the first step:

~/Documents/Claude/
  AI/
  Product/

The user creates folders for their projects in the main Claude folder inside Documents:

cd "$HOME/Documents/Claude/Product"
claude

And then adds these projects to the Claude Code desktop app through Project -> Use an existing folder.

Important: if a folder is created for a project that the team is already working on, you should not immediately write random files there. You need to find the GitHub repository corresponding to the project, and populate the project contents from that GitHub repository.

Otherwise, it is very easy to end up with two different "current" versions of the project.

5. Rule

The second setup step:

Install Claude Code CLI, install Claude Code Desktop App, and create a permanent working folder `~/Documents/Claude for all projects that Claude Code will work with.

Do not scatter projects across Desktop, Downloads, and random temporary folders. Claude Code works better when it has a stable, understandable file system structure with the correct permissions and access to local folders and files.

Step 03. Terminal and command line on macOS

After installing Claude Code (Codex), you need to agree properly on which command line the team uses on a Mac.

The command-line application, or terminal, is required to launch and execute low-level commands for the operating system and files when working with coding and vibecoding.

In Windows, we often say "install PowerShell 7." On macOS, the situation is different: the basic command line is already built into the system.

1. What is the equivalent of PowerShell 7 on macOS

On macOS, there are two different things that are often confused:

a terminal application, that is, the window where commands are entered;
a shell, that is, the program that understands and executes those commands.

The built-in terminal application is called:

Terminal.app

The built-in standard shell on modern macOS:

zsh

You do not need to install zsh separately. It is already included in modern macOS and usually launches by default inside the standard Terminal.app.

That is, the basic equivalent of a working command line on a Mac is not PowerShell, but the combination:

Terminal.app + zsh

This is enough to run installation commands, launch the Claude Code (Codex) CLI, work with Git, Homebrew, Node.js, Python, and projects.

Check which shell is currently being used:

echo "$SHELL"

The normal expected result:

/bin/zsh

Check the zsh version:

zsh --version

2. Is the built-in Terminal.app enough

Yes, the built-in Terminal.app is enough to start.

It is already included in macOS and is located here:

Applications -> Utilities -> Terminal

Or it can be opened through Spotlight:

Cmd + Space -> Terminal -> Enter

For the first AI environment setup, you do not need to install an additional terminal. The fewer unnecessary steps before a working Claude Code , the better.

4. When it is worth installing iTerm2

After the basic setup, you can install iTerm2 as a more convenient terminal application.

iTerm2 does not replace the shell. It replaces only the terminal window. The same zsh usually still runs inside it.

iTerm2 is useful if a person needs:

convenient tabs and split panes;
profiles;
fast search through output history;
more flexible font and color configuration;
comfortable daily work in the terminal.

But iTerm2 should not be a mandatory first step. First, the team must be able to open the regular Terminal.app and execute basic commands.

6. What every team member should be able to do

Before continuing with environment installation, a person should be able to:

open Terminal.app;
go to the projects folder:

cd "$HOME/Documents/Claude"

view the current folder:

pwd

view the list of files:

ls

create a folder:

mkdir -p "$HOME/Documents/Claude"

launch Claude Code:

claude

7. Rule

The third setup step:

On macOS, the team works through the built-in Terminal.app and the standard zsh shell. iTerm2 can be installed later as a more convenient terminal window, but not as a mandatory prerequisite for starting.

This approach is simpler, closer to macOS itself, and better compatible with most developer tools used in AI vibecoding.

Step 04. Screenshots on macOS for working with Claude Code

For AI vibecoding with Claude Code (Codex), screenshots are one of the main ways to convey context. The team must be able to quickly capture the needed window or screen area and immediately paste the image into Claude Code.

1. Is a separate screenshot tool needed

At the first stage, you do not need to install a separate screenshot tool.

macOS already has a built-in screenshot tool. It is good enough for basic work with Claude Code:

capture the entire screen;
capture a selected area;
capture a specific window;
copy a screenshot directly to the clipboard;
paste a screenshot into Claude Code (Codex) without saving a file to disk.

This is exactly the scenario needed for communicating with Claude Code (Codex) through screenshots and voice messages.

2. The main requirement

The main requirement for a screenshot tool:

Press a hotkey, select a specific window or area, put the image into the clipboard, and paste it immediately into Claude Code (Codex).

On a Mac, pasting is usually not done through Ctrl+V, but through:

Cmd+V

That is, the working scenario is:

took a screenshot -> the screenshot went to the clipboard -> opened Claude Code (Codex) -> pressed Cmd+V

3. Basic macOS hotkeys

Screenshot of a screen area to a file:

Shift+Cmd+4

Screenshot of a screen area directly to the clipboard:

Ctrl+Shift+Cmd+4

After this, select the required area with the mouse. The screenshot will not be saved as a separate file but will go to the clipboard. You can then paste it into Claude Code (Codex) through Cmd+V.

Screenshot of a specific window to the clipboard:

Ctrl+Shift+Cmd+4 -> Space -> click the required window

This is the most important option for working with Claude Code (Codex), because it lets you quickly show the agent a specific window: browser, terminal, error, IDE, macOS settings, or the result of the application.

Screenshot panel:

Shift+Cmd+5

Through it, you can select a screenshot or screen-recording mode, and also configure where screenshots are saved.

4. Best practice for the team

Team standard:

Primary tool: built-in macOS Screenshot
Required skill: screenshot an area or window directly to the clipboard
Primary paste into Claude Code (Codex): Cmd+V
Third-party screenshot tool: not mandatory at the start

Every team member must learn at least two commands:

Ctrl+Shift+Cmd+4

for a screenshot of an area to the clipboard.

Ctrl+Shift+Cmd+4 -> Space -> click

for a screenshot of a specific window to the clipboard.

5. Rule

The fourth setup step:

The team uses the built-in macOS Screenshot and must know how to screenshot an area or a specific window directly to the clipboard in order to paste it into Claude Code (Codex) through Cmd+V.

This is critical because effective work with Claude Code (Codex) is based not only on text, but also on fast screenshots of errors, interfaces, the terminal, the browser, and application results.

Step 05. Xcode Command Line Tools on macOS

On Windows, JavaScript/Node.js projects sometimes require installing Microsoft Visual Studio Build Tools 2022 so that native dependencies can be built: packages that compile C/C++ code through node-gyp during npm install or pnpm install.

On macOS, Xcode Command Line Tools are installed.

This item must be completed before installing Git, GitHub CLI, Homebrew, Python packages, Node.js packages, and FFmpeg, because Xcode Command Line Tools provide macOS with the basic developer toolchain.

1. Xcode Command Line Tools on macOS

Build tools on macOS are Apple tools:

Xcode Command Line Tools

They are also called:

Command Line Tools for Xcode

They provide the system with a compiler toolchain needed to build native packages:

clang;
make;
headers;
SDK;
developer command-line utilities.

2. Is this included in macOS by default

Xcode Command Line Tools are Apple tools for macOS, but they are not always installed on a clean Mac.

They may already have been installed earlier, for example:

when installing Git;
on the first launch of a developer command;
when installing Homebrew;
when installing Xcode;
when running xcode-select --install.

Therefore, the correct approach is:

do not assume; check

3. How to check installation

Check the path to the active developer tools:

xcode-select -p

If the tools are installed, the command will show a path, for example:

/Library/Developer/CommandLineTools

Check the compiler:

clang --version

Check make:

make --version

If these commands work, the basic build tools are ready.

4. How to install Xcode Command Line Tools

If the tools are not installed:

xcode-select --install

macOS will open a system installation window. You need to agree to the installation and wait for it to complete.

After installation, check again:

xcode-select -p
clang --version
make --version

5. Full Xcode is usually not needed

The full Xcode application takes up a lot of space and is not always needed.

For most Claude Code (Codex), Node.js, Python, Homebrew, Git, and native npm/pnpm dependency tasks, this is enough:

Xcode Command Line Tools

Full Xcode is needed only if the project is explicitly related to:

iOS development;
macOS app development;
Swift/Objective-C projects;
Xcode projects;
iPhone/iPad simulators;
building Apple applications.

If there are no such tasks, do not install full Xcode by default.

6. Connection with Node.js and pnpm

Some JavaScript packages may run node-gyp and build a native module during installation.

If Xcode Command Line Tools are not installed, you may see errors such as:

gyp ERR!
No Xcode or CLT version detected
make failed
clang not found

In that case, you need to check and install Xcode Command Line Tools.

7. Do not search for instructions independently

Strict rule:

If pnpm install, npm install, Python package install, or Homebrew fails with a build error on macOS, ask Claude Code (Codex) which build tools are needed. Do not search for random instructions online.

The correct request:

Claude, on macOS, building a native dependency fails when installing Node.js/Python packages. Here is the complete error log. Check whether Xcode Command Line Tools are installed and tell me which commands to run.

If a system installation window appears:

Claude, macOS offers to install Command Line Tools for Xcode. Is this needed for the Claude Code environment? Here is a screenshot.

8. Do not fix developer tools at random

Do not run commands such as the following without instructions:

sudo xcode-select --switch ...
sudo rm -rf /Library/Developer/CommandLineTools

This can break Homebrew, Git, Python packages, and Node.js native builds.

If xcode-select or clang behaves strangely, show Claude Code (Codex):

xcode-select -p
xcode-select --version
clang --version
make --version

and the full error text.

9. Rule

The fifth setup step:

On macOS, install Xcode Command Line Tools for the Claude Code environment. This step is completed before installing Git and the remaining developer tools. If Xcode installation produces unclear errors, or if errors occur while working with Xcode, go back two steps and check whether your macOS is clean and new. If not, reinstall macOS after first saving your personal and work files. There will be no Xcode errors on a clean macOS.

Check:

xcode-select -p
clang --version
make --version

Install if needed:

xcode-select --install

Additional rule:

If building JavaScript/Python packages fails, do not fix the compiler toolchain at random. Ask Claude Code (Codex) and follow the exact instructions for macOS.

Step 06. Install and configure Git

Git is a mandatory tool for AI vibecoding with Claude Code (Codex). Without Git, it is more difficult and even impossible to safely change code, review a diff, roll back errors, make commits, open pull requests, and understand what exactly the agent changed.

Before this item, Xcode Command Line Tools must be installed or checked. On macOS, they provide the basic developer tools through which Git is often installed or activated.

1. Is Git included in macOS by default

On macOS, Git is often already available after Xcode Command Line Tools are installed.

You can check in Terminal.app:

git --version

If Git is already installed, the command will show a version, for example:

git version 2.x.x

If Git is not installed, macOS may offer to install Xcode Command Line Tools. This is a normal path for a Mac.

Command to install Xcode Command Line Tools:

xcode-select --install

After installation, you need to check again:

git --version

2. Do not search for a Git link independently

If you need a current Git download link or do not understand which installation method to choose, do not look for it yourself in random articles and videos.

Rule:

Ask Claude Code (Codex) for the current link or Git installation method.

Example request:

Claude, I need to install Git on macOS. Tell me the current official installation method for my case and give me a link if one is needed.

On macOS, a link is usually not needed at all: Xcode Command Line Tools or Homebrew are enough. But if Claude Code (Codex) recommends downloading an installer, it must provide a current official link and explain why that option was selected.

3. Do not guess installer checkboxes

The Windows Git installer really has many screens with settings and checkboxes. On macOS, this scenario is less common, but the rule should still be universal for the team.

Strict rule:

Do not guess Git installer settings. If checkboxes, PATH options, editor, line endings, SSH, credential helper, or other unclear settings appear on the screen, send a screenshot to Claude Code and ask what to choose.

The correct request:

Claude, I am installing Git now and will send you screenshots of the setup screens. Please tell me which checkboxes and options to choose so that Git is configured for AI vibecoding with Claude Code on macOS.

Then send screenshots of every unclear installation step to Claude Code, and it will explain what to choose and why.

This is important because incorrect Git settings can lead to problems:

Git cannot be found in the terminal;
commits are created with the wrong name or email;
SSH keys do not work;
GitHub asks for a password again and again;
line endings change in files;
Claude Code sees unnecessary changes in the diff;
pull/push work unstably.

4. Recommended Git installation path on macOS

For the team, the basic path is:

Open Terminal.app.
Check Git:

git --version

If Git is not installed, install Xcode Command Line Tools:

xcode-select --install

After installation, check again:

git --version

Later, after installing Homebrew, you can install a newer Git through Homebrew if necessary:

brew install git

But at the first stage, do not make things more complicated. If Git through Xcode Command Line Tools works, that is enough to start.

5. Basic Git configuration

After installation, you need to specify your name and email for commits once:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Check the settings:

git config --global --list

At minimum, you should see:

user.name=Your Name
[email protected]

It is better to use the email associated with the GitHub account. If a private GitHub noreply email is used, take it from GitHub settings and paste it here.

6. Git must work from the Claude Code projects folder

After setup, you need to check Git in the working folder:

cd "$HOME/Documents/Claude"
git --version

If the command shows the Git version, then Claude Code CLI will also be able to use Git inside projects.

For a specific project, it is useful to check:

git status

If the folder is already a Git repository, the command will show the state of the working copy. If not, Git will honestly say that it is not a repository. This is normal.

7. What else is important for Claude Code (Codex)

For AI vibecoding, Git is needed not only "so that it is installed." It is needed as a safety system.

Before a major task, it is desirable to have a clean status:

git status

If there are important uncommitted changes, they need to be saved or committed before Claude Code begins actively changing the project.

After Claude Code works, you need to look again:

git diff
git status

This way, a person understands which files changed and what exactly the agent did.

8. Rule

The sixth setup step:

Git must be installed, available from Terminal.app, configured with the correct user.name and user.email, and checked in the `~/Documents/Claude folder.

Additional strict rule:

Do not look for random instructions and do not guess Git installer checkboxes. Ask Claude Code (Codex) about the current installation method and all unclear settings, sending screenshots of installation screens.

This way, Git becomes not a random program on the computer, but a normal foundation for Claude Code (Codex) to work safely with code.

Step 07. Install Homebrew

After Xcode Command Line Tools and Git, you need to install Homebrew.

Homebrew is a package manager for macOS. It is needed to conveniently install and update developer tools, command-line utilities, libraries, and some desktop applications.

For the Claude Code (Codex) environment, Homebrew is especially useful because it is convenient to install through it:

GitHub CLI (gh);
FFmpeg;
libsndfile for Python audio packages;
Node.js, if the team chooses the Homebrew path;
Python versions, if the team chooses the Homebrew path;
additional command-line tools.

1. Homebrew is not included in macOS

Homebrew is not a standard part of macOS.

It must be installed separately.

Check whether Homebrew is installed:

brew --version

If the command cannot be found, Homebrew is not installed yet or has not been added to PATH.

2. Why install Homebrew after Git

Homebrew actively uses macOS developer infrastructure and GitHub.

Therefore, the correct order is:

Xcode Command Line Tools -> Git -> Homebrew

Xcode Command Line Tools provide the compiler/developer toolchain.

Git is needed to work with repositories and can be used by Homebrew.

Homebrew is installed on top of this basic layer.

3. Do not search for the installation command independently

Strict rule:

Ask Claude Code (Codex) for the Homebrew link and Homebrew installation command. Do not search for random instructions online and copy commands from articles, videos, or forums.

The correct request:

Claude, I need to install Homebrew on macOS for the Claude Code environment. Tell me the current official installation command, check the order of the steps, and tell me what to do with PATH after installation.

At the time this instruction was written, the official Homebrew install script looks like this:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

But in the working instruction for the team, the main rule remains the same:

Get the current command from Claude Code (Codex), and Claude Code must rely on the official Homebrew site.

4. Installation

Before installation, check:

xcode-select -p
git --version

If both steps work, ask Claude Code for the current Homebrew installation command and run it in Terminal.app.

After launching the installer, read the output carefully. The Homebrew installer usually explains what it is going to do and may ask for an administrator password.

If an unclear prompt appears, do not guess the answer:

Claude, I am installing Homebrew on macOS. Here is a screenshot/installer output. Tell me what to choose and whether I can continue.

5. PATH after installing Homebrew

After installation, Homebrew almost always prints a Next steps block.

It may include commands that need to be added to shell config so that brew can be found in Terminal.app.

For an Apple Silicon Mac, Homebrew is usually installed here:

/opt/homebrew

For an Intel Mac, Homebrew is usually installed here:

/usr/local

But commands for PATH must not be invented manually.

Strict rule:

Show the commands from the Next steps block to Claude Code (Codex) or copy them into Claude Code and run them only after confirmation. Especially if they concern ~/.zprofile, ~/.zshrc, or PATH.

The correct request:

Claude, Homebrew was installed and showed Next steps. Here is the full text. Tell me which commands to run so that brew is correctly added to PATH on my Mac.

6. Check the installation

After installation, open a new Terminal.app window and run:

brew --version
brew doctor

brew --version should show the Homebrew version.

brew doctor may show warnings. Not all warnings are critical, but they need to be read.

If brew doctor shows an unclear warning or error, do not fix it at random:

Claude, here is the output of brew doctor on macOS. Explain which warnings are important for the Claude environment and what is safe to fix.

7. What can be installed through Homebrew

After installing Homebrew, you can install developer tools:

brew install gh
brew install ffmpeg
brew install libsndfile

But it is better to take each specific installation command from the corresponding instruction item or ask Claude Code (Codex).

Homebrew is not a reason to install everything globally and indiscriminately.

8. Do not use random sudo

If a random instruction suggests fixing Homebrew through:

sudo chown
sudo chmod
sudo rm -rf

stop and ask Claude Code (Codex).

Homebrew may ask for a password during installation, but regular brew install ... work should not turn into a chaotic set of sudo commands.

9. Rule

The seventh setup step:

After Xcode Command Line Tools and Git, install Homebrew. Homebrew is not included in macOS, but is needed as a package manager to install GitHub CLI, FFmpeg, audio libraries, and other developer tools.

Additional strict rule:

Get the Homebrew link, installation command, and PATH configuration from Claude Code (Codex). Do not search for random instructions online, do not edit shell config at random, and do not run sudo commands without understanding them.

Step 08. Install GitHub CLI

After installing Git and Homebrew, you need to install GitHub CLI. This is GitHub's command-line interface, which lets you work with GitHub from Terminal.app: authorize, check repositories, create pull requests, view issues, read CI statuses, and perform other actions without switching to a browser.

GitHub CLI is launched with the command:

gh

1. First, a GitHub account is needed

GitHub CLI should be installed and configured only after a person already has a corporate GitHub account.

Why:

after installing gh, you will need to authorize in GitHub;
authorization requires an existing GitHub account;
without authorization, GitHub CLI is installed but almost useless for actual work;
Claude Code (Codex) will not be able to help with pull requests, issues, and GitHub workflows through local gh if the user has not signed in to GitHub.

Rule:

First create or prepare a GitHub account, then install and authorize GitHub CLI.

2. Do not search for the installation command independently

On Windows, GitHub CLI is often installed directly from the command line using a special command. There is also a command-line installation method on macOS, but you should not search for it manually online.

Strict rule:

Ask Claude Code (Codex) for the current GitHub CLI installation command.

Example request:

Claude, I need to install GitHub CLI on macOS. Tell me the current official installation command for my Mac and take into account whether I have Homebrew.

This is important because the installation method depends on the situation:

whether Homebrew is installed;
Apple Silicon Mac or Intel Mac;
regular GitHub.com or GitHub Enterprise;
whether there are corporate restrictions on package installation;
whether installation through a package manager or through an official binary/pkg is needed.

At the time this instruction was written, the official basic method for macOS through Homebrew is:

brew install gh

But in the working instruction for the team, the main rule remains the same: do not search random articles, ask Claude Code (Codex), and use the official method.

3. Check the installation

After installation, you need to check that the gh command is available:

gh --version

If the command shows a GitHub CLI version, installation was successful.

If Terminal.app says that gh is not found, do not guess the solution; ask Claude Code (Codex):

Claude, I installed GitHub CLI on macOS, but the gh command cannot be found in Terminal.app. Help me check PATH and fix the installation.

4. Authorize in GitHub

After installation, you need to authorize:

gh auth login

GitHub CLI will usually ask several questions:

GitHub.com or GitHub Enterprise Server;
HTTPS or SSH;
open a browser for authorization or paste a token;
which Git protocol to use by default.

If the person is not sure what to choose, they should send a screenshot to Claude Code (Codex) and ask.

Example request:

Claude, I am running gh auth login on macOS. Here is a screenshot with the options. Tell me what to choose for normal work with GitHub and Claude Code.

5. Check authorization

After signing in, you need to check the status:

gh auth status

Expected result: GitHub CLI should show that the user is authorized in GitHub.

If multiple accounts or GitHub Enterprise are used, you need to explicitly check which account is signed in.

6. Check operation in the Claude Code projects folder

After installation and authorization, you need to go to the working folder:

cd "$HOME/Documents/Claude"

And check:

gh auth status
gh repo list

If gh repo list shows the account repositories, GitHub CLI is ready to work.

Inside a specific GitHub repository, it is useful to check:

gh repo view

If the command shows information about the current repository, the local folder is connected to GitHub.

7. macOS specifics

On macOS, GitHub CLI is usually most conveniently installed through Homebrew:

brew install gh

But this assumes that Homebrew is already installed. If Homebrew is not installed yet, you need to first go to the instruction item about Homebrew or ask Claude Code (Codex) which installation path to choose now.

On a Mac, it is important to remember:

commands are run in Terminal.app;
the shell is usually zsh;
pasting text and screenshots is usually through Cmd+V;
if system access prompts appear, do not click randomly; send a screenshot to Claude Code;
if authorization opens a browser, you need to sign in to the correct GitHub account.

8. Rule

The eighth setup step:

GitHub CLI is installed only after preparing a GitHub account. Ask Claude Code for the current installation command. After installation, be sure to run gh auth login and check the result through gh auth status.

Additional rule:

If unclear choices, checkboxes, questions about HTTPS/SSH, browser login, token, or GitHub Enterprise appear when installing or authorizing GitHub CLI, the person does not guess the answer but sends a screenshot to Claude Code (Codex).

GitHub CLI should become the standard bridge between the local project folder, GitHub, and Claude Code (Codex).

Step 09. Install Python on macOS

Python is needed in the Claude Code (Codex) environment not because we like or dislike this language.

Python is needed because most simple automations in AI vibecoding are conveniently done with Python scripts:

take data from one file and move it into another;
parse CSV, JSON, Markdown, HTML, or a text log;
produce a small report;
rename a set of files;
check folder structure;
prepare data for import;
quickly write a one-time utility script;
automate a routine action that would be lengthy and risky to do manually.

For Claude Code (Codex), Python is not a matter of taste, but a mandatory working tool.

1. Python is mandatory

Every Mac prepared for AI vibecoding with Claude Code (Codex) must have a working Python 3.

Check for Python:

python3 --version

Check pip:

python3 -m pip --version

If these commands do not work or show an unsuitable version, Python must be installed.

2. Do not search for a link independently

You should not search independently online for the current Python download link or current installation command.

Rule:

Ask Claude Code (Codex) for the Python download link and installation method.

Example request:

Claude, I need to install Python on macOS for AI vibecoding. Tell me the current official link or installation command. I need a stable Python 3.12.x version, not the newest experimental/latest version.

This is important because the Python website may have a large button for the newest version, but our task does not need the newest version. We need the most stable and compatible version of the Python programming language for everyday automation.

3. Which Python version to install

For our Claude Code (Codex) environment, the baseline standard is:

Python 3.12.x

As of June 18, 2026, the latest version in the 3.12 branch is Python 3.12.13.

At the same time, officially newer branches already exist: Python 3.13 is in bugfix support, and Python 3.14 is the latest feature release. But for stable AI vibecoding, we do not chase the newest version.

Why we choose 3.12.x:

a mature and widely supported branch;
good compatibility with libraries;
less risk that simple automation scripts will break because of fresh changes;
sufficiently new version for most modern Python tools;
a more predictable environment for the team.

Strict rule:

For the basic Claude Code environment, install Python 3.12.x. Do not install Python 3.14 and newer versions by default until the team separately decides to update the standard and checks compatibility.

4. Built-in Python in macOS

macOS may have system Python components or developer tools related to Python.

Rule:

Do not touch the macOS system Python and do not rely on it as the working Python for Claude Code (Codex).

System Python is needed by macOS itself or Apple developer tools. It should not be removed, overwritten, or fixed manually.

A separate user/developer Python is installed for Claude Code (Codex) work.

5. Where to install Python on macOS

On Windows, people sometimes use installation at the root of drive C:\ so that Python is predictably available.

You should not do this on macOS. macOS has a different file system structure and a different approach to installing developer tools.

The correct approach:

do not install Python at the root of the drive;
do not modify system folders manually;
use the official macOS installer from python.org or a package manager;
check availability through Terminal.app.

The official macOS Python installer usually installs Python in a system-expected developer location such as:

/Library/Frameworks/Python.framework/Versions/3.12

And adds commands for launching Python 3.12 to standard paths.

If Python is installed through Homebrew, it will be installed in the Homebrew prefix:

/opt/homebrew

on an Apple Silicon Mac, or:

/usr/local

on an Intel Mac.

Both options are normal. For the team, the physical installation folder matters less than ensuring that these commands work reliably in Terminal.app:

python3 --version
python3 -m pip --version

6. Recommended installation method

For team members who are not confident working with package managers, the clearest path is:

Ask Claude Code (Codex) for the current official link to Python 3.12.x for macOS.
Download the official macOS installer from python.org.
Run the installer.
Do not guess unclear settings if they appear; send a screenshot to Claude Code (Codex).
After installation, open a new Terminal.app.
Check:

python3 --version
python3 -m pip --version

For people who already have Homebrew installed, this option is possible:

brew install [email protected]

But you still need to ask Claude Code (Codex) about the installation command in advance, because Homebrew, PATH, and team policy may differ.

7. Check after installation

After installation, you need to run:

python3 --version

Expected result for our standard:

Python 3.12.x

Check pip:

python3 -m pip --version

Check where Python is located:

which python3

Check that Python can run a simple script:

python3 -c "print('Python is ready for Claude Code (Codex) automation')"

8. Virtual environments

For projects, it is important not to install all Python libraries globally unless necessary.

Inside a specific project, it is better to use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

After activating .venv, libraries are installed inside the project rather than in global Python.

Claude Code (Codex) should see and use such an environment if Python scripts belong to a specific project.

9. What to do if the version does not match

If, after installation, the command:

python3 --version

shows something other than Python 3.12.x, do not delete Python or change system files at random.

Ask Claude Code (Codex):

Claude, I installed Python on macOS, but python3 --version shows the wrong version. Help me understand which Python is currently being used, where it is installed, and how to safely configure Python 3.12.x for Claude Code (Codex).

10. Rule

The ninth setup step:

Python is mandatory for the Claude Code environment because most simple automations are conveniently done with Python scripts. For a basic stable environment, install Python 3.12.x, do not touch the macOS system Python, and do not install Python manually at the root of the drive.

Additional rule:

Ask Claude Code (Codex) for the download link, installation command, and any unclear installer settings, rather than looking in random sources or guessing.

Step 10. Install must-have Python packages

After installing Python, you need to prepare the basic set of Python packages used in everyday work with Claude Code (Codex).

This is an extremely important step, because without the packages needed for your tasks in programming languages during vibecoding, you can easily encounter overspending or looping because of a missing package, and your Claude Code may not tell you about it. As a result, you will lose a lot of time and token spend.

Always, before a major task or project, first think and ask Claude Code which programming language we will use for this task and which necessary language packages we will need.

These packages are needed not "just in case," but for actual AI vibecoding scenarios:

working with the OpenAI API;
working with images;
working with audio;
preparing and processing voice transcriptions;
voice activity detection;
local ML/audio utilities.

1. Packages are installed not globally, but in a virtual environment

Main rule:

Python packages for Claude Code projects are not installed globally unless necessary. They must be installed in .venv inside a specific project or inside a separate environment bootstrap project.

The reason is simple: different Python packages and different package versions may be incompatible with each other. If everything is installed globally, sooner or later one automation will break another.

Working template:

cd "$HOME/Documents/Claude Code (Codex)"
mkdir -p python-tooling
cd python-tooling
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

After activating the environment, the terminal prompt usually shows (.venv).

2. Compatible pinned package set

For our practice, we fix a compatible set of versions:

imageio-ffmpeg==0.6.0
openai==2.33.0
numpy==1.26.4
torch==2.5.1
librosa==0.10.2.post1
soundfile==0.12.1
webrtcvad==2.0.10
Resemblyzer==0.1.4
setuptools==80.9.0

This is important: versions are pinned not for aesthetics, but because in practical work, different Python package versions often conflict with one another.

Strict rule:

Do not automatically update these packages to newer versions. If you want to update a package, first ask Claude Code (Codex), check compatibility, and run a test installation in a separate .venv.

3. Create a requirements file

Inside the project, create a file:

requirements-codex-python-tooling.txt

Contents:

imageio-ffmpeg==0.6.0
openai==2.33.0
numpy==1.26.4
torch==2.5.1
librosa==0.10.2.post1
soundfile==0.12.1
webrtcvad==2.0.10
Resemblyzer==0.1.4
setuptools==80.9.0

Installation:

python -m pip install -r requirements-codex-python-tooling.txt

4. What these packages do

openai==2.33.0 is needed for working with the OpenAI API.

numpy==1.26.4 is needed as a basic library for numeric data, arrays, audio, and ML dependencies.

torch==2.5.1 is needed for ML/audio tasks and dependencies such as Resemblyzer.

librosa==0.10.2.post1 is needed for analyzing and processing audio files.

soundfile==0.12.1 is needed for reading and writing audio files.

imageio-ffmpeg==0.6.0 is needed for tasks that require ffmpeg processing through Python.

webrtcvad==2.0.10 is needed for voice activity detection: determining where audio contains voice and where there is silence or noise.

Resemblyzer==0.1.4 is needed for speaker/audio embeddings and related voice tasks.

setuptools==80.9.0 is needed as a basic build dependency for Python packages.

5. macOS specifics

On macOS, some packages may require system developer tools.

Before installing this set, the previous steps must be completed:

a modern macOS is installed;
system updates are installed;
the user works from an admin account;
Git is installed;
Xcode Command Line Tools are installed;
Python 3.12.x is installed.

Check Xcode Command Line Tools:

xcode-select -p

If the tools are not installed:

xcode-select --install

6. `soundfile` and libsndfile

The soundfile package works through the system library libsndfile.

If soundfile is installed but importing it or reading audio fails with an error about libsndfile, you need to install the system library through Homebrew:

brew install libsndfile

After that, check again:

python -c "import soundfile; print(soundfile.__version__)"

7. `webrtcvad` may build from source

webrtcvad==2.0.10 may require compilation. Therefore, Xcode Command Line Tools must be installed before attempting to install the package.

If the installation of webrtcvad==2.0.10 breaks on a specific Mac, do not chaotically change the versions of all packages.

Ask Claude Code (Codex):

Claude, webrtcvad==2.0.10 cannot be installed on macOS in a Python 3.12 .venv. Here is the full error text. Help me understand whether compiler tools, a wheel, pip/setuptools are missing, or whether a compatible fallback is needed.

A possible fallback for a separate project is the webrtcvad-wheels package, which has binary wheels for macOS. But this is not a replacement for the basic pinned set without a separate team decision.

8. `torch` on macOS

PyTorch supports macOS, but installation depends on the Python version, Mac architecture, and available wheel packages.

For our baseline, use:

torch==2.5.1

If torch==2.5.1 cannot be installed on a specific Mac, do not immediately update the entire requirements file.

Ask Claude Code (Codex):

Claude, torch==2.5.1 cannot be installed on macOS in a Python 3.12 .venv. Here is the error. Check compatibility with my Mac architecture and suggest a safe option without breaking the rest of the pinned set.

9. Check the installation

After installing the packages, check imports:

python - <<'PY'
import imageio_ffmpeg
import openai
import numpy
import torch
import librosa
import soundfile
import webrtcvad
import resemblyzer
import setuptools

print("imageio-ffmpeg", imageio_ffmpeg.__version__)
print("openai", openai.__version__)
print("numpy", numpy.__version__)
print("torch", torch.__version__)
print("librosa", librosa.__version__)
print("soundfile", soundfile.__version__)
print("webrtcvad import ok")
print("Resemblyzer import ok")
print("setuptools", setuptools.__version__)
PY

If all imports succeed, Python tooling is ready to work.

10. Do not install packages before Python

Packages cannot be installed before the correct Python is installed and checked.

Correct order:

Python 3.12.x is installed.
python3 --version shows Python 3.12.x.
A .venv is created.
.venv is activated.
pip is updated.
The pinned requirements file is installed.
Import checks are performed.

11. Rule

The tenth setup step:

Must-have Python packages are installed only in .venv, strictly according to pinned versions, through a requirements file. This set is needed for the OpenAI API, images, audio, transcriptions, and simple Claude Code (Codex) automations.

Additional rule:

If one package cannot be installed on macOS, do not update the entire set at random. Send Claude Code the full error text and ask for a safe fix for the specific Mac, Python 3.12.x, and current pinned set.

Always use only strictly official and safe packages for work; packages from an unclear source must not be used, as this can lead to a vulnerability in your code.

Step 11. Install the JavaScript environment: Node.js and pnpm

After Python, you need to prepare the JavaScript environment. For Claude Code (Codex), this is just as much a must-have layer, because a huge number of modern projects, frontend tools, dev servers, CLI utilities, build systems, and AI integrations run through Node.js.

We need the JavaScript environment not because JavaScript is better or worse than Python, but because in real AI vibecoding work, Claude Code (Codex) constantly encounters:

web applications;
frontend projects;
React, Next.js, Vite, and similar frameworks;
npm/pnpm/yarn packages;
dev servers;
Playwright/browser automation;
OpenAI SDK for JavaScript/TypeScript;
file, image, audio, and video processing through Node tooling.

MiniApps also run specifically on scripting programming languages.

1. What needs to be installed

Basic JavaScript set:

Node.js
pnpm

Node.js is the runtime that runs JavaScript outside the browser.

pnpm is a package manager that often works faster and more cleanly with dependencies than regular npm. If a project uses pnpm-lock.yaml, you need to work through pnpm.

Important:

At this step, we install only Node.js and pnpm. We do not install all possible JavaScript packages for OpenAI, audio, video, images, frontend, and testing in advance.

npm is usually technically installed together with Node.js, but as a command standard for our projects, we prefer pnpm unless a specific project requires another package manager.

Node.js also has built-in core modules, for example fs, path, http, crypto. This is part of Node.js itself; they cannot and do not need to be separately installed or removed. The phrase "Node.js without all packages" in our instruction means:

install the Node.js runtime, but do not install project dependencies globally

2. Node.js is not built into macOS

Unlike zsh, Node.js is not a standard part of macOS.

It must be installed separately.

Check whether Node.js is installed:

node --version

Check npm:

npm --version

Check pnpm:

pnpm --version

If node or pnpm cannot be found, the JavaScript environment is not ready yet.

3. Which Node.js version to install

For the Claude Code (Codex) environment, install a stable LTS version of Node.js, not Current/latest.

As of June 18, 2026, the official Node.js LTS is:

Node.js v24.17.0 LTS

At the same time, Node.js v26.x already exists as Current, but do not install it by default for the basic stable environment.

Rule:

For the team, install Node.js LTS. Install Current/latest only if a specific project explicitly requires it.

4. Do not search for an installation link or command independently

Ask Claude Code (Codex) for the current Node.js download link or installation command.

Example request:

Claude, I need to install Node.js on macOS for AI vibecoding. Tell me the current official installation method. I need the LTS version, not Current.

This is important because the Node.js site may offer several options:

LTS;
Current;
macOS installer;
Homebrew;
version manager;
Apple Silicon;
Intel Mac.

Do not choose at random.

5. Recommended approach on macOS

There are two normal options for the team.

Option 1: the official installer from nodejs.org.

This path is easier for newcomers. A person downloads the LTS installer, installs Node.js, and then checks:

node --version
npm --version

Option 2: a version manager, for example fnm or nvm.

This path is better for developers who work with multiple projects on different Node.js versions.

On macOS, you need to take the Mac architecture into account:

Apple Silicon: arm64
Intel Mac: x64

If a person downloads an installer manually, they must choose the correct option for their Mac. If they are unsure, ask Claude Code and send a screenshot of the download page or the output of:

uname -m

Expected options:

arm64
x86_64

The team standard can be formulated as follows:

For newcomers: official Node.js LTS installer.
For developers with multiple projects: version manager.
Main rule: use Node.js LTS everywhere unless a project requires otherwise.

If a person does not understand which option to choose, they ask Claude Code (Codex).

6. Install pnpm

After installing Node.js, you need to install or enable pnpm.

A modern safe option is often done through Corepack, which comes with Node.js:

corepack enable
corepack prepare pnpm@latest --activate

After that, check:

pnpm --version

If the command runs on a corporate Mac and corepack enable asks for permissions or fails because of permissions, do not run random sudo commands from the internet. Send Claude Code (Codex) the complete error output.

If Corepack is unavailable or the command does not work, do not guess the fix. Ask Claude Code:

Claude, I installed Node.js LTS on macOS, but I cannot enable pnpm through Corepack. Here is the terminal output. Help me install pnpm safely.

7. Do not install project packages globally

Only basic tools such as node, npm, pnpm should be globally available.

Project dependencies need to be installed inside a specific project:

cd "$HOME/Documents/Claude Code (Codex)/my-project"
pnpm install

or, if the project uses npm:

npm install

You must not randomly install packages globally such as:

npm install -g openai
npm install -g typescript
npm install -g vite

unless the project explicitly requires them.

For our team, this is a separate strict rule:

Node.js is installed without a global set of additional JS packages. All packages for OpenAI, voice, audio, transcription, images, video, frontend, and tests are installed only inside the specific project after checking package.json and the lockfile.

8. Ask about needed JS packages before working with a project

Before starting work on a specific JavaScript/TypeScript project, ask Claude Code (Codex) which dependencies are needed specifically for this project.

Example request:

Claude, I am starting work on this project on macOS. Review package.json, the lockfile, and the project structure. Tell me which Node.js packages need to be installed and which package manager to use: npm, pnpm, or yarn.

For projects with OpenAI, voice, audio, transcription, images, and video, ask a separate question:

Claude, the project will work with the OpenAI API, voice, audio, transcription, images, and video. Check which JavaScript/TypeScript packages are needed, which versions are compatible, and suggest an installation without dependency conflicts.

Claude Code (Codex) must look at:

package.json;
pnpm-lock.yaml;
package-lock.json;
yarn.lock;
README;
.nvmrc;
.node-version;
engines in package.json;
existing scripts.

9. How to choose a package manager in a project

Do not choose a package manager at random.

Rule:

If pnpm-lock.yaml exists -> use pnpm.
If package-lock.json exists -> use npm.
If yarn.lock exists -> use yarn.
If there is no lockfile -> ask Claude Code (Codex) what to choose for the project.

For new projects, you can use pnpm if there are no restrictions.

10. Common packages for AI/media projects

You do not need to install all these packages in every project in advance, but the team should understand which categories are commonly encountered:

OpenAI API: openai;
schemas and validation: zod;
images: sharp, jimp;
browser automation: playwright;
video/audio through ffmpeg: fluent-ffmpeg, ffmpeg-static;
reading audio/video metadata: music-metadata;
WAV/audio utilities: wavefile, node-wav;
TypeScript tooling: typescript, tsx, ts-node;
tests: vitest, jest, playwright/test.

But again:

These packages are not installed automatically. They must be selected for the specific project and specific task.

11. Check the installation

After installing the JavaScript environment, run:

node --version
npm --version
pnpm --version

Check that simple JavaScript runs:

node -e "console.log('Node.js is ready for Claude Code (Codex) automation')"

Check the projects folder:

cd "$HOME/Documents/Claude Code (Codex)"
node --version
pnpm --version

12. Rule

The eleventh setup step:

On macOS, install Node.js LTS, npm, and pnpm. Node.js is not built into macOS. Ask Claude Code (Codex) for the current installation command or link rather than looking randomly online.

Additional rule:

Before working with each JavaScript/TypeScript project, ask Claude Code (Codex) which package manager to use and which exact packages are needed for OpenAI, voice, audio, transcription, images, video, and other project tasks.

This makes the JavaScript environment manageable rather than a collection of randomly installed global packages.

Step 12. Allow Claude Code and developer tools to access the internet on macOS

On Windows, Claude Code (Codex) may be unable to access the internet because of Windows Defender Firewall or other security rules. A similar issue is also possible on macOS, but it works differently.

The main difference:

The built-in macOS Firewall mainly controls incoming connections to the Mac. Outgoing internet issues are more often related not to the macOS Firewall itself, but to VPN, proxy, corporate MDM policies, DNS, antivirus software, network filters, or third-party firewall applications.

Therefore, you need to check several layers on macOS.

1. What should have internet access

For normal operation of the Claude Code (Codex) environment, the following applications and tools need internet access:

Claude Code (Codex) Desktop app;
Claude Code (Codex) CLI;
Terminal.app;
the browser through which login is performed;
Git;
GitHub CLI (gh);
Homebrew;
Node.js/npm/pnpm;
Python/pip;
package managers and dev servers of specific projects.

If one of these tools cannot access the internet, Claude Code work will break with strange errors: packages do not download, login does not work, GitHub does not open, because Claude Code (Codex) cannot use network functions.

2. Check basic internet from Terminal.app

Before configuring the firewall, check that the internet works from the terminal:

curl -I https://www.apple.com
curl -I https://github.com
curl -I https://api.openai.com

If these commands do not get a response, the issue is not Claude Code (Codex) itself. You need to diagnose the network, DNS, proxy, VPN, or corporate restrictions.

3. Check macOS Firewall

Open settings:

Apple menu -> System Settings -> Network -> Firewall

If Firewall is off, the built-in macOS Firewall should not block Claude Code (Codex).

If Firewall is on, open:

Firewall -> Options

And check whether there is an explicit prohibition there for the Claude Code (Codex) app, Terminal.app, the browser, or other developer tools.

If an application is added to the list and has block/deny next to it, change the rule to allow.

Important:

You do not need to turn off the firewall completely without a reason. First, allow the specific application or service.

Strict rule:

Ask Claude Code how to correctly configure macOS Firewall for Claude Code, Terminal.app, a dev server, or another developer tool. Do not invent settings yourself and do not search for random instructions online.

The correct request:

Claude, I am configuring macOS Firewall for Claude Code and developer tools. Here is a screenshot of the current Firewall/Options settings and a description of the problem. Tell me which applications to allow and which settings to choose.

4. Allow an application through Firewall Options

If the Claude Code (Codex) Desktop app or another needed application is blocked:

Open System Settings.
Go to Network.
Open Firewall.
Click Options.
Add the needed application through +.
Select Allow incoming connections.
Save the settings.

This is especially important for applications that start a local server, dev server, or accept local connections.

5. Outgoing internet: where the real problem usually is

If Claude Code, curl, git, gh, brew, npm, pnpm, or pip cannot connect to the internet, and macOS Firewall does not show an explicit block, you need to check:

whether VPN is enabled;
whether there is a corporate proxy;
whether the Mac is managed through MDM;
whether a third-party firewall is installed: Little Snitch, LuLu, Radio Silence, corporate endpoint security;
whether the domains openai.com, chatgpt.com, api.openai.com, github.com, npmjs.com, pypi.org are blocked;
whether DNS is broken;
whether the network requires captive portal login, for example in an office, hotel, or airport.

On Mac, these layers are more often what block outgoing application connections.

6. Do not guess permissions

If macOS shows a network permission popup, firewall warning, or security prompt, a person must not click at random.

Rule:

Take a screenshot of the popup and send it to Claude Code with a question about what to click.

Example request:

Claude, macOS is showing a network permission for Claude Code/Terminal/dev server. Here is a screenshot. Tell me what to choose so that Claude Code can work with the internet and local dev servers, but without unnecessarily weakening security.

7. Check Claude Code CLI

After configuring the network, check Claude Code CLI:

codex --version

Then run:

codex

If login or a network request does not work, copy the error or send a screenshot to Claude Code (Codex).

8. Check package managers

Check that the main package managers can access the internet:

git ls-remote https://github.com/openai/codex.git
gh auth status
brew update
python3 -m pip index versions openai
pnpm view openai version

If one command fails, do not immediately reinstall the entire tool. Determine which network layer is blocking access.

9. Team standard

For the team, we establish:

Check macOS Firewall, but do not consider it the only cause of network problems.
The Claude Code app, Terminal.app, and developer tools must have network permission.
Look for outgoing blocks more often in VPN/proxy/MDM/third-party firewall.
Send unclear security and firewall prompts as screenshots to Claude Code.

10. Rule

The twelfth setup step:

On macOS, check that the Claude Code (Codex) Desktop app, Claude Code CLI, Terminal.app, Git, GitHub CLI, Homebrew, pip, and pnpm can access the internet. The built-in macOS Firewall usually controls incoming connections, but its Options need to be checked if an application is explicitly blocked.

Additional rule:

If Claude Code or developer tools cannot access the internet, do not disable security blindly. Check Firewall, VPN, proxy, DNS, MDM, and third-party network filters, and send all unclear permission windows to Claude Code as screenshots.

Step 13. Configure PATH on macOS

On Windows, there is a Path variable where folders with programs that should run from the terminal are specified. macOS has the same concept, but it is usually called:

PATH

PATH is a list of folders where the shell searches for commands.

If a command exists on the computer but its folder is not in PATH, Terminal.app and Claude Code (Codex) will not be able to run it properly.

1. Why PATH is important for Claude Code

Claude Code constantly runs commands:

git;
gh;
codex;
python3;
pip;
node;
npm;
pnpm;
brew;
curl.

If a command cannot be found, Claude Code may start looping, suggest workarounds, reinstall unnecessary things, or diagnose the problem incorrectly. This leads to lost time and huge token overspending.

Therefore, after installing every tool, you need to check not only the fact of installation, but also that the command is available from Terminal.app.

2. How to view PATH

Show the current PATH:

echo "$PATH"

A more readable version:

echo "$PATH" | tr ':' '\n'

Each line is a separate folder where the shell searches for executable commands.

3. How to check a specific command

Check whether a command is found:

command -v git
command -v gh
command -v codex
command -v python3
command -v node
command -v pnpm
command -v brew

You can also use:

which git
which gh
which codex
which python3
which node
which pnpm
which brew

If a command is configured correctly, macOS will show a path to the executable file, for example:

/usr/bin/git
/opt/homebrew/bin/brew
/opt/homebrew/bin/node

If a command cannot be found, there will be an error such as:

command not found

or an empty result.

4. Typical PATH folders on macOS

The following paths are common on macOS:

/usr/bin
/bin
/usr/sbin
/sbin
/usr/local/bin
/opt/homebrew/bin

For Apple Silicon Macs, Homebrew is usually located here:

/opt/homebrew/bin

For Intel Macs, Homebrew is often located here:

/usr/local/bin

For the Python installer from python.org, paths like this may appear:

/Library/Frameworks/Python.framework/Versions/3.12/bin

For Node.js installed through a version manager, paths inside the user's home folder may appear.

5. Where PATH is configured in zsh

On modern macOS, the standard shell is zsh.

For zsh, the most commonly used files are:

~/.zprofile
~/.zshrc

But you must not edit them manually without understanding.

Important:

Do not randomly insert lines into .zshrc, .zprofile, .bash_profile, or other shell files.

An incorrect line in PATH can break the terminal, package managers, or result in the wrong Python/Node/Git version being run.

6. Homebrew and PATH

After Homebrew is installed on macOS, it usually shows the command that needs to be added to the shell profile.

On Apple Silicon, it often looks like this:

eval "$(/opt/homebrew/bin/brew shellenv)"

But this line cannot simply be copied for everyone without checking.

The correct action:

take a screenshot or copy the Homebrew installer output -> send it to Claude Code -> run the exact command that Claude Code confirms for the specific Mac

7. What should work after PATH setup

Minimum checklist:

git --version
gh --version
codex --version
python3 --version
node --version
pnpm --version

If Homebrew is installed:

brew --version

If all commands launch from a new Terminal.app window, PATH is configured well enough for Claude Code.

8. After changing PATH, you need to open a new Terminal.app

After editing the shell profile, the old Terminal.app window may not see the changes.

You need to:

Close the current Terminal.app window.
Open a new Terminal.app window.
Run the checks again:

echo "$PATH" | tr ':' '\n'
command -v codex
command -v gh
command -v python3
command -v node
command -v pnpm

9. Do not search for PATH instructions independently

Strict rule:

When configuring PATH on macOS, you need to clearly understand which exact line to add and to which exact file. Ask Claude Code about this rather than searching online or inventing it yourself.

The correct request:

Claude Code, I am configuring PATH on macOS for the Claude Code environment. Here is the output of echo "$PATH", command -v brew, command -v codex, command -v gh, command -v python3, command -v node, command -v pnpm. Tell me whether I need to add anything to ~/.zprofile or ~/.zshrc, and give me the exact command.

If a command cannot be found:

Claude Code, on macOS, the node/pnpm/gh/codex/python3 command cannot be found in Terminal.app. Here is the output of echo "$PATH" and command -v. Help me safely fix PATH.

10. Do not use sudo without a reason

You almost never need to use sudo to configure PATH.

If an internet instruction suggests:

sudo nano /etc/paths

or editing system PATH files, this is a red flag.

For a normal Claude Code environment, user shell files are almost always enough:

~/.zprofile
~/.zshrc

System files such as /etc/paths must not be modified without a clear reason and Claude Code confirmation.

11. Rule

The thirteenth setup step:

On macOS, check that all key Claude Code environment commands are available from Terminal.app through PATH: git, gh, codex, python3, node, pnpm, brew.

Additional strict rule:

Do not configure PATH on macOS at random. Do not search for random commands online, and do not edit .zshrc, .zprofile, or system files without understanding. Always ask Claude Code, show the current PATH, and follow the exact instruction for the specific Mac.

Step 14. Install FFmpeg for working with audio and video

In our work, Claude Code often receives tasks related to audio:

prepare a voice transcription;
split an audio file;
convert a format;
extract audio from video;
check file duration;
normalize or prepare a file for further processing;
use Python and JavaScript tools that need ffmpeg.

Therefore, FFmpeg is a mandatory system tool for the Claude Code (Codex) environment.

1. What is FFmpeg

FFmpeg is a set of command-line tools for working with audio and video.

The most important commands:

ffmpeg
ffprobe

ffmpeg performs conversion, cutting, audio extraction, and other operations.

ffprobe shows technical information about a media file: duration, codecs, tracks, bitrate, sample rate, and other parameters.

2. FFmpeg is not built into macOS

FFmpeg is usually not a standard part of macOS.

It must be installed separately.

Check whether FFmpeg is installed:

ffmpeg -version
ffprobe -version

If the commands cannot be found, FFmpeg must be installed.

3. Do not search for a link or command independently

On Windows, FFmpeg is often installed manually: download an archive through a link, extract it, put it in the root folder of drive C:\, then add the path to Path.

On macOS, the main approach is different. FFmpeg is most often installed through a package manager, usually Homebrew.

Strict rule:

Ask Claude Code for the FFmpeg download link, installation command, and instructions for adding the path. Do not search for random instructions online and do not invent the path yourself.

The correct request:

Claude, I need to install FFmpeg on macOS for working with audio, video, and transcriptions. Tell me the current official/recommended installation method for my Mac and say whether I need to configure PATH.

If installation is manual:

Claude, I am installing FFmpeg manually on macOS. Tell me where to correctly place ffmpeg and ffprobe, and which line to add to PATH for zsh. Here are my current echo "$PATH" and uname -m.

4. Recommended method on macOS

If Homebrew is already installed and working, the recommended method is:

brew install ffmpeg

After installation, check:

ffmpeg -version
ffprobe -version

If the commands work, you usually do not need to add a path separately: Homebrew installs binaries into its prefix, which should already be in PATH.

On Apple Silicon Macs, this is usually:

/opt/homebrew/bin

On Intel Macs, this is often:

/usr/local/bin

5. If Homebrew is not installed

If Homebrew is not installed yet, do not immediately download a random FFmpeg archive.

Ask Claude Code (Codex):

Claude, my Mac does not have Homebrew yet, but I need to install FFmpeg for the Claude Code environment. What is more correct: install Homebrew first or use a manual binary? Give me safe instructions for macOS.

In most cases, the correct path for the team is:

Homebrew first -> then brew install ffmpeg

Manual binary installation is acceptable only if there is a reason not to use Homebrew.

6. Manual installation on macOS

Do not perform manual FFmpeg installation on macOS by default.

If it is needed after all, do not put files in the root of the drive as on Windows.

On macOS, it is better to use a user or standard Unix location, for example:

~/bin

or another folder that Claude Code explicitly confirms for the specific Mac.

After that, the path to the folder must be included in PATH.

But again:

Ask Claude Code exactly where to put ffmpeg and ffprobe, and exactly which line to add to ~/.zprofile or ~/.zshrc, taking the current PATH into account.

7. Check PATH

After installation, check that Terminal.app sees the commands:

command -v ffmpeg
command -v ffprobe

Expected result when installed through Homebrew on Apple Silicon:

/opt/homebrew/bin/ffmpeg
/opt/homebrew/bin/ffprobe

Expected result when installed through Homebrew on an Intel Mac:

/usr/local/bin/ffmpeg
/usr/local/bin/ffprobe

If command -v does not show anything, FFmpeg is installed in the wrong place or the folder was not included in PATH.

Then ask Claude Code:

Claude Code, FFmpeg is installed on macOS, but command -v ffmpeg shows nothing. Here is the output of echo "$PATH", brew --prefix, and ls for the required folder. Help me safely add FFmpeg to PATH.

8. Check operation on a file

After installation, it is useful to check not only the version, but also the actual operation of ffprobe.

Example:

ffprobe -hide_banner path/to/audio-or-video-file

If there is no file yet, this is enough:

ffmpeg -version
ffprobe -version

9. Connection with Python and JavaScript

Some Python and JavaScript packages may use FFmpeg internally:

imageio-ffmpeg;
audio/video processing scripts;
transcription pipelines;
video conversion utilities;
tools that extract audio from video.

It is important to understand:

The Python package imageio-ffmpeg does not eliminate the need to have system ffmpeg if the project or Claude Code scripts expect the command-line commands ffmpeg and ffprobe.

Therefore, checking ffmpeg -version is mandatory.

10. Do not use sudo without a reason

When installing through Homebrew, you usually do not need to use sudo manually.

If a random instruction suggests:

sudo cp ffmpeg /usr/bin
sudo nano /etc/paths

this is a red flag.

You need to stop and ask Claude Code.

11. Rule

The fourteenth setup step:

To work with audio, video, and transcriptions on macOS, install FFmpeg and check the ffmpeg and ffprobe commands.

Recommended path:

brew install ffmpeg

Additional strict rule:

Always ask Claude Code for the FFmpeg download link, installation command, and PATH instructions. Do not search for random instructions online, do not put files in system folders, and do not add paths at random.

Step 15. Install a text editor for Markdown and YAML

A good text editor is mandatory for the Claude Code (Codex) environment on macOS.

Its purpose is not to replace an IDE or become the main programming tool. Its purpose is simpler and more important:

quickly open a Markdown file;
quickly open a YAML file;
read the structure of a document;
edit text, headings, lists, configs;
see syntax highlighting;
not break encoding;
not turn plain text into rich text;
not add invisible formatting.

1. Why TextEdit is not enough

macOS has built-in TextEdit, but we do not consider it a sufficient editor for the Claude Code (Codex) environment.

The reason: TextEdit is designed not only for plain text, but also for rich text. This increases the risk of accidentally breaking Markdown, YAML, or a configuration file.

Our work requires a plain-text editor specifically.

2. Main formats

The editor must confidently work at minimum with:

.md
.markdown
.yaml
.yml
.txt
.json
.toml
.env

Especially important:

Markdown
YAML

Markdown is needed for instructions, documentation, prompts, handoff files, product docs, and Claude Code (Codex) materials.

YAML is needed for configs, CI/CD, GitHub Actions, docker-compose, automation files, and infrastructure descriptions.

3. Best practice editors on macOS

Normal options for macOS:

CotEditor
Sublime Text
BBEdit
Visual Studio Code

CotEditor

A good free macOS-native plain-text editor.

Suitable as a basic option for the team if a simple, fast, and understandable editor for Markdown/YAML is needed.

Sublime Text

A very fast professional editor.

Suitable as a paid or trial-based option for those who are used to Sublime instead of Notepad++.

BBEdit

A classic professional macOS text editor.

Good for large text files, search, plain text, Markdown, HTML/XML, and technical texts.

4. Recommended standard for the team

Minimum standard:

CotEditor

Extended standard:

CotEditor + Visual Studio Code

Paid/professional alternative:

Sublime Text or BBEdit

The main point:

A Mac must have at least one normal plain-text editor that quickly opens Markdown and YAML.

5. Do not search for a link independently

Strict rule:

Ask Claude Code (Codex) for the text editor download link and installation method. Do not search for random download sites online.

The correct request:

Claude, I need to install a text editor on macOS for Markdown and YAML in the Claude Code environment. Tell me the official download source for CotEditor/Sublime Text/BBEdit and the best option for my task.

If the person has already selected an editor:

Claude, I want to install Sublime Text/CotEditor/BBEdit on macOS. Give me the official download source and check which build to choose for Apple Silicon or Intel Mac.

6. Installation

Possible safe sources:

the editor's official site;
Mac App Store;
official Homebrew cask, if the team already uses Homebrew.

You must not download editors from random download sites, mirrors, "free cracked," "portable build," and similar sources.

If installation is through Homebrew, also ask Claude Code for the command:

Claude, can the selected text editor be installed through Homebrew cask on macOS? Give me a safe command and the official source.

7. Check after installation

After installation, check:

The editor opens.
You can open .md.
You can open .yaml and .yml.
Syntax highlighting is visible.
The file is saved as plain text.
The editor does not add rich-text formatting.

Test files:

test.md
test.yaml

YAML example:

name: codex-macos-setup
tools:
  - codex
  - git
  - homebrew

Markdown example:

# Claude Code macOS setup

- Markdown works
- YAML works

8. Configure file opening

After installation, you can configure a default editor for .md, .yaml, .yml.

But this does not need to be done identically for everyone.

If you need to make an editor the default application, ask Claude Code:

Claude, I want to make CotEditor/Sublime Text/BBEdit the default editor for .md, .yaml, and .yml on macOS. Give me step-by-step instructions through Finder.

9. Do not install unnecessary extensions without checking

If VS Code or another editor with extensions/plugins is used, you must not install random extensions.

Rule:

Install extensions for Markdown, YAML, GitHub, OpenAI, formatting, and preview only after checking with Claude Code (Codex).

Reason: extensions have access to project files and can affect security, formatting, and editor behavior.

10. Rule

The fifteenth setup step:

A plain-text editor for quickly working with Markdown and YAML must be installed on macOS. The minimum recommended option is CotEditor. Professional alternatives are Sublime Text or BBEdit. VS Code can be used as a heavier code editor.

Additional strict rule:

Ask Claude Code about the download link, installation method, Apple Silicon/Intel build choice, and default editor configuration. Do not download editors from random download sites and do not install extensions without checking.

Step 16. Install Obsidian for product Markdown documents

If you do product work, an ordinary text editor can quickly become insufficient.

There are many Markdown files. Folders, subfolders, drafts, translations, handoff files, source of truth, call notes, product theses, ADRs, vision documents, and other materials appear.

In an ordinary text editor, it can quickly become confusing:

where the required file is located;
which version is current;
which documents are connected to each other;
where the product Data folder is located;
what belongs to the project and what belongs to an old draft;
which files are ready and which are still in progress.

For this, Obsidian is needed.

1. What is Obsidian

Obsidian is a local application for working with Markdown files and a knowledge base.

Important:

Obsidian works locally.
Obsidian works on top of a regular folder containing Markdown files.
Obsidian does not turn your documents into a closed web format.
Obsidian does not require mandatory authorization for basic work.
Obsidian is free to use.

It is not a web service, not SaaS, and not a replacement for GitHub/Google Drive/Confluence.

It is a local shell for conveniently working with your folder of Markdown documents.

2. First superpower: see the structure of product files

Obsidian can be connected to your product folder, for example:

~/Documents/Claude/Product/Data

or to another folder containing the product knowledge base.

After that, Obsidian shows:

the file tree;
folders;
Markdown documents;
connections between notes;
fast search;
Markdown preview;
convenient navigation.

This is especially important for product work, where you need not just to open one file, but to understand the entire document structure.

3. Second superpower: parallel editing with AI

Obsidian is very convenient for joint work between a person and AI.

Scenario:

Obsidian is open on one side.
A person manually edits a Markdown document in it.
Claude Code/Codex/AI interface is open on the other side.
The person asks AI to change the same document: replace a term, rewrite a block, structure a section, clean up repetition, translate text, or bring the file to a template.
The change appears in the file.
Obsidian immediately shows the updated document.

This feels almost like jointly editing a document with a person and AI.

Task examples:

Claude Code (Codex), replace the term MetaSites with Metasites in this document.
Claude Code (Codex), bring this Markdown to the Source of Truth structure.
Claude Code (Codex), move all questions for Dima into a separate section.
Claude Code (Codex), check that YAML frontmatter is not broken.
Claude Code (Codex), make a Russian translation next to the English one, without losing structure.

For product work, this is very effective.

4. Third superpower: Obsidian plugins

Obsidian has a developed plugin system.

Plugins can help:

organize the knowledge base;
work with tables;
improve search;
build dashboards;
connect documents;
work with templates;
improve navigation;
manage tasks.

But you do not need to install Obsidian plugins all at once immediately.

Strict rule:

At the start, use Obsidian as a local Markdown workspace. Install plugins later, only if it is clear which task they solve.

Before installing a plugin, ask Claude Code (Codex):

Claude, I want to install an Obsidian plugin for my product base of Markdown files. Explain whether I need it, whether it is safe, and which specific task it solves.

5. Fourth capability: knowledge graph

Obsidian has graph view: a visual graph of connections between documents.

A knowledge graph can be built, and it looks interesting.

But the honest current position:

We have not yet learned how to use graph view effectively in everyday product work.

Therefore, graph view can be explored, but it should not be considered a mandatory part of the basic workflow.

For us, the following are more important now:

folder structure;
fast search;
convenient Markdown editing;
parallel work with AI;
keeping documents as regular local .md files.

6. Installing Obsidian

Obsidian must be downloaded only from an official source.

Strict rule:

Ask Claude Code (Codex) for the Obsidian download link and installation method. Do not search for random download sites.

The correct request:

Claude, I need to install Obsidian on macOS to work with a product Markdown base. Give me the official download source, tell me which build to choose for Mac, and explain how to connect the local Data folder as a vault.

For macOS, the official installer is usually downloaded from the Obsidian website, after which the application is moved to Applications.

7. How to connect the product folder

In Obsidian, a working folder is called:

vault

For product work, the vault must point to an existing folder with Markdown files.

For example:

~/Documents/Claude/Product/Data

or:

~/Documents/Claude/<project>/Data

You do not need to create a random new vault if you already have a working folder with documents.

Ask Claude Code (Codex):

Claude, help me choose the correct Obsidian vault folder for my product work. Here is the structure of ~/Documents/Claude. I want to edit product Markdown files and not break the connection with GitHub/Confluence.

8. Obsidian and Git

Obsidian edits regular files on disk.

If this folder is a Git repository, Obsidian changes will be visible through:

git status
git diff

This is convenient, but requires discipline.

Rule:

Before mass AI editing of documents in Obsidian, check git status to understand which changes already exist.

9. Obsidian does not replace Confluence

Obsidian is convenient only for local work with Markdown.

Confluence is needed for publishing, collaborative reading, corporate access, and agreed pages.

The correct combination:

Obsidian = local editing and Markdown structure
Claude Code (Codex) = AI editing and automation
GitHub = versioning and synchronization
Confluence = publishing and corporate consumption

10. Rule

The sixteenth setup step:

If you do product work, install Obsidian as a local shell for Markdown documents and connect it to the correct Data folder or other product knowledge base.

Additional strict rule:

Download Obsidian only from the official source that you request from Claude Code (Codex). Choose the vault consciously: it must point to the correct local document folder rather than create a new random structure.

Step 17. Install an IDE or code editor, but do not make it the main AI interface

After installing a plain-text editor for Markdown and YAML, you can install a full code editor: VS Code, Cursor, or an equivalent.

It is important to distinguish the terms carefully.

VS Code, Cursor, Windsurf, and similar applications are often called IDEs, but technically many of them are closer to:

code editor / AI code editor

A full IDE usually includes a heavier set of built-in capabilities: project system, debugger, profiler, GUI builders, language-specific tooling, and so on. But in everyday speech, developers often call VS Code and Cursor an IDE. In this instruction, the general term can be used:

IDE / code editor

1. An IDE is needed, but it is not the first or main step

In old developer habits, installing VS Code, Cursor, or another IDE is often considered the first and main step in setting up a computer.

This is no longer the case in the Claude Code (Codex) environment.

An IDE is needed for:

reading and editing code;
navigating a project;
syntax highlighting;
working with Git diff;
locally running scripts;
debugging;
TypeScript/Python/React/Node.js workflows;
targeted manual file edits.

But an IDE should not be the main interface for communicating with AI.

2. Why the main AI interface is the Claude Code (Codex) GUI

Our work with Claude Code (Codex) is not based only on text.

We constantly use:

voice messages;
large verbal task descriptions;
screenshots of errors;
screenshots of interfaces;
AI questionnaires;
images and layouts;
files;
sequential dialogue;
result verification;
explaining context in ordinary human language.

The Claude Code (Codex) GUI is more convenient for this mode because it is better suited for conversing with the agent, transferring screenshots, voice context, and files.

An IDE/code editor is good inside code, but worse as the primary conversational interface for AI vibecoding.

3. Harsh new reality

Developers are used to thinking:

first install an IDE -> then start working

For Claude Code (Codex) work, it is more correct to do this:

first prepare macOS, Claude Code, terminal, Git, Homebrew, Python, Node.js, PATH, and media tools -> then install an IDE/code editor as an additional working tool

An IDE is no longer the center of all development.

The center of the AI vibecoding workflow is Claude Code (Codex) and a correctly prepared environment.

4. Why AI work should not be conducted only through an IDE

We do not prohibit VS Code, Cursor, and equivalents.

But we strongly do not recommend building all AI work only through an IDE, because:

voice input in an IDE is usually less convenient than in a specially organized Claude Code (Codex) workflow;
working with screenshots and images can be less fast;
it is not always convenient to provide a large amount of context by voice;
it is not always convenient to hold a long product or architectural dialogue;
an IDE encourages immediately diving into code rather than first formulating the task correctly;
a developer starts arguing with the agent at file level instead of first providing full context, definition-of-done criteria, and constraints.

Yes, modern editors are evolving. VS Code has Copilot Chat, extensions, voice/speech capabilities, and image inputs. Cursor positions itself as an agent-first editor. But this does not cancel our team rule right now:

IDE/code editor is a tool for working with code. Claude Code (Codex) GUI is the main interface for task setting, voice communication, screenshots, files, and agent work.

5. Which IDE/code editor to install on macOS

Normal options:

Visual Studio Code
Cursor
Windsurf
JetBrains IDEs

For our team, the basic option is:

Visual Studio Code

If a person already uses Cursor, they can install Cursor, but should not turn it into the team's only AI interface.

JetBrains IDEs make sense for specific stacks: Java, Kotlin, backend, mobile, heavy refactoring. But they are not mandatory for the basic Claude Code (Codex) environment.

6. Do not download an IDE from random sources

Strict rule:

Ask Claude Code (Codex) for the VS Code, Cursor, or other IDE/code editor download link. Do not search for an installer online yourself.

The correct request:

Claude, I need to install VS Code/Cursor on macOS for the Claude Code environment. Give me the official download source, tell me which build to choose for Apple Silicon or Intel Mac, and what to check after installation.

If installation is through Homebrew:

Claude, can VS Code/Cursor be installed through Homebrew cask on macOS? Give me a safe command and the official source.

7. What to check after installation

After installing the IDE/code editor, check:

The application opens.
You can open the project folder from `~/Documents/Claude.
Project files are visible.
.md, .yaml, .json, .ts, .js, .py open.
The terminal inside the editor sees the commands:

git --version
python3 --version
node --version
pnpm --version
codex --version

The editor does not break line endings, encoding, and YAML indentation.

If the IDE's built-in terminal does not see commands but the regular Terminal.app does, the issue is with shell/PATH inside the IDE. This must be shown to Claude Code (Codex).

8. Extensions and plugins

Do not install many extensions right away.

Minimally useful categories:

Markdown;
YAML;
Git/GitHub;
Python;
JavaScript/TypeScript;
formatter/linter only for a specific project.

Strict rule:

Install extensions only after checking with Claude Code and only for a specific task. Do not install random AI/extension packs.

Reason: extensions have access to the workspace, files, terminal, environment variables, and sometimes tokens, and must be only official versions and safe. Installing an unknown extension can lead to a vulnerability on your desktop.

9. How to explain this to developers

Wording for the team:

We are not taking VS Code or Cursor away from you. You can use them to read and edit code.

But the team's main AI workflow goes through the Claude Code (Codex) GUI, because it is faster and more natural there to set tasks by voice, attach screenshots, provide files, discuss architecture, and verify results.

The IDE remains a tool for manual work with code. The Claude Code (Codex) GUI becomes the main interface for working with the AI agent.

This is not a matter of taste. It is a matter of speed, context quality, and reducing the number of errors.

10. Rule

The seventeenth setup step:

On macOS, you can and should install an IDE/code editor, usually VS Code or Cursor. But the IDE is not the team's main AI interface. The main AI vibecoding interface is the Claude Code (Codex) GUI.

Additional strict rule:

Download the IDE only from the official source that you request from Claude Code (Codex). Install extensions carefully and only after checking. If the IDE terminal cannot see git, python3, node, pnpm, or codex, do not fix it at random; show Claude Code (Codex) the command output and current PATH.

Step 19. Why all this setup is needed

After completing all the previous items, the user has a properly configured macOS environment for working with Claude Code, Codex, and other AI development tools.

This instruction is needed not for formality and not because of a love of installing software.

It is needed to make AI vibecoding fast, predictable, safe, and economically reasonable.

1. Do not make AI develop missing tools

If Git, Python, Node.js, pnpm, FFmpeg, GitHub CLI, Xcode Command Line Tools, or another basic tool is not installed on the computer, the AI agent starts spending time not on the task but on fixing the missing environment.

This leads to bad scenarios:

Claude Code (Codex) tries to replace a missing tool with a temporary script;
Claude Code starts looking for workarounds;
the agent suggests unnecessary installations;
the task expands;
token spend increases;
execution time grows;
the final cost of the work becomes many times higher.

It is important that your Claude Code may not tell you about a missing tool during vibecoding, and you will never know about it. But you will observe the AI agent working on solving endless problems for a very long time.

The correct conclusion:

Basic tools must be installed in advance. AI must not spend working time inventing what should be part of the environment.

2. Do not make AI fight access and permissions

A poorly prepared Mac can break Claude Code (Codex) work not because of an error in code, but because of the environment:

no administrator rights;
old macOS;
updates are not installed;
Terminal.app cannot see commands;
PATH is broken;
firewall or VPN blocks the network;
GitHub CLI is not authorized;
Google APIs are not enabled;
FFmpeg cannot be found;
Python packages are installed globally and conflict;
Node.js packages were installed with the wrong package manager;
the IDE terminal sees a different environment.

Under such conditions, AI starts fighting not the task, but the computer.

This makes AI vibecoding slow, expensive, and unpleasant. It often leads to disappointment that AI is stupid and works poorly.

It is important that your Claude Code may not tell you about a missing access permission during vibecoding, and you will never know about it. But you will observe the AI agent working on solving endless access problems for a very long time.

The correct conclusion:

The environment must be configured so that Claude Code (Codex) can immediately read files, run commands, download dependencies, work with GitHub, audio, video, Python, Node.js, and Google APIs.

3. Protect against looping

One of the most expensive problems in AI development is looping.

Looping occurs when the agent tries again and again to solve the same infrastructure problem:

a command cannot be found;
a package cannot be installed;
PATH was not updated;
permissions do not allow reading or writing a file;
a network request is blocked;
an API is not enabled;
credentials do not work;
a compiler is missing;
FFmpeg cannot be found;
Python/Node versions conflict.

Every such cycle consumes:

user time;
tokens;
money;
attention;
trust in the AI tool.

It is important that if your Claude Code gets into a loop during vibecoding, it will not tell you about the real problem; you may only be able to guess it from the message context.

The correct conclusion:

Good preliminary environment setup protects against Claude Code or Codex looping.

4. Why order matters

The installation order is not random.

You cannot start with an IDE and hope that everything else will appear by itself.

The correct sequence reduces the number of errors:

macOS -> admin account -> Claude Code (Codex) -> Terminal/zsh -> screenshots -> Xcode Command Line Tools -> Git -> Homebrew -> GitHub CLI -> Python -> Python packages -> Node.js/pnpm -> network/firewall -> PATH -> FFmpeg -> text editor -> IDE -> plugins -> Google APIs

If you violate the order, you can get strange errors:

Git is installed, but compiler tools are missing;
Homebrew is installed, but brew is not in PATH;
GitHub CLI is installed, but there is no GitHub account;
Python packages are installed into the wrong Python version;
Node.js exists, but pnpm does not work;
FFmpeg is installed, but Claude Code (Codex) cannot see it;
Google API credentials exist, but APIs are not enabled.

5. Economic meaning

These rules save:

time;
money;
tokens;
nerves;
team working hours.

They also improve result quality:

Claude Code (Codex) is distracted less;
fewer random installations;
fewer version conflicts;
fewer access errors;
fewer network blocks;
less manual panic;
more stable development.

6. Human meaning

The purpose of this instruction is to make working with AI pleasant rather than disappointing.

A poorly configured environment creates the feeling that AI "is being dumb," "is stuck in a loop," "does not know how," "cannot install a package," "does not understand Mac," or "breaks the project."

Often, the problem is not AI.

The problem is that the computer was not prepared for AI vibecoding.

The correct environment changes the feeling of work:

less struggle -> more results
less diagnostics -> more development
less irritation -> more enjoyment from AI

7. Final rule

The nineteenth setup step:

Follow the entire instruction and installation order not for bureaucracy, but to save time, money, and attention. A good environment does not allow Claude Code and Codex to drift into developing missing tools, fighting access, and entering expensive error loops.

Result:

A properly configured Mac makes AI vibecoding faster, cheaper, calmer, and much more pleasant.

Step 20. Configure Claude Code (Codex) plugins and MCP servers

After the macOS environment is configured, you can move on to configuring Claude Code (Codex) itself.

At this stage, it is important to install plugins that connect Claude Code (Codex) to the team's working services: mail, calendar, documents, tasks, repositories, design, and internal systems.

1. What is a plugin in Claude Code (Codex)

In Claude Code (Codex), a plugin is an installable bundle that expands the agent's capabilities.

A plugin can include:

skills;
app integrations/connectors;
MCP servers;
commands;
hooks;
assets;
settings and metadata.

Simplified, you can think of it like this:

plugin = a ready package of capabilities for Claude Code (Codex)

Often, a plugin does indeed contain an MCP server and a set of skills for working with it. But technically, a plugin can be broader than just "MCP server + skills."

2. What is an MCP server

An MCP server is an intermediary layer between the AI interface and an external backend/service.

It lets Claude Code (Codex) work with an external system through tools:

read data;
search data;
create tasks;
update documents;
work with files;
obtain context;
run permitted operations.

Simple formula:

MCP server = a bridge between an AI chat and another product's backend

For example, an MCP server can connect Claude Code (Codex) to:

GitHub;
Gmail;
Google Drive;
Google Calendar;
Jira;
Confluence;
Figma;
an internal backend;
Xolo;
Metasites;
any other product that has an MCP interface.

3. Plugins and MCP are not the same thing

It is important to distinguish:

Plugin
MCP server
Connector/App integration
Skill

A plugin is a packaging of capabilities.

An MCP server is one way to give Claude Code (Codex) tools for working with an external service.

A skill is an instruction or workflow that teaches Claude Code (Codex) how to correctly perform a specific type of task.

A connector/app integration is an authorized connection to a service such as Google Drive, Gmail, Calendar, GitHub, or Atlassian.

In everyday speech, you can say "Gmail plugin" or "GitHub plugin," but it is important to understand that there may be a set of different components inside.

4. Which plugins are needed first

For our product, corporate, and development work, the basic set is:

Google services
Atlassian Rovo
GitHub
Figma

Google services

Needed for working with:

Gmail;
Google Calendar;
Google Drive;
Google Docs;
Google Sheets;
Google Slides.

These plugins/connectors allow Claude Code (Codex) to help with mail, calendars, documents, files, spreadsheets, and presentations.

Atlassian Rovo

Needed for working with:

Jira;
Confluence;
tasks;

Important: the correct plugin name for Jira is Atlassian Rovo

GitHub

Needed for development coordination:

repositories;
issues;
pull requests;
review comments;
CI;
GitHub Actions;
draft PR;
development handoff scenarios.

Figma

Needed for working with design:

read design context;
create or update layouts;
work with components;
build screens;
prepare a design-to-code workflow;
work with FigJam/Slides, if required.

Figma is not a mandatory plugin for every person, but it is very effective for product and design-related work.

5. Where to install plugins

In the Claude Code (Codex) app, open the section:

Plugins

Then:

Find the required plugin.
Open its details.
Click install/add.
If the plugin requires connecting an external service, complete authorization.
After installation, start a new thread or restart the working session if Claude Code (Codex) requires it.

In Claude Code (Codex) CLI, plugins can be opened through:

/plugins

7. Authorization is mandatory

After installing most working plugins, you need to authorize.

This is normal: authorization gives the plugin access specifically to your data in a particular service.

Examples:

the Gmail plugin must get access to Gmail;
the Google Calendar plugin must get access to the calendar;
the Google Drive plugin must get access to Drive/Docs/Sheets/Slides;
the GitHub plugin must get access to GitHub;
Atlassian Rovo must get access to the Jira/Confluence workspace;
the Figma plugin must get access to Figma files.

Without authorization, a plugin may be installed but will not be able to work with real data.

8. Authorization security

Authorize plugins only:

on a secure work computer;
in the correct work account;
for services you actually use;
understanding which permissions are granted;
without granting unnecessary access.

If the authorization window shows scopes/permissions that are unclear, take a screenshot and ask Claude Code (Codex).

The correct request:

Claude, I am authorizing a plugin for Gmail/Google Drive/GitHub/Atlassian/Figma. Here is a screenshot of the permissions. Explain what exactly I am allowing and whether it is safe for the work task.

9. Direct connection of MCP servers

Not all external systems come as ready marketplace plugins.

Sometimes, you need to connect an MCP server directly through Claude Code or Codex settings.

Examples:

Xsolla MCP server;
Metasites MCP server;
a specific product's MCP server;
a custom backend;
a local MCP server for development.

Rule:

If an MCP server is not an official marketplace plugin, connect it only according to the exact instructions of the server owner and after checking with Claude Code (Codex).

10. Do not connect unknown plugins and MCP servers

Plugins and MCP servers can gain access to work data.

Therefore, you must not:

install random plugins;
connect unclear MCP endpoints;
grant permissions without understanding;
use personal accounts instead of work accounts;
connect corporate services from an unsecured computer;
store tokens/secrets in open files.

11. Correct request to Claude Code (Codex)

Before installing a plugin:

Claude, I need to configure plugins for a working Claude Code environment. I use Gmail, Google Calendar, Google Drive, Jira, Confluence, GitHub, and Figma. Tell me which official plugins to install, in what order, and which authorization steps to expect.

Before connecting an MCP server:

Claude, I need to connect an MCP server to Claude Code. Here is documentation or an endpoint from the server owner. Check security, explain which tools it will provide, and tell me how to connect it correctly in settings.

12. Rule

The twentieth setup step:

After configuring the macOS environment, configure Claude Code (Codex) plugins: Google services, Atlassian Rovo, GitHub, Figma, and other work integrations that the person actually needs.

Additional strict rule:

Authorize every plugin in the correct work account and understand which permissions it receives. Connect MCP servers only from trusted sources, according to the owner's instructions, and after checking with Claude Code (Codex).

Step 21. Configure AGENTS.md, skills, and the project folder structure

After configuring plugins, connectors, and MCP servers, you need to configure the behavior of Claude Code/Codex itself inside your projects.

Three big topics:

AGENTS.md
skills
correct folder structure

This is no longer operating system installation. It is configuring how the AI agent will understand your work, your rules, your projects, and your team processes.

1. AGENTS.md — general rules for the AI agent

AGENTS.md is an instruction file for Claude Code (Codex).

It defines persistent rules:

how to work with the project;
which commands to run;
which files not to touch;
which checks are mandatory;
how to format the result;
how to work with Git;
how to approach security;
which project agreements to follow.

Simplified:

AGENTS.md = behavior rules for Claude Code (Codex) in your workspace

2. Global and project AGENTS.md

There are different levels of rules.

Global file:

~/.codex/AGENTS.md

It sets the user's personal rules for all projects.

Project file:

<project-root>/AGENTS.md

It sets rules for a specific project or repository.

More specific rules may exist inside subfolders:

<project-root>/services/payments/AGENTS.md
<project-root>/apps/web/AGENTS.md

Claude Code (Codex) reads instructions from the general level to the more specific level. Therefore, rules closer to the current project folder can clarify or override more general rules.

3. AGENTS.md requires separate configuration

You cannot write AGENTS.md randomly.

It is not a place for lengthy philosophy and not a place for conflicting wishes.

A good AGENTS.md should be:

short;
specific;
verifiable;
connected to real project commands;
understandable for AI;
useful for recurring tasks.

Example topics for AGENTS.md:

Use pnpm if pnpm-lock.yaml exists.
Check git status before changes.
Do not commit secrets.
After changing Python scripts, run pytest if tests exist.
After changing frontend, run lint/build if commands are available.
Do not add new production dependencies without confirmation.

4. Skills — reusable workflows

Skills are reusable workflows for Claude Code (Codex).

A skill can contain:

SKILL.md;
instructions;
reference files;
scripts;
templates;
assets.

Simplified:

skill = a repeatable working skill that Claude Code (Codex) can invoke

For example:

uploading Markdown files to Confluence;
working with a service desk;
task triage;
generating a status report;
publishing Product documents;
processing a transcript;
preparing Jira tickets;
working with internal pipelines.

5. Why skills save time

If you perform a similar operation every day, it should be turned into a skill.

Example:

upload a file to Confluence

Without a skill, Claude Code (Codex) has to understand from scratch each time:

where the file is located;
which script to use;
which credentials are needed;
how to perform a dry run;
how to check the result;
which errors are typical;
how not to break publishing.

With a skill, this becomes a stable workflow.

Result:

Skills save time, reduce errors, and make Claude Code (Codex) resemble not a random assistant, but a trained team member.

6. Where skills are located

For project skills:

<project-root>/.agents/skills

For a user's personal skills:

~/.agents/skills

Other managed locations may be used for team or system skills.

Important:

Skills must be installed and stored consciously. Do not copy random skills without understanding what they do.

7. Company skills and Neuronet

If the company already has ready-made skills, they should be used.

Especially useful:

skills for uploading files to Confluence;
skills for service desks;
skills for Jira;
skills for Confluence;
skills for internal workflows;
skills for recurring product/documentation tasks;
skills for Neuronet scenarios.

This is not decoration. It is a huge time saving.

Rule:

If the company has a ready skill for a task, use the skill first rather than asking Claude Code (Codex) to reinvent the process every time.

8. Correct folder structure

In addition to AGENTS.md and skills, you need to configure folders correctly.

The most important combination:

local project folder
folder/workspace in Claude Code or Codex
GitHub repository

These three layers must point to the same project.

If they diverge, problems begin:

Claude Code (Codex) works in the wrong folder;
the GitHub repo does not correspond to local files;
AI changes the wrong project;
AGENTS.md instructions are not loaded;
skills are in the wrong location;
Git status shows the wrong changes;
the pull request goes from the wrong branch;
the team does not understand where the current version is.

9. Recommended structure

Basic projects folder on a Mac:

~/Documents/Claude

Inside it:

~/Documents/Claude/AI
~/Documents/Claude/Product
~/Documents/Claude/project-a
~/Documents/Claude/project-b
~/Documents/Claude/product-docs

For first team onboarding, two starting folders are especially useful:

~/Documents/Claude/AI
~/Documents/Claude/Product

AI is for Claude Code setup, AI instructions, handoff documents, training, and working materials on AI processes.

Product is for the product base, Markdown documents, PRDs, specifications, transcripts, and files that can sync with GitHub and Confluence.

Each project folder must correspond to its GitHub repository or explicitly be a non-code workspace.

Example:

~/Documents/Claude/my-app
  .git/
  AGENTS.md
  .agents/skills/
  package.json
  README.md

Claude Code/Codex must be opened exactly in the project folder, not in a random parent folder.

10. Onboarding a new participant: folders, Claude Code (Codex), and GitHub

For a new team member, the order should be as follows:

Open Documents.
Create the Claude Code (Codex) folder.
Inside it, create the AI and Product starting folders or other folders that the team agreed on in advance.
In Claude Code/Codex, create a project not "from scratch," but through the Use Existing Folder, Open Existing Folder, or analogous button for selecting an already existing folder.
Select a specific project folder, for example ~/Documents/Claude Code (Codex)/Product, not all of Documents.
Do not write random files into a new team folder before initial population from a GitHub repository, an approved template, or an already existing source of truth.
Get access to the corporate GitHub account and the required repository. For team work, it is usually specifically a corporate account, not personal GitHub.
Ask the repository owner to add the user as a collaborator or grant access through the organization.
Connect the local folder to the GitHub repository through a Git remote or a correct clone.
Authorize GitHub CLI and the GitHub plugin in Claude Code (Codex) if they are used in the work.
Check that the local folder, Claude Code (Codex) workspace, and GitHub repository point to the same project.

Main idea:

First create the correct folder, then open exactly it in Claude Code, then connect it to GitHub. Do not create parallel copies of a project in different locations.

If a local folder has already been created, choose the existing folder specifically in Claude Code. If you start creating new projects without binding them to the real folder, chaos will appear very quickly: Claude Code will work in one directory, GitHub will be connected to another, and the person will look for files in a third.

11. Chat and agent discipline inside a project

In Claude Code and Codex, a chat inside a project is not just random correspondence. In practice, each chat begins to behave like a working agent with a particular function.

Therefore, for serious work, you cannot mix all topics into one chat.

Good examples of separate chats:

Claude Code setup
GitHub Updates
Product docs
Confluence upload
Lessons
Bug triage

Bad practice:

One chat simultaneously for Claude Code setup, GitHub sync, product decisions, bugs, transcripts, and personal notes.

In ordinary ChatGPT, a mixed chat may still be tolerable. In Claude Code/Codex, it quickly becomes harmful because the AI agent starts connecting unrelated contexts, tasks, folders, and rules to each other.

Rule:

Every work chat must have a clear function. If a new major topic appears, it is better to create a separate chat within the same project than to break the current context.

A separate example of an important chat:

GitHub Updates

Such a chat can be used only for tasks of synchronizing the local folder with GitHub: check changes, make a commit, prepare a pull request, pull updates, check repository status. This protects the team from a situation where GitHub operations are spread across random conversations.

12. Checking the folder linkage

Before serious work, you need to check:

pwd
git status
git remote -v
ls

Understand:

where am I;
is this the correct project or not;
is there a Git repo;
which GitHub remote is connected;
is AGENTS.md visible;
is .agents/skills present;
are there uncommitted changes that cannot be lost.

If there are doubts, ask Claude Code (Codex):

Claude, check that my local project folder, Claude Code workspace, and GitHub repository are connected correctly. Here is the output of pwd, git status, and git remote -v.

13. Do not mix work folders

You must not maintain the same project simultaneously in several uncoordinated folders:

~/Downloads/project
~/Desktop/project
~/Documents/Claude/project

This almost guarantees confusion.

Rule:

Each project must have one primary local folder, one clear Claude Code (Codex)/Claude Code workspace, and one GitHub repository.

14. What to configure through Claude Code

These topics must not be configured at random.

Ask Claude Code (Codex):

Claude, help me configure AGENTS.md for this project. First read the README, package.json/pyproject, folder structure, and existing commands. Then propose a short AGENTS.md.

Claude, which company skills do I need to install for working with Confluence, Jira, service desk, and Product docs?

Claude, check the project folder structure and connection to GitHub. Tell me where AGENTS.md should be located and where project skills should be located.

15. Rule

The twenty-second setup step:

After installing plugins and MCP, configure AGENTS.md, skills, folder structure, and work-chat discipline. This defines the AI agent's behavioral rules, connects reusable workflows, and protects against confusion between the local folder, Claude Code/Codex workspace, and GitHub repository.

Additional strict rule:

Do not configure AGENTS.md, skills, folder structure, and GitHub linkage at random. First ask Claude Code to read the project, check the GitHub linkage, and propose minimal, precise rules for the specific work.

Step 1. Up-to-date macOS and a macOS account with administrator rights

1. Use a modern macOS

2. Install all available macOS updates

3. Work from the primary administrator account

Rule

Step 2. Install Claude Code and create a working project folder

1. Where to store Claude Code projects on macOS

2. Install Claude Code CLI

3. Install the Claude Code desktop app

4. What the basic structure on a Mac should look like

5. Rule

Step 03. Terminal and command line on macOS

1. What is the equivalent of PowerShell 7 on macOS

2. Is the built-in Terminal.app enough

4. When it is worth installing iTerm2

6. What every team member should be able to do

7. Rule

Step 04. Screenshots on macOS for working with Claude Code

1. Is a separate screenshot tool needed

2. The main requirement

3. Basic macOS hotkeys

4. Best practice for the team

5. Rule

Step 05. Xcode Command Line Tools on macOS

1. Xcode Command Line Tools on macOS

2. Is this included in macOS by default

3. How to check installation

4. How to install Xcode Command Line Tools

5. Full Xcode is usually not needed

6. Connection with Node.js and pnpm

7. Do not search for instructions independently

8. Do not fix developer tools at random

9. Rule

Step 06. Install and configure Git

1. Is Git included in macOS by default

2. Do not search for a Git link independently

3. Do not guess installer checkboxes

4. Recommended Git installation path on macOS

5. Basic Git configuration

6. Git must work from the Claude Code projects folder

7. What else is important for Claude Code (Codex)

8. Rule

Step 07. Install Homebrew

1. Homebrew is not included in macOS

2. Why install Homebrew after Git

3. Do not search for the installation command independently

4. Installation

5. PATH after installing Homebrew

6. Check the installation

7. What can be installed through Homebrew

8. Do not use random sudo

9. Rule

Step 08. Install GitHub CLI

1. First, a GitHub account is needed

2. Do not search for the installation command independently

3. Check the installation

4. Authorize in GitHub

5. Check authorization

6. Check operation in the Claude Code projects folder

7. macOS specifics

8. Rule

Step 09. Install Python on macOS

1. Python is mandatory

2. Do not search for a link independently

3. Which Python version to install

4. Built-in Python in macOS

5. Where to install Python on macOS

6. Recommended installation method

7. Check after installation

8. Virtual environments

9. What to do if the version does not match

10. Rule

Step 10. Install must-have Python packages

1. Packages are installed not globally, but in a virtual environment

2. Compatible pinned package set

3. Create a requirements file

4. What these packages do

5. macOS specifics

6. soundfile and libsndfile

7. webrtcvad may build from source

6. `soundfile` and libsndfile

7. `webrtcvad` may build from source

8. `torch` on macOS