Local environments
Local environments let you configure setup steps for worktrees as well as common actions for a project.
You configure your local environments through the Codex app settings pane. You can check the generated file into your project's Git repository to share with others.
Codex stores this configuration inside the .codex folder at the root of your
project. If your repository contains more than one project, open the project
directory that contains the shared .codex folder.
Setup scripts
Since worktrees run in different directories than your local tasks, your project might not be fully set up and might be missing dependencies or files that aren't checked into your repository. Setup scripts run automatically when Codex creates a new worktree at the start of a new thread.
Use this script to run any command required to configure your environment, such as installing dependencies or running a build process.
For example, for a TypeScript project you might want to install the dependencies and do an initial build using a setup script:
npm install
npm run build
If your setup is platform-specific, define setup scripts for macOS, Windows, or Linux to override the default.
Actions
Actions are helpful to keep you from typing common actions like triggering a build for your project or starting a development server. For one-off quick debugging you can use the integrated terminal directly.
<CodexScreenshot alt="Project actions list shown in Codex app settings" lightSrc="/images/codex/app/actions-light.webp" darkSrc="/images/codex/app/actions-dark.webp" maxHeight="400px" class="mb-4 lg:mb-0" />
For example, for a Node.js project you might create a "Run" action that contains the following script:
npm start
If the commands for your action are platform-specific, define platform-specific scripts for macOS, Windows, and Linux.
To identify your actions, choose an icon associated with each action.