HappyEngineering
Browse documentation

Happy Desktop docsFeatures

Projects & Workspaces

A project is a folder you pointed Happy at. A workspace is a folder an agent works in. Usually they are the same folder. When two pieces of work would touch the same repository at once, each gets its own workspace: a Git worktree on its own branch, cut from the remote's trunk.

Projects

Importing registers the folder. Happy does not move it, copy it, or initialize Git. AGENTS.md files anywhere in the tree are read by every agent working there and re-read when they change. Your global AGENTS.md applies to every project.

Creating a workspace

  1. Fetch origin and fork the remote trunk. The project folder's checkout, HEAD, and branches are not touched.
  2. Reserve a name, a folder under ~/Happy/Workspaces (macOS) or ~/happy/workspaces (Linux), and a branch worktree/<name>.
  3. git worktree add, in the background.
  4. Copy the files in workspace.sync (a gitignored .env, say) and keep them current whenever the project root's copy changes.
  5. Run workspace.setup_commands, such as pnpm install --frozen-lockfile.

A workspace is ready once the checkout and file sync succeed; a failed setup command is logged as a warning. It starts with a cold build cache. A project without Git gets a plain copy of its folder instead of a worktree.

A new workspace takes the name of its first conversation, and the branch follows. A workspace you named is never renamed by an agent.

Archiving

Immediate and irreversible: the workspace leaves the list, the worktree and folder are removed in the background, the branch stays in Git. Archive when the work is finished or abandoned. Archiving from an agent is reviewed in Auto.

Agents in another workspace

An agent never edits another workspace by path. Work runs from inside the workspace:

  • Subtask: a full conversation in your session list, in its own new workspace, with the creating agent as its coordinator. Only bots and their subtasks create them.

Only the creating session may archive a workspace.

When to create one

When work will run alongside other work and their changes could collide. That is the only reason. A subtask of what you are already doing, however many subagents help, stays in the current workspace.

Changes

Measured against the branch's merge base with the remote default branch (origin/main), falling back to the local one only when there is no remote. Desktop shows changed files beside the conversation.

[workspace]
setup_commands = ["pnpm install --frozen-lockfile"]
sync = [".env"]
protected_sync = [".env.production"]