Developer Setup for Starter Projects

How to use Claude Code and Codex in a starter project. Where to put a project folder on a Mac, what goes in it, and how to organize and plan work with an AI agent.

Many people only know AI for its web browser chat, for questions and answers, but that misses AI's full usefulness. Claude Code and Codex are more than chatbots; they know how to use the Mac as a computer, better than most experts. You can use AI agents for workflows that require reading and writing files, including software development, as well as anything else that you'd do on a computer. But first, you need to know how to set up a project.

With web browser chat, AI's context (its memory and attention) is limited to the chat session. But you can set up files and folders as a project and give AI a persistent, lasting context for your work. AI can update and save project files as you work, so AI's context is complete and current for every new session. This is the expert's way of working with AI.

The "Set Up Your Mac" apps give you starter projects to practice on, and this page explains how to use the starter projects. With these examples, you'll know how to set up a project folder of your own.

Starting a project is part of setting up a Mac for AI coding. See the full Mac setup roadmap.

Tools you'll need

A project folder is an ordinary folder on your Mac. Claude has a Projects feature, which runs work in the cloud (see "Project folders and Claude Projects" below), but here a "project" just means a folder with files and subfolders on your Mac.

You can view project folders and files in Finder, Apple's file browser, though files whose names start with a dot, such as .gitignore and the .claude folder, are hidden until you show hidden files on Mac.

All of these tools can be installed from the "Set Up Your Mac" apps.

Install and use AI desktop apps:

Claude Desktop, from Anthropic (use its Code tab for projects; it needs a paid Claude plan), described in Claude Code and Claude Desktop Compared
The ChatGPT desktop app, from OpenAI (choose Codex from the dropdown at the top for projects); see ChatGPT for Mac to install it

Or, if you prefer to work within a terminal application:

Claude Code (the command-line version); see Install Claude Code on Mac
Codex CLI; see OpenAI's Codex CLI page to install it

You'll also need Git, to save versions of your project. It comes with the Xcode Command Line Tools.

You'll need an editor to view and edit Markdown files. For simplicity, download and install a Markdown editor. If you already use a code editor such as Zed or VS Code, you can use it to view and edit Markdown files. You can use Apple's TextEdit if you haven't installed a better editor, but don't use Microsoft Word as its hidden formatting codes interfere with plain text. If you use TextEdit, turn off smart quotes in TextEdit > Settings, or it changes straight quotes to curly ones, which breaks commands and code.

How it works

An AI agent such as Claude Code or Codex works in the folder you open it in, whether you start it there in a terminal application or choose the folder in a desktop app. It can read and edit the files there and run commands in that folder. Before your first prompt, it reads the project's instruction file, CLAUDE.md or AGENTS.md, which tells it how the project works (see Developer Setup for Agent Instructions).

The agent remembers almost nothing from one session to the next. This is why project files are so important. Each time you start it, it knows what it reads in the folder and little else. Even within one session, its working memory (its context) fills up on a long task, and then it starts to lose track of earlier decisions. That's why a good project folder holds more than code. It keeps the instructions, the plan, and notes on what was done, so the next session can pick up where the last one stopped.

The "Set Up Your Mac" apps set up a starter project, in addition to installing Claude Code and Codex. This article explains what the app gives you, where to keep a project folder, how to open it in your agent and what to ask first, and how to plan, save and record your work. It is one topic in "Set Up Your Mac", my guide to setting up a Mac for software development.

Starter projects in the "Set Up Your Mac" apps

On its Starter Project screen, the "Set Up Your Mac" app offers to create an example project, with instruction files for your AI agent. Everyone gets a simple practice project. If you have some coding experience, you get a coding project too:

AI-Simple-Project - a practice folder for trying an AI agent on a page of rough notes. You don't need to know how to code.
AI-Coding-Project - a small coding project laid out for spec-driven development (explained below). The app offers it to anyone who says they have written code, or whose Mac already had developer tools when the app started.
Python-Example-Project - a small Python project that uses uv to manage its packages, offered on a separate screen of the "Set Up Your Mac for Python" app.

