Stack Guide

Stack Guide

Alpha: use at your own risk; may change daily. See the release policy.

.SYSTEMX is stack-neutral. It organizes how work is understood and verified; your project chooses its languages, frameworks, data stores, and deployment tools.

CLI and tool boundaries

Use CLI and Tools to choose installed systemx management, reviewed local shell/PowerShell launchers, configured application commands, or an Agent Y provider. The installed alpha.5 CLI exposes systemx projects --target OUTER_DIR -- ... --project NAME, defaulting offline. Shared outer tools route to .SYSTEMX/Projects/NAME/.SYSTEMXP; children keep records and explicitly configured commands, not nested installations. Menu 18 and tools-guide print the same portable entry-point map.

What is required

Usage	Requirement	Installed by .SYSTEMX?
Read/write project documents	Markdown/JSON-capable editor or file tools	No editor is installed
Optional CLI and library	Python 3.9+	Runtime must already be available
Git-based package installation	Git and pip in the chosen Python environment	No Git installation
Wheel or reviewed folder usage	Python; no Git required for the folder tools	Only requested package/folder files
Bash launchers	Bash plus Python	No shell configuration changes
Windows launchers	PowerShell plus Python launcher/Python	No execution-policy changes
VS Code	Optional editor	No extension or global settings changes
Google Drive profile	Locally available regular files, or explicit browser uploads	No Drive client, OAuth, or account setup
LLM chat	Explicit attachments or authorized file tools	No model subscription or API calls
Optional Agent Y GitHub channel	Python tools, a chosen installed CLI provider, Git repository, and GitHub CLI/account access for PR operations	No provider CLI, Git credentials, GitHub account, or PR is installed/created by setup

There are no third-party Python runtime dependencies, database requirements, Node.js requirements, background daemons, system services, login jobs, or automatic Git hooks in the standard installation. Building a wheel uses setuptools as a build dependency in the build environment. The GitHub release wheel avoids a local source build.

Fit it to your project

Project type	Typical integration
Python library/application	Point checks at the project's chosen test and lint commands
JavaScript/TypeScript	Point checks/build at existing npm, pnpm, or other scripts
.NET, Java, Go, Rust, or native apps	Use the existing compiler/test CLI as argument arrays
Documentation/research	Use document validation and evidence review; leave deployment empty
Desktop workspace or non-Git directory	Use explicit project paths and local records
Cloud/Drive workspace	Coordinate one writer and verify synchronization before switching

For example, if a JavaScript project already defines a working test script, a check can use {"name": "tests", "command": ["npm", "test"]}. That does not install npm, create a test suite, or prove the command passes. Keep missing commands empty until the project supplies them. See the configuration contract.

Keep application dependencies, credentials, infrastructure, and build output in the host project's chosen layout. Use the appropriate package manager to install and remove those dependencies. A .SYSTEMX folder uninstall must not remove a shared SDK or unrelated project environment. If a project-specific setup adds external resources, record the exact owner, version, install location, original state, verification, uninstall command, and log location in that project.

Portable adoption

Use .SYSTEMX with exact casing everywhere, UTF-8 documents, quoted containing project paths, and argument arrays. Treat local lowercase aliases as optional; do not rely on Git, Drive, or archives preserving them. Prefer an isolated Python environment for the library so its package and logs are easy to identify and remove. Start with first-time setup, then keep the uninstall guide with the project handoff.

Full-project and bot toolchains

Use the one-shot toolchain map to connect a researched brief to real app and verification tools. Codex-based sessions/dots, Grok-based bots, or other harnesses can use the same records through an authorized local CLI or explicit adapter. Follow shared workspace patterns for persistent VM/local storage, Drive, cloud snapshots, and removal ownership. Those examples add no provider CLI installation, scheduler, model API client, or synchronization daemon. The optional Agent Y channel below invokes a provider that the user has already installed and authorized.

App subagents and external CLI providers

The optional Agent Y adapter described here is included in 1.9.0-alpha.2. Older 1.8.9-alpha.1 installations have Agent X/Z tooling only. On native Windows in this alpha, Agent Y applied CLI runs fail closed before provider/worktree mutation because safe descendant-process termination is unverified. The core Windows installer and record tools are a separate path.

Agent Y is an optional task channel when Agent 0 in Codex App, VS Code, or another harness delegates a bounded job to an installed Codex CLI, Copilot CLI, or a configured provider. Select the provider per task after checking its installed command, authentication, allowed paths, and cost. The CLI runs in an isolated Git worktree; it does not inherit the app's hidden conversation memory. Share only the explicit task packet and reviewed evidence.

With explicit opt-in, a successful run can push its owned branch and open a draft GitHub PR. Agent 0 still owns review and task acceptance. Ready-for-review, external merge, abandoned close, and verified cleanup have separate authority and remote-state checks. The optional CLI channel adds external tool requirements and token/compute costs to the same project budget as any app-native subagents. See security and the command reference before enabling PR actions.

Read the current Agent 0/X/Y/Z map

The updated complete-system infographic shows the application/toolchain layer alongside the records. Agent Y is an optional task-selected external CLI channel; it does not select a framework, install a provider, or replace project checks. Agent 0/user owns acceptance, Agent X records actual events, and Agent Z reviews the evidence. An opted-in draft PR is a delivery handoff; readiness, cancellation closure preserving work, and archive-first cleanup after a separate authorized merge have distinct gates.