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 and to push as you. Public GitHub repositories work without connecting. See GitHub & Git.
  • Another Git host. Paste the HTTPS URL. Public repositories work as they are. Private repositories need clone credentials. See Other Git Hosts.
  • 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.

You can also create either kind of project from the CLI. Pass a repository to map an existing GitHub repository or another Git repository:

amp projects create acme/widgets
amp projects create https://git.example.com/acme/widgets

Use --amp-hosted with a name to start with a blank repository hosted by Amp:

amp projects create --amp-hosted --name widgets

To move a repository that only exists on your computer into an Amp-hosted project, run --push from inside it. Amp creates the project, adds its clone URL as the origin remote (pass --remote <name> to use another name), and pushes your current branch. The project name defaults to the directory name.

cd myproject
amp projects create --push

After that, git push and git pull talk to the Amp-hosted repository, and orbs start from whatever you pushed.

Amp creates projects in your current workspace by default when you have one. Pass --personal or --workspace to choose the owner.

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.

To replace a project’s additional repositories from the CLI, repeat --additional-repository for each HTTPS URL. You can select up to 20 repositories in one update.

amp projects update acme/widgets \
  --additional-repository https://github.com/acme/api \
  --additional-repository https://github.com/acme/docs

Run amp projects update acme/widgets --clear-additional-repositories to remove them all. Use --repository-url <url> to change the primary URL of a mapped repository or migrate an Amp-hosted project to an external repository. This changes the repository Amp clones but does not copy Git data, so push the Amp-hosted repository to the external repository first. Add --repository-mode github to link the URL as a GitHub repository, or --repository-mode mapped to treat a GitHub-linked project as a plain Git URL. See Repository Linking.

Run amp projects update acme/widgets with no update options to refresh a GitHub-connected project’s repository metadata from GitHub. This picks up repository renames and transfers using the repository’s stable GitHub ID. It does nothing for mapped and Amp-hosted projects.

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.
  • Git Identity decides who appears as the author of commits made in orbs. Personal projects let you use your Amp account or another verified identity. Workspace admins can require Amp, require each member’s Amp Account, or let each member choose with User Choice. See Commit Identity.
  • 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. Kept threads are archived and stay readable, but they are read-only and can never be unarchived. amp projects delete always keeps threads this way.

Repository Linking

Every project has one primary Git repository, which Amp clones into every orb. The project links to it in one of three ways:

  • A GitHub repository. The project is linked to a specific repository through your GitHub connection. Amp tracks it by its GitHub ID, so if the repository is renamed or transferred, the project follows it to the new name.
  • An Amp-hosted repository. Amp hosts the repository.
  • A Git URL. The project stores the URL and clones whatever is there. This works for any Git host, including GitHub repositories you have not connected.

To change which repository a project points to, edit the URL in the Git Repository field. For a project linked to a GitHub repository, open the menu next to the repository and choose Treat as Standard Git Repository, enter the new URL, and then choose Treat as GitHub Repository to link it to the new repository.

Changing the repository does not move threads, orb snapshots, or Git data. Existing threads keep the repository they were created with.

Git Remote Aliases are used to map local CLI threads to this project. When you run the CLI in a Git checkout, it matches the checkout’s remote URLs against the project’s repository URL and its aliases, so add an alias for each other URL your clones use, e.g., a mirror or an SSH remote. Remove aliases that point at a repository the project no longer uses.

Additional Repositories to Clone are other repositories that every orb in the project checks out next to the primary repository, under ../repos/. Use them when work spans more than one repository. See Customizing Orbs.

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 after orb activation, when the agent runs.

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. You can also list snapshots with amp projects snapshots list <project> and delete them with amp projects snapshots delete <project>.

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.