Projects

A project is a repository registered with OpenLoop under an alias. Linking is lightweight (a line in the global registry), and initialization materializes the repo’s control plane.

Linking

openloop project add api ~/work/api --init

• The alias (api) is what every other command uses (-p/--project).
• --init immediately materializes templates (otherwise run openloop project init api later, useful if you want to register first and review what will be written).
• If the alias already exists, the command fails; pass --force to update the path instead.

Initialization writes (idempotently):

File	Purpose
.openloop/project.json	Per-project config, reference
.openloop/policy.yaml	Scope & risk policy, concepts
.openloop/tasks.json (+ schema)	Empty task ledger
.pi/SYSTEM.md, .pi/APPEND_SYSTEM.md	Agent system prompts
.agents/skills/openloop/SKILL.md	Agent workflow instructions
AGENTS.md	A fenced <!-- openloop:start --> … <!-- openloop:end --> section is merged in

Re-running project init --force backs up the existing .openloop/ to .openloop/backup/<timestamp>/ before overwriting.

The registry

~/.openloop/projects.json maps aliases to absolute paths and records whether the control plane was initialized. openloop project list (or --format json) shows the current state; project show <alias> prints one entry.

openloop project list

alias      initialized  path
api        true         /home/you/work/api
web        true         /home/you/work/web
scripts    false        /home/you/work/scripts

Activation

openloop project activate api

Sets the daemon’s preference. With the default round-robin selection strategy every initialized project gets a turn; with priority, the active project is preferred whenever it has work (see scheduling).

Unlinking

openloop project remove api

Removes the registry entry only. Everything inside the repository (.openloop/, prompt files, ledger history) is preserved, safe to run at any time, and safe to re-link later with project add.