Click "Install in Documents" and the app puts each project in its own folder in your Documents folder, such as ~/Documents/AI-Simple-Project. Click "Choose my folder…" to put them in a folder you choose instead, anywhere in your home folder (see "Where to put a project folder" below). The app never writes into a folder that already exists, so it can't overwrite your files. When setup is done, click "Show Example Projects" to see them in the Finder.

Each project has a "Start here" README.md with prompts to try, an AGENTS.md that holds the instructions for your agent, and a CLAUDE.md that is a single line pointing Claude Code to AGENTS.md. It also has a .gitignore file, which keeps secrets out of Git, and a few agent skills for the project. The coding project adds numbered folders for plans, research, decisions, specifications and procedures, a changelog, and a one-file Python program. It is the same layout I use for my own projects, scaled down.

The app doesn't put the projects under Git. Do that before your agent changes anything (see "Git for a project folder" below).

Where to put a project folder

I recommend keeping your projects in a folder named Projects in your home folder (~/Projects), with one folder inside it for each project. The "Set Up Your Mac" app doesn't like to create new home folders on your Mac, so it uses the existing Documents folder unless you choose another folder. However, Documents has two drawbacks for code, so you may want to create a new home folder such as ~/Projects:

macOS protects the Documents folder. The first time a terminal application or an AI agent opens a file there, macOS asks whether to allow it, in a message that starts with the app's name, such as "Terminal" would like to access files in your Documents folder. If you click "Don't Allow", commands in the folder fail with "Operation not permitted" until you turn access back on in System Settings > Privacy & Security > Files & Folders. Don't turn on Full Disk Access to stop the question.
iCloud may sync the Documents folder. If "Desktop & Documents Folders" is turned on in your iCloud settings (it may have been turned on when you first set up your Mac), iCloud uploads every file in your projects, which is a problem for big projects. Developers report that iCloud syncing damages Git's records of a project, and that it stalls on the thousands of small files that coding tools create.

A folder you make directly in your home folder, such as ~/Projects, has neither problem. Many developers keep their code in a folder of this kind, and some name it workspace or code or Developer (the Finder conveniently uses a hammer icon for a folder named Developer).

To use it for the app's starter projects, make the folder before you click a button in the app. In the Finder, choose Go > Home, then File > New Folder, and name the folder Projects. Then click "Choose my folder…" in the app and choose Projects. If the app already put the projects in Documents, you can move them to your Projects folder in the Finder.

Don't open your home folder itself as a project, in a terminal application or in a desktop app. The agent could then reach every file you have. In a terminal, Claude Code also doesn't remember your answer to its trust question there, so it asks every time.

Names that start with a dot, such as .gitignore and .claude, are hidden in the Finder. Press Command + Shift + . (period) in a Finder window to show them. See Show Hidden Files on Mac.

Open a project in Claude Desktop

Claude Desktop's Code tab runs Claude Code in a window, so you can work in a project folder without a terminal. It is the same Claude Code as the command-line version, and it reads the same CLAUDE.md, skills and settings, so a project works the same way in both. The Code tab needs a paid Claude plan (Pro, Max, Team or Enterprise). Here's how to open a project folder in Claude Desktop:

Open Claude Desktop and click Code at the top of the window.
In the row under the prompt box, click the first control (the environment selector) and choose the top entry under Local, so Claude works on your Mac.
Click the project folder control beside it, choose Open folder…, and select your project folder, such as AI-Simple-Project in your Projects folder.
Check the permission mode in the same row (see below), then type your prompt and press Return.

The mode selector, in the row under the prompt box, sets what Claude may do without asking you first:

Manual - Claude asks before it edits a file or runs a command, and shows each change for you to accept or reject.
Accept edits - Claude edits files without asking, but still asks before it runs most commands.
Plan - Claude explores the project and proposes a plan, without editing your files.
Auto - Claude works without asking, while a separate check blocks actions that look risky.

While you're learning what Claude does, you can choose "Manual" to get a warning of every change before it happens. Claude Desktop remembers the mode you choose for each folder, except "Plan," which lasts for one session.

When Claude changes files in "Auto" or "Accept edits" mode, a count of added and removed lines, such as +12 -1, appears. Click it to see each change, file by file. You can click a line to comment on it, and Claude revises the code to match your comments.

