Scratch Sessions

A scratch session is a session that does not belong to any project on disk. When you start one, AoE provisions a fresh directory under ~/.agent-of-empires/scratch/<id>/ (on Linux: $XDG_CONFIG_HOME/agent-of-empires/scratch/<id>/), attaches the session to it, and removes the directory when you delete the session (unless you opt in to keeping it).

Use scratch sessions for one-off questions, quick investigations, or ad-hoc agent runs where you do not want a session record tied to a specific repo or to keep stray files around afterwards.

When to use it

• Ask the agent a question that does not depend on a particular codebase.
• Give the agent a clean, empty directory to write files into without polluting an existing project.
• Investigate something quickly and have the directory go away automatically when you are done.

Three ways to start one

Command line

aoe add --scratch -t "Quick question" -c claude

The session prints its resolved Path: line pointing at ~/.agent-of-empires/scratch/<id>/ and a Scratch: yes line in the summary. You do not pass a project path; it is provisioned for you.

Trying to pass a path alongside --scratch is rejected:

aoe add /Users/me/repo --scratch
# error: Cannot specify a project path with --scratch

--scratch is mutually exclusive with all worktree-related flags (-w, --new-branch, --base-branch, --repo, --project, --no-submodules). Mixing them fails at parse time with a clear conflict message.

Web dashboard

In the new-session wizard, the Project section has a toggle labeled Skip project folder above the Recent / Browse / Clone URL tabs. Turning it on hides the path picker and shows a “Scratch session” callout; the worktree controls under More options become unavailable.

Selecting a real project (Recent / Browse / Clone) turns the toggle back off, so the wizard never submits a request with both a real path and the scratch flag set.

Fast-create shortcut. From anywhere in the dashboard, press Cmd+Shift+N (Mac) or Ctrl+Shift+N (Linux / Windows) to open the wizard with scratch already enabled. A follow-up Cmd+Enter / Ctrl+Enter launches the session, so two keystrokes is enough to spin up a fresh scratch session.

Command palette. The same flow is reachable from the command palette (Cmd+K / Ctrl+K): search for “New scratch session” and run it to open the wizard prefilled for a scratch session. In read-only mode the creation commands are hidden from the palette.

Sidebar grouping. Every scratch session has its own scratch/<id>/ directory on disk, so the dashboard sidebar would otherwise render each one as its own one-session group. Scratch sessions are bucketed into a single synthetic Scratch group at the bottom of the sidebar instead, mirroring how multi-repo workspaces are collapsed into one Multi-repo group. Clicking the ”+” on the Scratch group header opens the wizard with no path prefilled, so you can flip on Skip project folder to add another one.

TUI new-session dialog

Press Ctrl+T from any field in the new-session dialog. The Path input is replaced with a (scratch directory) marker, the worktree toggle is forced off, and submitting creates the session in a fresh scratch directory. The bottom hint line surfaces Ctrl+T scratch so the binding is always visible; the chip is emphasized when you are focused on the Path row. Press Ctrl+T again to revert.

Storage location

Scratch directories live under the app data dir, each session in its own <instance-id>/ subdirectory:

Platform	Scratch root
macOS / Windows	~/.agent-of-empires/scratch/
Linux	$XDG_CONFIG_HOME/agent-of-empires/scratch/ (defaults to ~/.config/agent-of-empires/scratch/)

Storing under the app dir (rather than $TMPDIR) means scratch directories survive OS-level temp-dir cleaning until you delete the session.

What happens at delete

Deleting a scratch session (aoe rm, web dashboard, or TUI delete dialog) also removes its scratch directory.

Pass --keep-scratch to aoe rm (or check the box in the delete dialog) to keep the directory on disk; the session is detached from AoE’s view but the files survive, and the kept path is logged.

Deleted scratch directories do not appear in the wizard’s Recent projects tab.

Compatibility

• Structured view: scratch sessions use the structured view (the default) with the bundled ACP agents. The ACP worker spawns with the scratch directory as its current working directory.
• Sandboxes: scratch sessions can run in a container sandbox (-s or --sandbox-image); the container mounts the scratch directory the same way it mounts a real project path.
• Worktrees: not supported. A scratch directory is not a git repo, so the worktree concept does not apply. Use a regular project path with -w if you want a worktree.
• Hooks: a scratch directory has no .agent-of-empires/config.toml, so the per-repo hook trust prompt never fires. Global and profile on_create hooks still run, with the scratch directory as their cwd.

Cleanup and retention

If aoe serve (or your shell session) dies before you delete a scratch session, the directory is left on disk. There is no automatic retention policy yet; clean up by deleting the session record (which removes the directory) or by removing entries under the scratch root directly.

To keep the files, use aoe rm --keep-scratch and copy them out, or create a new session against a real path with aoe add <path>.