#The chatspace lifecycle

A chatspace isn't always "on." It moves through a few states, and understanding them explains why it starts fast, why it stops on its own, and what's kept when it does.

#The states

State What's happening
Preparing The machine is coming up: claiming a box, cloning your repo, installing the agent CLI, starting it.
Running The agent is live. You can Open in Claude / Codex and work. Your live links are reachable.
Off Stopped — by you or by idle stop. Your files and branch are preserved; resume any time.
Needs sign-in The agent is up but waiting for you to sign in (first use, or your saved login expired).
Broken Setup or start failed. The app shows the reason; usually you can retry or delete and recreate.

#Create

You pick a repo and branch, choose Claude or Codex, write a kickoff prompt, and (optionally) choose an environment and an idle-stop timeout. Tap Create.

If you choose a new branch, Chatspaces creates a chatspaces/… branch for you so your work stays isolated from your main branch. The branch becomes real on GitHub the first time the agent pushes to it.

#Provision

Chatspaces brings up your machine and gets it ready:

  • Claims a cloud box (often a pre-warmed one, so this is quick).
  • Clones your repo onto it using a scoped GitHub token.
  • Installs and starts the agent CLI (Claude Code or Codex).
  • Injects any environment secrets you selected.

The first time you use an agent, this is also where you'll be asked to sign in.

#Run

Once running, the agent fires your kickoff prompt once and gets to work. From here you:

  • Open in Claude / Codex to talk to the agent in its own app.
  • Answer any prompts (permissions, pickers) that Chatspaces surfaces natively in-app.
  • Run your app and get a live preview link.
  • Commit and push your work, or open a PR.

The kickoff prompt runs once — resuming later won't repeat it.

#Idle & stop

Chatspaces watches for activity. After a stretch with nothing happening, it auto-stops the machine so you're not spending usage on an idle box. You can also stop it yourself any time.

Stopping does not lose your work — your repo, branch, uncommitted changes, and installed tools all stay on the machine. See idle stop to tune the timeout (or turn it off for a chatspace).

#Resume

Tap Resume, or just Open in Claude / Codex. The machine wakes — usually in about a second — and the agent reconnects to the same conversation. No re-cloning, no re-signing-in (if your login was saved), no lost state.

#Delete

When you're truly done, delete the chatspace. This tears down the machine and removes it for good.

Heads up

If the chatspace has uncommitted changes or unpushed commits, the app warns you and asks you to confirm before deleting — once it's gone, that work is gone. Commit and push first if you want to keep it (just ask the agent to do it).

#What persists across stop/resume

Persists while off Lost only on delete
Repo, branch, and uncommitted changes Everything on the machine
Installed packages and tools The machine itself
The agent conversation / session
Your environment selection and idle settings

Next: signing in to Claude & Codex, or how to drive a chatspace from the apps.

← Previous Quickstart Next → Signing in to Claude & Codex