The slash command (type / in the prompt box) gives you quick access to Claude Code's built-in commands and agent skills. To run a command yourself, click Terminal in the session's title bar, which opens a terminal panel inside Claude Desktop, already in the project folder.

Each conversation in the Code tab is a session, with its own folder and history. You'll see sessions listed in the sidebar, with names created by the AI agent. Click an earlier session to continue it, or click + New (Command + N) to start another. The sidebar may also show Projects, Anthropic's cloud feature described in "Project folders and Claude Projects" below. A folder you open with Open folder… isn't an Anthropic cloud project.

You can use the Code tab and a terminal on the same project, even at the same time. In a terminal application, claude --desktop opens the Code tab on the folder you're in.

To install Claude Desktop, see Anthropic's Get started with the desktop app, and see Claude Code and Claude Desktop Compared for how the two differ. Codex works the same way in the ChatGPT desktop app (ChatGPT for Mac). Click Add new project beside Chats in the sidebar (or press Command + O), choose the folder, and start a Codex chat that runs Local.

Open a project in a terminal application

Here's how to work in a project folder with the command-line version of Claude Code or Codex. In a terminal application, move into the folder with cd, then start your agent. For the practice project in a Projects folder, run:

$ cd ~/Projects/AI-Simple-Project
$ claude

Type codex in place of claude to use Codex. If the project is somewhere else, such as ~/Documents/AI-Simple-Project, use that path instead. To open a terminal application already in a folder you see in the Finder, see How to Open Terminal on Mac.

The first time you start Claude Code in a folder, it asks you to confirm that you trust the folder. Answer yes for your own projects. Codex may ask the same, and it suggests a read-only setting for a folder that isn't under Git.

In a terminal, Claude Code starts in auto mode, where it works without asking while a separate check blocks actions that look risky. To approve every edit and command yourself while you learn what it does, start it in Manual mode instead:

$ claude --permission-mode manual

In Codex, type /permissions to change what it may do without asking, such as switching to read-only while you plan.

Type your prompt and press Return. Type / to see the agent's commands, and type /exit when you're done. To continue later, run claude -c in the same folder, and Claude Code picks up the most recent conversation there. In Codex, codex resume continues an earlier chat.

First prompts in a new project

To get started on a project, ask your agent about the folder. Ask what is in it and what the agent can help you do there. It reads the agent instructions in AGENTS.md when the session starts, then looks through the files it needs.

Tell the agent you're new to AI projects or coding, and ask it to explain what it plans to do before it changes anything. Then give it one small, real task whose result you can check yourself, such as tidying a page of notes or adding one feature to a small program.

When the agent gets something wrong that will come up again, tell the agent what it did wrong, then ask it to add one line about it to AGENTS.md. When you start a new session, the agent will know not to make the same mistake. Keep the file short, because the agent reads every line of it in every session, and it consumes context.

What to tell the agent before it starts

For anything bigger than a small change, tell the agent three things before it starts: what to do, the limits it must stay within (such as "don't change the template" or "don't delete anything"), and how you'll know it is done. The last part matters most. Turn it into a check the agent can run itself, such as a test, a build, or a script that compares the result with what you expect. Anthropic's best practices for Claude Code put this advice first, because with a check it can run, the agent fixes its own mistakes until the check passes, and you read the result instead of finding each mistake yourself.

You don't need plan mode for this. Plan mode (type /plan in Claude Code or Codex, or choose Plan in Claude Desktop's mode selector) adds a reminder to each of your messages not to write code yet. Boris Cherny, who works on Claude Code and came up with plan mode, wrote in September 2026 that he no longer uses it, because the newest models plan as they work. It still works when you want to read and correct a plan first, and Anthropic still suggests planning when you're unsure of the approach, when a change touches several files, or when you don't know the code. When the agent has finished, ask it to explain what it changed and what it assumed, so you can check the result itself.

To keep Claude Code working until the check passes, type /goal and the condition, such as /goal all tests in test/auth pass and the lint step is clean, or stop after 20 turns. After each turn, a separate model reads the conversation and decides whether the goal is met, so write the condition as something the agent's own output can show, and include a limit so it can't run on indefinitely. Codex has a /goal command too.

