Getting Started

Getting started

Use one SYSTEMX format across different working locations. Select a profile, choose the project directory, and initialize its own records.

1. Choose a setup profile

Working location	Profile flag	Guide
Repository or VS Code project root	--profile project	Project setup
Windows, macOS, or Linux directory	--profile directory	Directory setup
Local Google Drive project folder	--profile drive	Google Drive setup
LLM chat context and handoffs	--profile chat	LLM chat setup

Each profile uses the same template, ledger, memory, and version-management rules. A filesystem target is a path on the current computer. A Drive URL or a chat conversation does not itself provide writable filesystem access.

2. Install the tools or use an extracted template

Optional CLI tools need Python 3.9+. Documentation works without Python. Use Library integration to install from Git or a release wheel into a chosen Python environment. Exact release commands are in Versions and changelog.

From a reviewed checkout or extracted template:

bash .SYSTEMX/SYSTEMX.sh validate --template
bash .SYSTEMX/INSTALL.sh --target "/path/to/project" --profile project --dry-run
bash .SYSTEMX/INSTALL.sh --target "/path/to/project" --profile project

Windows users can call .SYSTEMX\INSTALL.ps1 with the same flags or use py -3 -B .SYSTEMX\manager.py install. The target is the containing project folder. It may already have SYSTEMX: installation preserves existing files and adds missing ones. Inspect the dry run and read Upgrading first.

3. Verify the selected defaults and project records

With the installed library:

systemx status --target "/path/to/project"
systemx run --target "/path/to/project" -- validate
systemx run --target "/path/to/project" -- doctor
systemx run --target "/path/to/project" -- context --agent agent.0

Without package installation, use python3 -B .SYSTEMX/manager.py in place of systemx. The managed launcher also works from the adopted project root. New installs are pinned with manual updates. A zero task count means no work has been recorded; it is not project completion. The blank --template validation mode applies before installation; normal validate applies after adoption.

4. Record context and configure relevant commands

Fill the outer .SYSTEMX/GLOBAL/CONTEXT.md, PLAN/MASTER-PLAN.md, MEMORY/PROJECT.md, and AGENTS/agent.0/MEMORY.md with the project's facts. Never put active work into the blank records under .systemx/releases/.

Run systemx run --target ... -- init only if project commands are needed. It creates project.json without replacing an existing config. See Configuration and quality. Create concrete tasks through Task workflow, then select existing task IDs with focus.

5. Connect your assistant and resume consistently

Load the selected defaults' START-HERE and STANDARD, then the outer project's current focus, shared records, task ledger, and assigned agent memory. The context command identifies both locations. Reconcile root discovery instructions with the supplied entry-point template instead of overwriting them.

For chats without file access, export a reviewed packet and retain proposed changes explicitly. For shared Drive folders, use one writer and verify synchronization before another computer resumes the project.

Follow Installation and updates to change the version, lock it again, or opt into startup updates. Updates preserve your project records and all existing local folders.