Configuration

Environment Variables

Variable

Purpose

Default

APOGEE_ROOT

Override project root for MCP server session

Current directory

APOGEE_EXECUTOR

Chain execution backend for the Python server (only inmemory is supported; the Rust binary is the primary production server)

inmemory

APOGEE_ORG_SKILLS

Organization-level skill overlay path

(unset)

APOGEE_TEAM_SKILLS

Team-level skill overlay path

(unset)

APOGEE_USER_SKILLS

User-level skill overlay path

(unset)

APOGEE_MAX_CPUS

Maximum CPUs for manifest generation

(auto-detect)

APOGEE_DUCKDB_MEMORY_LIMIT

DuckDB memory limit (e.g. "4GB")

"2GB"

APOGEE_NICE_LEVEL

Unix nice level for manifest generation (0-19)

10

APOGEE_CI_REPORT_PATH

Custom CI report JSON path

apogee_artifacts/ci-run-report.json

Build Tasks

Apogee uses just as the build runner. Key tasks:

just test          # Run unit tests
just test-all      # Unit + integration tests
just build         # Compile skill runtime
just docs          # Build HTML documentation
just man           # Build man pages
just pdf           # Build PDF documentation
just docs-all      # Build all three formats
just accept        # Full acceptance gate

CI Integration

Apogee runs headless — no IDE required. The manifest generator and test runners work as standalone CLIs in any CI pipeline.

Quick setup: copy a CI template from examples/ci/:

  • GitLab CI: copy examples/ci/.gitlab-ci.yml to your repo root

  • GitHub Actions: copy examples/ci/github-actions.yml to .github/workflows/verify.yml

Verification bands control depth via the VERIFY_BAND env var:

Band

What runs

Coverage output

fast-feedback

Unit tests (quick mode)

No

ship-quality

Full unit + integration tests

coverage.xml

hostile-path

All above + adversarial lanes

coverage.xml + custom

Headless CPG analysis in CI:

# Generate manifest and CPG database
apogee-manifest --repo . --label current

# Multi-branch indexing (compare feature vs main)
apogee-manifest --repo . --orchestrate \
  --orchestrate-branch main=origin/main \
  --orchestrate-branch feature=origin/feature-x

# Query the CPG database directly via DuckDB
duckdb .apogee/cpg.duckdb \
  "SELECT name, file_path FROM nodes WHERE kind='function'"

The apogee-manifest CLI produces the same DuckDB database that powers the MCP server’s 13 CPG tools. In CI, you can query it directly with DuckDB SQL or feed the manifest JSON into downstream reporting.

CI report output: set APOGEE_CI_REPORT_PATH to control where the structured CI report is written (default: apogee_artifacts/ci-run-report.json). The report includes pass/fail counts, verification band, and proof-tier verdicts.

The templates respect the artifact privacy boundary — apogee_artifacts/ is never uploaded.

See examples/ci/README.md for full band selection and coverage output details.

Troubleshooting

MCP server won’t start / IDE can’t connect

  • Verify Python 3.10+: python3 --version

  • Verify the server runs: apogee-mcp (should block on stdin)

  • Check IDE config: the server command must be the full path to apogee-mcp or use the virtualenv’s Python

  • For Cursor: check .cursor/rules/apogee.mdc exists

  • For Claude Code: check CLAUDE.md exists at repo root

``just install`` fails

  • Verify just is installed: just --version

  • Verify pip is available: python3 -m pip --version

  • Check that scripts/install_server.sh is executable

  • On macOS: xcode-select --install if C compiler is missing

Manifest generation produces empty results

  • Ensure the repo has committed files (uncommitted files need --working-dir flag)

  • Check .apogee/manifest.toml for exclude_patterns that may be filtering too aggressively

  • Run with --json to see raw output: apogee-manifest --repo . --json

Compiled skills are stale

  • Run just build to recompile skills

  • Run just check to verify freshness without rebuilding

  • If the unit test runner reports stale skills, just build fixes it

CPG database errors

  • The CPG database is stored at .apogee/cpg.duckdb

  • Delete and regenerate: rm .apogee/cpg.duckdb && apogee-manifest --repo .

  • Memory issues: set APOGEE_DUCKDB_MEMORY_LIMIT=4GB

See Also