apogee-repo

Bootstrap, update, and manage Apogee-enabled repositories. Handles IDE configuration, managed repo registry, and project hygiene.

MCP surface: Indirect — apogee://status/config-health uses the hygiene scanner.
Install: pip install apogee (included with the Apogee server install)
apogee-repo bootstrap ~/projects/my-app --claude

Synopsis

apogee-repo bootstrap <path> [--claude] [--cursor] [--opencode] [--continue] [--no-ide] [--force]
apogee-repo update <path|all> [--regen-manifest] [--claude] [--cursor]
apogee-repo status <path>
apogee-repo validate <path>
apogee-repo clean <path> [--yes] [--dry-run]
apogee-repo wipe <path> [--yes] [--dry-run]
apogee-repo list
apogee-repo prune
apogee-repo unregister <path>

Description

apogee-repo manages the lifecycle of Apogee-enabled repositories. It handles initial bootstrap (creating apogee_artifacts/, .gitignore patterns, IDE configs, manifests), ongoing updates (refreshing server paths, regenerating manifests), and hygiene (detecting conflicts, cleaning stale configs).

A managed repo registry at ~/.apogee/managed_repos.json tracks all bootstrapped repositories. This enables update all to refresh every project in one command.

Subcommands

Subcommand

Description

Key flags

bootstrap

Create Apogee project state in a target repo

--cursor, --claude, --opencode, --continue, --force, --no-ide

update

Refresh configs, server paths, IDE settings

--regen-manifest, --cursor, --claude

status

Show repo health: connections, rules, issues

validate

Check for config conflicts (non-Apogee files)

clean

Remove conflicting config files

--yes, --dry-run

wipe

Remove ALL Apogee config files (clean slate)

--yes, --dry-run

list

List all managed repos from registry

prune

Remove stale entries (deleted repos) from registry

unregister

Remove a repo from the registry without deleting files

Bootstrap

apogee-repo bootstrap <path> creates:

  • apogee_artifacts/ — feature specs, plans, implementation order

  • project_memories/ — manifests and analysis output

  • .gitignore patterns — excludes Apogee working state

  • IDE configs (optional) — .cursor/mcp.json, Claude Code hooks

  • Initial manifest — baseline codebase analysis

# Bootstrap with Claude Code support
apogee-repo bootstrap ~/projects/kernel --claude

# Bootstrap with Cursor support
apogee-repo bootstrap ~/projects/webapp --cursor

# Bootstrap without IDE configuration
apogee-repo bootstrap ~/projects/library --no-ide

# Re-bootstrap (overwrite existing config)
apogee-repo bootstrap ~/projects/stale --force

Update

apogee-repo update <path> refreshes a managed repo:

  • Updates server path references if the global install moved

  • Refreshes IDE configs (MCP server connection)

  • Optionally regenerates the manifest with --regen-manifest

# Update a single repo
apogee-repo update ~/projects/my-app

# Update all managed repos
apogee-repo update all

# Update and regenerate manifest
apogee-repo update ~/projects/my-app --regen-manifest

Health and Hygiene

# Check repo health
apogee-repo status ~/projects/my-app
# → Shows: MCP connection, rules files, config issues

# Detect conflicting configs
apogee-repo validate ~/projects/my-app

# Remove conflicting (non-Apogee) config files
apogee-repo clean ~/projects/my-app --dry-run
apogee-repo clean ~/projects/my-app --yes

# Full reset — remove ALL Apogee configs
apogee-repo wipe ~/projects/my-app --yes

Registry

# List all managed repos
apogee-repo list

# Remove deleted repos from registry
apogee-repo prune

# Unregister without deleting files
apogee-repo unregister ~/projects/old-project

Note

This page is also available as a man page: man apogee-repo

See Also