For a larger idea, Anthropic suggests asking the agent to interview you about what you want, then to write the answers down as a short specification in a Markdown file. A specification (a spec) says what the program should do and how you'll know it is done. Writing one before the agent builds, and keeping it in the project as the record of what was agreed, is called spec-driven development. It is the method the app's AI-Coding-Project teaches. An approach without spec files is called "vibe coding", which is asking an agent for code with no plan and accepting whatever it writes. Andrej Karpathy, who coined the term "vibe coding", calls it "not too bad for throwaway weekend projects," but serious projects need files for specs and work history. For how the method works, and the tools built for it, see Spec-Driven Development.

Personally, I don't use the /plan command shortcut, and I begin every project with preliminary planning, asking the agent to create research files, decision records, specifications, and playbooks or plans to guide the work. The agent helps me clarify what I want, then follows its own guidance (recorded in the project files) to stay on track.

Git for a project folder

Git is a tool for save-as-you-go version control, a mainstay for software developers but increasingly used by non-programmers as well. As you work, you periodically ask for a commit, a snapshot of the project you can go back to, so you can undo anything the agent did. With AI agents, you no longer need to know all the complex commands for using Git. Just tell the agent to "git commit" whenever you want to save your work in progress as a version you can go back to.

That matters more than it used to, because Claude Code in a terminal now starts in auto mode, approving most actions on its own instead of asking you each time, so you might want to revert to earlier work if the agent messes up.

The starter projects aren't under Git when the app creates them, so ask your agent to set up Git for the project and make a first commit, or follow the Git articles to do it yourself. As a general rule, put every project folder under Git before your agent changes anything, and save your work with a commit before and after each task.

The "Set Up Your Mac" apps give you the option of setting up GitHub with your email address and authorization credentials. GitHub is a website that stores a copy of your Git projects online, so you have a backup off your Mac and can work on it from another computer or share a project with teammates. The app saves your name and email in Git's settings, so each commit records who made it. It also installs GitHub's command-line tool, gh, and signs you in to GitHub in your web browser, so you or your agent can send (push) your commits to GitHub without typing a password. The app never sees your GitHub password, and if you don't have a GitHub account yet, it links to GitHub's sign-up page.

If you're set up for GitHub, prompt your AI agent to "commit and push" periodically. It will "take a snapshot" of your work in progress and save it offsite to GitHub for safekeeping.

Notes that carry over between sessions

Because the agent forgets almost everything between sessions, you should save work history records in the project folder as you progress.

Git's history is a record that the agent can access. But its details are limited, so I like to ask the agent to write changelog entries and work ledger notes.

At a minimum, I recommend asking the agent to keep a changelog file. Tell the agent to update the AGENTS.md file to ask if you want a changelog entry every time you tell it you are finished with a work session. A changelog lists what changed and when, and a rule in the AGENTS.md file encourages the agent to help you stay disciplined about keeping a changelog.

You can also ask for a short handoff note that says what you were working on, what is done, and what comes next. I ask my agents to write to a work ledger folder with a short handoff file after every work session. Ask the agent to write a skill named preserve-our-work which updates a changelog and writes a work ledger handoff note. This is the most effective trick to create project memory for your agents.

As you work, develop a rhythm for your work. Ask the agent to "commit and push" whenever you've got something you want to save. Then, when you're taking a break or starting a new task, type /preserve-our-work (in Codex, $preserve-our-work), or just say "preserve our work", to trigger the skill. Your agent gets a breadcrumb trail of everything you've done together in the project, so any new session with the same agent (or a different one) will have deep knowledge of the project.

Anthropic and OpenAI recommend the same habit for their own agents. Anthropic's engineers have each session read a progress file and the Git log before it starts work (Effective harnesses for long-running agents). An OpenAI team keeps its plans and design documents in the project, with a short AGENTS.md that points to them (Harness engineering). The app's example AI-Coding-Project shows a changelog and a folder of handoff notes, with skills that help the agent write them.

How to create a new project folder

