Projects

A project is where Amp keeps everything about one codebase: the repository, the threads that work on it, and the settings that every orb for that code shares. When you start a thread in a project, Amp knows which repository to clone, which secrets to provide, how big the orb should be, and how to ship the result.

You can work without a project. A thread with No Project gets a clean orb and no repository, which is fine for research or one-off scripts. For anything that touches a codebase, create a project once and every thread after that starts ready to work.

A project page showing the project name and description, recent commits to main, recent threads, and the repository files

The project page shows recent commits, the threads that worked on the repository, and a file browser. From the header you can clone the repository, open the project settings, or start a new thread.

Create a Project

Open Projects and click New Project. Pick where the code comes from and who owns the project. The Orbs getting started guide walks through the dialog step by step.

Repository

A project can use a repository from three places:

  • GitHub. Connect GitHub in your integration settings and pick a repository. Amp uses that connection to clone private repositories into the orb. Public GitHub repositories work without connecting.
  • Another Git host. Paste the HTTPS URL. Public repositories work as they are. Private repositories need clone credentials in the project’s environment. See Configure Git.
  • Amp. Choose Start From Scratch and Amp creates and hosts a blank repository for you. Clone it to your machine with amp clone owner/project-name, where owner is your username or the workspace name.

Owner

A project belongs to you or to your workspace. A workspace project is visible to every member of the workspace, and members can start threads in it. A private project is visible only to you. You can move a private project into a workspace later with Change Owner in the project settings, but not the other way around.

Threads and Projects

Every thread belongs to at most one project, and the project page lists them. Amp assigns the project when the thread starts:

  • In the web app, the composer shows the current project next to the executor. Click it to pick a different project, choose No Project, or create a new one.
  • In the CLI, amp -ox looks at the Git remotes of the current directory and picks the project whose repository URL matches. Pass --project when more than one project matches.
  • When one agent starts another with Agent to Agent, it names the project the new thread runs in, so you can hand work to a different repository.
The new thread composer with the project picker open, showing No Project, the calc project, and a Create Project action

If your repository is reachable under more than one URL, for example a mirror or an SSH remote, add the other URLs as Git Remote Aliases in the project settings so the CLI matches them too.

Project Settings

Open the settings from the gear icon on the project page. The settings are grouped into tabs.

The Project Settings dialog on the Overview tab with fields for name, icon, description, Git repository, Ship Behavior, Commit Author, and Public Read-Only Code Access

Overview

  • Name, Project Icon, and Description identify the project in lists and in the composer.
  • Git Repository is the repository Amp clones into every orb. Add Git Remote Aliases for other URLs that point at the same repository.
  • Commit Author decides who appears as the Git author of commits the agent makes. Amp uses Amp as the author and adds the thread creator as a co-author. Thread Creator uses the person who started the thread.
  • Public Read-Only Code Access appears for Amp-hosted repositories. It lets anyone on the internet clone the repository and read its files. Threads stay private.
  • Change Owner moves a private project into a workspace. Delete Project removes the project and lets you choose what happens to its threads.

Ship Behavior

Ship Behavior picks the main action in the Changes pane of every thread in the project:

  • Ship asks the agent to commit whatever is uncommitted and push to the base branch.
  • Push to Branch asks the agent to commit and push the current branch. On GitHub, the thread shows a link to open a pull request.
  • Custom Ship sends a prompt you write instead. Use it when your team has its own flow, such as opening a pull request with a template or running a release script.

See Shipping Changes for what each option asks the agent to do and how to write a custom Ship prompt.

For automatic pull requests, add “Create pull requests with gh pr create, embedding public artifact URLs of screenshots or videos in the PR description” to your AGENTS.md. gh is preinstalled and authenticated in orbs.

Orb

  • Orb Size sets the default machine for new orbs in the project. Each thread can still pick a different size when it starts. See Sizes & Costs.
  • Pre-clone Script and Pre-setup Script run before Amp clones the repository and before .agents/setup. Amp stores them outside the repository, so use them for things that do not belong in the code, such as installing a credential helper. See Customizing Orbs.
  • The tab also shows whether the repository has .agents/setup and .agents/resume, and lets you delete the cached snapshot when you need a setup change to apply right away.

Secrets & Env Vars

Values you add here are available as environment variables in every orb for the project. Mark passwords and tokens as secrets so Amp hides them after you save. Project values override workspace values with the same name, and your personal values override both. See Handling Secrets.

Webhooks

For Amp-hosted repositories, the Post-receive Webhook sends a JSON POST to a URL you choose after every successful push. Use it to notify a CI system or a chat channel. To have an outside service wake an orb instead, see Event-Driven Orbs.

Permissions

Every member of a workspace can start threads in the workspace’s projects. Changing the settings of a workspace project takes the project’s creator or a workspace admin. A private project can be used and changed only by its owner. Public read-only access to an Amp-hosted repository lets others clone and read the code, but not start threads or see them.

Manage Projects with Puck

You can ask Puck to change a project’s name, repository URL and aliases, Ship Behavior, commit author, or orb size. Puck uses your permissions, so it can change only the projects you could change yourself.