Spaces

A Space is where your team plans and directs work, usually in one Amp project. You chat with Amp in the Space, and Amp starts threads that do the work in parallel. Each thread shows up in the chat as a live card, so everyone can see who is on what as it happens.

Create a Space

Click New Space in the sidebar’s Spaces section and fill in:

  • Name: shown in the sidebar and at the top of the Space.
  • Goal (optional): what the work is for. Amp keeps the Space’s threads directed toward it.
  • Project (optional): the project the Space’s threads run in. Choose No Project for work that needs no repository, such as research or planning. See Spaces without a project.
  • Shared with: who in your workspace can see the Space and chat in it.
  • Slack Channels (optional): channels whose @Amp requests go to the Space. See Ask from Slack.

Then click Create Space. You can change all of these later in Edit Space.

To create a Space from the CLI, run amp spaces create with its name. It prints the Space’s URL; add --json to also get its ID:

amp spaces create "Checkout v2" --project acme/web --goal "Get checkout under 2 seconds" --shared-with workspace

--project, --goal, and --shared-with (workspace or only-me) are optional, as in New Space. Slack channels are linked in Edit Space.

To start a thread in a Space from the CLI, add --space with the Space’s URL or ID to an execute mode command, such as amp -ox --project acme/web --space T-… "Fix the coupon rounding bug". The new thread joins the Space as soon as it is created, under the same rules as bringing in a thread: you must own the Space, or it must be shared with you with multiplayer on, and the thread must be shared at least as widely as the Space. With amp threads continue <thread> -x, --space adds that existing thread instead.

The Space’s owner can move it to another project, or to No Project, in Edit Space. The list shows the projects of the Space’s workspace, plus your personal projects while the Space is shared with no one, because nobody else can use them. Threads Amp starts after the change run in the new project, and threads it already started keep theirs. Amp is told about the change.

Spaces without a project

A Space without a project belongs to your current workspace. When Amp starts a thread for it, the thread runs in an orb with no repository checked out, and the thread is shared like the Space. When you ask for work in one of your projects, e.g., “fix the login bug in acme/web”, Amp starts that thread in the project you named.

Some parts of a Space depend on its project:

  • Ship. A thread with no repository has nothing to ship. Archive it when its work is done. A thread Amp started in a named project ships as usual.
  • Progress. The chart counts each thread as described in Track progress, using the thread’s own commits.
  • Space instructions. A project’s Space instructions, set in the project’s settings, apply only to Spaces in that project. A Space without a project uses your workspace’s Puck instructions.

Work in a Space

  • Ask in the chat. Post a request, a bug, or an idea. Amp answers, or starts a thread for each piece of work and posts it as a card that shows the thread’s live status and whether it needs someone.
  • Open a thread. Click a card to open the thread beside the chat. Read the result, try it, keep iterating with the agent there, and ship it.
  • Bring in a thread you started elsewhere. Ask the Space to add it, with its link or ID. You can also ask Puck, or the thread itself, to ask the Space for you. The thread must be yours and shared at least as widely as the Space; if it isn’t, the Space asks you to share it first. Once added, it shows in the Space’s thread list, and while the Space is multiplayer, the Space’s members can prompt it too. The threads it started come with it. To add a thread another thread started, add the thread that started it, even if that thread is already in the Space. A thread already in another Space can’t be added.
  • Ask from Slack. Link Slack channels to the Space in New Space or Edit Space. When someone mentions @Amp in a linked channel, the request goes to the Space, which starts the threads. Other messages, including bot posts, don’t reach the Space. Only a Space shared with the whole workspace can link channels, and only public channels Amp is in, in a Slack workspace connected to your Amp workspace.
  • Talk with your team. Teammates the Space is shared with post in the same chat and steer the work. Comment on a message to discuss it among people; Amp does not read comments until someone mentions @amp in one.

To talk instead of type, start the Space’s Huddle.

Sharing and its limits

A Space shared with your workspace or with groups has multiplayer on, so the people it is shared with can chat in it. A Space set to Only You does not. Change it under Shared with in Edit Space.

A shared Space can:

  • Start threads only in orbs or on runners shared with the workspace, not on your personal runners. Its threads are multiplayer too.
  • Message, and get reports from, only threads that everyone in the Space can see and that have multiplayer on. It still answers requests from Slack in their Slack threads.
  • Add only threads shared at least as widely as the Space itself.

Track progress

Under the Space’s Goal, a chart shows the Space’s threads over the last 30 days, including threads added to it. Click a day to list that day’s threads. The chart counts each thread in one of these ways:

  • Shipped. The thread’s work landed. A thread counts as shipped when its commits are on the default branch, when its GitHub pull request is merged, or when its Ship archived it. Amp finds a thread’s commits by their Amp-Thread-ID trailer, so commits made while amp.git.commit.ampThread.enabled is off do not count. Amp sees commits reach the default branch only in Amp-hosted repositories, in GitHub repositories with the Amp GitHub App installed, and in GitLab projects with Push Updates installed. Commits pushed to other hosts, such as Bitbucket or a self-hosted Forgejo or Gitea server, do not count.
  • Archived. The thread was archived without shipping, e.g., research or business work that finished with nothing to commit.
  • Open. The thread is neither shipped nor archived yet. The line shows how many threads were open at the end of each day.

When you finish a thread that has nothing to ship, archive it. It then counts as archived and leaves the open count.

When the Space’s repository is on a host where Amp can’t see commits land, the chart shows Done instead of Shipped and Archived, and counts every archived thread as done. Archive a thread when its work has landed. On GitLab, installing Push Updates brings back the Shipped count.