Scopes¶
lazyai-cli supports three setup scopes. Choose the one that matches how you work.
Overview¶
| Scope | Best for | Canonical target | Notes |
|---|---|---|---|
project |
One repo, self-contained setup | ./.ai/ |
Default day-to-day setup |
global |
Personal defaults across projects | ~/.ai/ |
All 7 LazyAI-supported targets are available globally |
workspace |
Multi-repo team coordination | planning-repo/.ai/ |
Planning repo becomes the hub |
Project scope¶
What it is: the default, self-contained setup in the current working directory.
When to use it:
- You want everything versioned with the repo
- You want generated instructions checked into source control
- You need all supported tools available side-by-side
Example command:
lazyai-cli init \
--scope project \
--tools opencode,claude-code,copilot \
--name my-app \
--preset standard \
--enable-servers filesystem,ai-memory \
--no-interactive
Key directories created: .ai/, specs/, .opencode/, .claude/, .github/, .vscode/, .ai-setup.db
Global scope¶
What it is: personal defaults shared across all projects on your machine.
When to use it:
- You want your own baseline AI operating system everywhere
- You use any of the 7 supported tools across many repos
- You want project repos to layer on top of a personal default config
Canonical target: ~/.ai/
Tool-native targets:
~/.config/opencode/— OpenCode~/.claude/— Claude Code~/.copilot/— GitHub Copilot~/.pi/— Pi~/.omp/agent/— OMP~/.kiro/— Kiro~/.gemini/— Antigravity Example command:
lazyai-cli init \
--scope global \
--tools opencode,claude-code,copilot,pi,omp,kiro,antigravity \
--name global \
--preset minimal \
--no-interactive
Workspace scope¶
What it is: a multi-repo team setup with a dedicated planning repo as the central hub.
When to use it:
- Your team coordinates work across multiple repositories
- You want one planning repo for specs, ADRs, memory, and ledgers
- You want a single place for all AI tool configuration
How it works:
- Everything lives in the workspace root (the planning repo) — referenced repos are never touched
- The workspace root gets the full canonical setup:
.ai/, specs, tool directories, MCP configs - Referenced repos are scanned for stack detection (language, framework, commands)
- Detected repo info is included in compiled root files so AI agents know what is in the workspace
- Per-repo ledgers and state snapshots are written under
specs/memory/repos/ - Launch your AI tool from the workspace root
Example command:
lazyai-cli init \
--scope workspace \
--workspace-root ./planning-repo \
--tools opencode,claude-code,copilot \
--name acme-workspace \
--preset standard \
--no-interactive
Sidecar and scope behavior¶
LazyAI can optionally store docs, specs, and plans in a sidecar directory instead of the scope root. Sidecar configuration is discovered positionally — by directory position, not by name or registration — and resolved with a field-level merge across up to three layers.
Layer discovery (walk-up)¶
LazyAI looks for .lazyai/sidecar.yaml files at up to three positions relative to the current working directory (cwd):
- Project —
cwditself. Ifcwd/.lazyai/sidecar.yamlexists, that's the project layer. - Workspace — the nearest ancestor directory above
cwd(nevercwditself) that has a.lazyai/sidecar.yaml. LazyAI walks upward one directory at a time, stopping at the first hit. The walk never enters$HOME(it stops just before) and never goes past the filesystem root. - Global —
~/.lazyai/sidecar.yaml. Always present as a layer (built-in defaults apply if the file itself is absent).
There is no name-based registration and no "active workspace" pointer — whichever ancestor directory happens to contain a .lazyai/sidecar.yaml is the workspace layer for anything run from below it.
Field-level merge¶
Resolution is a per-field merge, not a single winning layer. For each of docs_dir, specs_dir, and plans_dir independently, LazyAI takes the first non-empty value found in this precedence order:
project > workspace > global > built-in default
This means a project-level config that sets only docs_dir still inherits specs_dir/plans_dir from the workspace or global layer (whichever set them) rather than losing them. sidecar status reports which layer supplied each resolved field.
Workspace as an ancestor directory¶
A "workspace" is no longer something you attach or activate by name — it's simply whichever ancestor directory above your project has a .lazyai/sidecar.yaml. In a multi-repo team, you typically run sidecar init --scope workspace once from the shared planning/parent directory; every project underneath it then automatically picks up its settings on the next resolution, with no separate registration step. Moving or renaming that ancestor directory has no special effect beyond the normal filesystem walk finding (or not finding) it again.
Optional fallback behavior¶
Sidecar is always optional. If no .lazyai/sidecar.yaml is found at any layer, LazyAI falls back to the built-in defaults with no behavior change. No sidecar = no errors, no warnings, no migration needed.
Explicit exclusions¶
- No Skeeper or external provider integration. The sidecar is purely local. There is no
skeeperfield, no provider abstraction, and no remote sync. - No content migration.
sidecar initdoes not move existing docs/specs/plans. - No multi-sidecar. One
.lazyai/sidecar.yamlper discovered layer. - Bounded discovery only. The walk-up looks for
.lazyai/sidecar.yamlfiles only, stopping before$HOMEor at the filesystem root — it does not read environment variables, and it does not keep climbing past the first workspace hit to look for a more distant layer.