When you start a project of your own, make a new folder for it in your Projects folder. Use a short name with no spaces, which is easier to type in a terminal. You can make the folder in the Finder, with File > New Folder, then open it in Claude Desktop with Open folder….

In a terminal application, use the mkdir command to create a folder, and the Projects folder too if you don't have one yet:

$ mkdir -p ~/Projects/my-project

Then move into it and start your agent:

$ cd ~/Projects/my-project
$ claude

You can reach the same folder in your file system with Claude Desktop, ChatGPT, Claude Code, or Codex in the terminal.

What goes in a project folder

A new project needs only a few files to start. Here's what to add, at a minimum:

A README - README.md says what the project is and how to run it, for you and for the agent.
Agent instructions - put them in AGENTS.md, and make a CLAUDE.md file containing the single line @AGENTS.md, so Claude Code and Codex read the same instructions. See Developer Setup for Agent Instructions for what to write.
A .gitignore file - it lists the files Git should leave out, such as a .env file of secrets and the folders that tools generate.
A folder for the code - such as source/ or src/.
A place for plans and notes - a folder of specs (short documents that say what to build, explained in Spec-Driven Development), a changelog and handoff notes (see above).

To see the folder structure I recommend, read the Spec-Driven Development article, which shows two example folder structures, the app's AI-Coding-Project and a larger layout for projects that run for months, and explains what goes in each folder and how it guides the agent.

Hidden folders named .claude and .agents hold the project's own skills for Claude Code and Codex (see Developer Setup for Agent Skills). Once the project has some files, type /init in Claude Code or Codex, and the agent writes a first instruction file from what it finds. Review it and cut what you don't need.

Keep API keys and passwords out of the project folder, so they never end up in Git or in a file you share. The starter projects' instructions tell the agent to keep API keys in a .env file in your home folder (~/.env), and their .gitignore leaves out any .env file in the project.

Starter templates

You'll find many ready-made starting points for Claude Code online, often called templates. They come in several kinds: installers that add files to a project, whole projects to copy, plugins for Claude Code, and collections of files to copy by hand. Before you use one, read what it adds, especially scripts and hooks (commands the agent runs automatically), because they run with your permissions. Many templates are built around CLAUDE.md for Claude Code (before Claude began reading AGENTS.md), so Codex doesn't read their instructions unless you add an AGENTS.md.

Project folders and Claude Projects

In this article, a project folder always means a folder on your Mac. But "AI projects" can mean other things.

Anthropic relaunched a feature named Projects in September 2026, and it is a different thing from a project folder on your Mac. A Claude project is one conversation in which Claude runs several tasks at once, mostly on Anthropic's computers in the cloud, working on GitHub repositories or on copies of files you upload. It is in claude.ai, Claude Desktop's Code tab and the Claude mobile app, but not in Claude Code in a terminal. Adding a folder to a Claude project uploads a copy of at most 100 of its files, and leaves out hidden files such as .gitignore and the .claude folder. Changes you make on your Mac don't reach that copy.

OpenAI uses the word in two ways too. In the ChatGPT app, a ChatGPT project groups chats and files in the cloud, while a local project is a folder on your Mac that Codex can work in.

Safety in a project folder

An AI agent can edit, move and delete files, so set up each project to limit the damage a mistake can do:

Open the agent in the project folder, never in your home folder.
Commit to Git before and after each task, so you can undo any change.
Learn which actions your agent takes without asking (in Claude Desktop, check the mode selector), and don't give it more freedom until you know what it does.
Keep API keys and passwords out of the project folder and out of Git.
Don't put other people's personal data in an app you built with an agent until a developer has reviewed it.

The section "Use an AI coding agent safely" on the "Set Up Your Mac" page explains more.

Getting work done with your computer and agents

Setting up a project folder is where you begin to use your Mac as a computer, and not just a glorified phone, with agents helping. An AI agent works on your own files, keeps notes for its next session, and saves each step in Git, so you can build anything, beyond what commercial apps offer you. Most days you'll still use your Mac's apps as before. Open a project folder when you want something an app can't give you, such as a tool for your own work, a small website, or a program that solves one problem. Start with the practice project, then make a folder for your first idea of your own.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.