Skip to content

Add an existing repository

This guide registers a repository you already have as a SASE project so agents can work in it. It assumes the repository exists locally with a remote; if that is not your situation, create the Git repository first and then come back.

Before you start

You need SASE installed and the repository checkout on this machine. If SASE is not set up yet, follow Install and set up SASE.

1. Preview the registration

Show the read-only plan without writing anything, and confirm it names the project you expect:

sase project add <repository> --check

<repository> is your existing repository reference, for example its local path. Previewing is free for agents and people alike; the actual setup step needs a person to confirm it.

2. Register the project

Register the repository as an enabled SASE project:

sase project add <repository>

Setup can write the repository's management file, commit it, and push the default branch. When setup succeeds in a terminal, it can offer to initialize the project directly.

3. Initialize the project

Preview what initialization would change, then apply it:

sase init -p <name> --check
sase init -p <name> --yes

Initialization walks the config, machine, memory, repository, service, and skills steps in order. Confirm everything is current:

sase init --check

SASE reports that it is initialized and no steps need to run.

If it goes wrong

Run the read-only checks in Diagnose problems with sase doctor and follow the step they point at.

_[project]: A sase project is a named unit of work registered with SASE. _[workspace]: A sase workspace is a numbered clone of a project's primary repo, managed by the workspace store and tracked in that project's registry.json. _[agent]: A sase agent is an agent session or a single agent that does not belong to a session. _[prompt]: A prompt is the text SASE hands to a provider to start an agent turn. _[macro]: A macro is a reusable prompt triggered with #name in agent prompts. _[Patch]: A Patch is SASE's local unit of change. _[bead]: A bead is one tracked work item in SASE's git-native issue tracker. _[plan]: A plan is a persisted, approved artifact recording the intent behind agent work. _[TUI]: The TUI is SASE's terminal interface for running agents and reviewing results. _[epic]: An epic is an executable multi-phase plan run with sase bead work. _[gate]: A sase gate is a durable, command-backed request for one user decision, created when work must pause for the user. _[monitor]: A sase monitor is a monitor turn that runs one long command under a detached supervisor, so the command outlives the agent that started it. *[stitch]: A stitch is the lightweight ordered change record inside a Patch's STITCHES: section.