Installation And Update Guide

This guide is the command reference for installing, updating, checking, and repairing Ghost-ALICE OS. Public guidance uses OS-native entrypoints with the same long flag surface.

• macOS, Linux, WSL, or Git Bash: bash install.sh ...
• Windows Command Prompt or PowerShell: .\install.cmd ...

On Windows, install.cmd keeps the native wrapper path, Python 3.11+ installer contract, UTF-8 console setup, and -NoProfile -ExecutionPolicy Bypass. This handles PowerShell execution policy blocks and does not change the user or machine execution policy.

The Windows installer needs PowerShell 7.6 or newer. Windows PowerShell 5.1 is retired: under an older PowerShell the installer prints the requirement and stops. Install PowerShell with winget install --id Microsoft.PowerShell --exact, then rerun .\install.cmd.

Core and Ghost-ALICE Autopilot together

After cloning this repository, use the platform-auto-detect installation:

bash install.sh --addon autopilot

For Windows Command Prompt or PowerShell, use .\install.cmd --addon autopilot. The detailed options below let you select a specific agent platform or manage each installation separately.

Contents

• Quick Install
• Install Official Addons
• Official Addon List
• Install One Official Addon To One Platform
• Install Custom Addons
• Install One Platform
• Check Status
• Update
• Common Commands
• Runtime And Platform Reference
• Uninstall
• Troubleshooting

Quick Install

macOS, Linux, WSL, or Git Bash:

git clone https://github.com/AidALL/ghost-alice.git ~/ghost-alice
cd ~/ghost-alice
bash install.sh --addon autopilot

Windows Command Prompt:

git clone https://github.com/AidALL/ghost-alice.git %USERPROFILE%\ghost-alice
cd %USERPROFILE%\ghost-alice
.\install.cmd --addon autopilot

Install Official Addons

Official addons use short aliases and install from the Ghost-ALICE core checkout.

macOS, Linux, WSL, or Git Bash:

bash install.sh --addon autopilot

Windows Command Prompt or PowerShell:

.\install.cmd --addon autopilot

Windows Command Prompt and PowerShell use the same official alias through .\install.cmd --addon autopilot.

Run this from the Ghost-ALICE core checkout. Normal users do not clone the autopilot addon repository or run an installer inside that repository; the core installer fetches the official addon package. This install example is not a full runtime compatibility claim; read the addon repository compatibility-matrix.json before making one.

For platform-specific commands, see Install one official addon to one platform.

Addon-specific behavior, state files, pause/resume controls, and removal details live in each addon repository. The core checkout owns the common install command.

Official Addon List

Core 0.5.1 and Ghost-ALICE Autopilot 0.5.1 use the routing and managed completion APIs. Ghost-ALICE Autopilot requires Core 0.5.1 or later. Source checks, native runtime validation and publication establish separate evidence.

Install One Official Addon To One Platform

bash install.sh --platform codex --addon autopilot

.\install.cmd --platform codex --addon autopilot

Install Custom Addons

Custom, tenant, or local development addons use --addon-source PATH|URL.

bash install.sh --addon-source /path/to/addon-repo

.\install.cmd --addon-source C:\path\to\addon-repo

For git URL addon sources, --addon-tag selects the branch or tag to clone into the local addon source cache.

Install One Platform

The following commands install Core only. Add --addon autopilot to include Ghost-ALICE Autopilot for the selected platform.

To choose interactively:

bash install.sh --prompt-platform

.\install.cmd --prompt-platform

Check Status

Doctor is a read-only strict diagnostic. Use it before changing a suspicious install.

bash install.sh --doctor
bash install.sh --status

.\install.cmd --doctor
.\install.cmd --status

The healthy target is overall: ok.

Update

Update the local clone through the installer so source-local edits are stashed before a fast-forward.

cd ~/ghost-alice
bash install.sh --update-source

cd %USERPROFILE%\ghost-alice
.\install.cmd --update-source

If the local installer lacks the update option, follow bootstrap update recovery.

If source update stops with conflicts, divergent branches, or non-fast-forward state, do not rerun the installer repeatedly. Follow troubleshooting first.

--update-source updates the Core source checkout; it does not update the addon package. Reinstall Core and Ghost-ALICE Autopilot together, then check the installed state. The bootstrap updater may reinstall Core only, so follow it with this same paired command.

bash install.sh --addon autopilot
bash install.sh --doctor
bash install.sh --status

.\install.cmd --addon autopilot
.\install.cmd --doctor
.\install.cmd --status

Common Commands

Runtime And Platform Reference

Agent Visibility Profile

The default profile is dynamic. The profile controls how much governance surface is shown to the user; it does not disable hooks, strict-grade logs, or Work-Impact Projection.

--agent-visibility remains an accepted compatibility alias. Prefer --visibility in new docs and commands.

Slash Commands By Platform

Ghost-ALICE installs /visibility strict|dynamic|minimal as a Claude Code workspace command. On Codex and every other platform, use _shared/agent_visibility_cli.py to inspect or change the same profile.

Python Contract

The installer requires Python 3.11 or newer for every command, --help and --list included: install.sh only finds or prepares Python and hands the arguments to _shared/installer/cli.py. If Python 3.11+ is missing, it attempts automatic preparation where possible.

The optional macOS native context gateway requires Python 3.14 or newer with compression.zstd. Its installer checks that capability before changing component files, the launch agent, or the Codex provider. This component requirement does not change the Core installer and hook minimum of Python 3.11. If Codex config.toml is a symlink, gateway installation and affected removal stop before changing the service and preserve the link and its target. Gateway installation also refuses symlinked launch-agent, component, companion, state, and ownership-file entries before service changes, preserving both links and targets. Refresh preserves edited provider blocks and launch agents by checking the prior installation binding before changes. Component replacement uses only the file digests in the authenticated installation receipt; the obsolete separate installed-files.json is neither read nor generated and is removed after a successful installation or refresh. Existing gateway state also requires authenticated registration and unchanged state proof, even when provider markers or the launch agent are absent. Without that ownership, installation preserves the state directory and stops; use an empty destination for a new installation or review the retained installation binding. If a first installation fails and the candidate service is confirmed stopped, rollback removes that attempt’s new state artifacts so a new attempt can proceed. An uncertain stop or concurrent artifact change preserves recovery material for review.

• macOS: if Homebrew is available, brew install python3
• Linux / WSL: available package managers such as apt-get, dnf, yum, or pacman
• Windows: winget, choco, then scoop

If Python 3.11+ is still unavailable, installation stops and prints manual recovery guidance.

PowerShell Contract

.\install.cmd runs the Windows installer with PowerShell 7 (pwsh.exe), and with Windows PowerShell (powershell.exe) when pwsh.exe is absent. The Windows installer needs PowerShell 7.6 or newer, the 7.6 LTS line. Under an older PowerShell, Windows PowerShell 5.1 included, it prints PowerShell 7.6 or newer is required with the install command winget install --id Microsoft.PowerShell --exact and stops with exit code 1; the installer never installs PowerShell itself. After that check, it sets UTF-8 console input and output, prepares Python 3.11+ and passes every argument in order to _shared/installer/cli.py, the same installer that install.sh runs, so Windows accepts the same long flags.

On macOS and other POSIX hosts, installed hooks try GHOST_ALICE_PYTHON first, then Python from the runtime PATH and common installation locations, and finally the interpreter used by the installer. Each candidate must pass the Python 3.11+ check. This final fallback lets a desktop app run hooks even when its PATH omits the installer’s Python directory. It does not change the host’s global Python or PATH; rerun the installer if that interpreter moves and no other candidate is available.

Node.js Contract

Claude Code and Codex hook-enabled installs require a resolvable Node.js runtime because the tool-checkpoint PreToolUse gate runs ghost-alice-hook.mjs. The installer checks configured runtimes, the platform registration and PATH, including the configured Codex runtime fallback. It blocks hook installation only when the target platform requires hooks and no usable Node runtime resolves.

Platform Update Behavior

Auto-reflection applies to skill bodies such as SKILL.md, references/, and scripts/. Hooks, bootstrap files, permission policy, and _shared/ are installer-managed runtime surfaces, so rerun the installer when they change.

Installation on disk and adoption by a running host are separate. After a hook command changes, confirm its native trust entry and observe a subsequent native callback; use the host’s reload or full restart controls if it retains the previous registration. See native hook trust and reload. Do not repeat unchanged business verification to check host adoption.

Core and optional Autopilot transitions

Core installation and addon removal are separate operations. A fresh Core installation supplies the instructions, input/source bindings, work and review records, and Core hooks. It does not register Autopilot continuation. Updating Core without an addon option preserves an already installed addon; --addon-skip skips addon installation and does not request its removal.

Core authenticates the model’s recommended follow-up work independently of Autopilot. Only the optional approved continuation path requests another host invocation. Removing Autopilot retains Core records and does not turn unmet criteria into completed criteria. Per-addon removal keeps modified files and its sidecar/removal marker for review or retry, while detaching its managed executable registrations. This is a configuration/file operation; ongoing-host adoption and cancellation of already delivered work are separate observations.

Full/platform removal archives pending merge originals and last-platform installation recovery copies under unique ~/.ghost-alice/uninstall-backup/<platform>/support-state/ directories. It keeps previous archives, source checkouts, conversation/session evidence, intent ledgers, audit traces and secrets. See uninstall cleanup for ownership and shared-file rules.

For Claude, the installer records which manifest-selected addon Skill(...) grants it actually added in ~/.ghost-alice/addon-permissions/claude.json. Addon removal clears one owned occurrence and preserves preexisting grants and extra user occurrences. A legacy grant without ownership evidence requires manual review. For Codex, addon removal clears unchanged owned hook trust hashes and moves surviving Core/user trust tables with their hook positions, preserving their metadata. A trust collision or configuration write failure prevents successful file removal; see uninstall cleanup.

Installed Surfaces

A full install deploys:

• core skills from skill-catalog/skills.json
• coding-convention workflow skills
• optional addon skills through official --addon aliases or custom --addon-source
• _shared/ utilities
• platform hook settings
• Node-backed hook dispatcher assets under ~/.ghost-alice/hooks/
• Claude Code permission allowlist
• Claude ${CLAUDE_CONFIG_DIR:-~/.claude}/CLAUDE.md global bootstrap
• Codex ~/.codex/AGENTS.md loader and managed ~/.codex/ghost-alice-governance.md common contract
• the install record ~/.ghost-alice/installed-payload.json: one file for both hosts that names every install location, its source and the fingerprints of copied files, written in the same step as each placement
• ~/.ghost-alice/rollbacks/<txid>/: the files one placement replaced, the install record as it was before, and the placement’s journal; the next locked installer command restores a placement that stopped halfway, and the newest 20 finished folders are kept
• support state for install-state, pending merges, and uninstall reports

An installation that registered the optional context gateway: the runtime _shared placement goes through the gateway coordination, which stops the service, publishes the changed modules, restarts the service and refreshes its installation receipt. The Codex copy of _shared (~/.agents/skills/_shared) does not: the coordination does not count that folder as a gateway dependency, so a Codex install that replaces it after a gateway module changed stops at the runtime placement with A gateway runtime component changed. For a gateway registered with that folder as a shared dir, run the gateway refresh command before bash install.sh when a gateway module changed in the source; the install prints one Context gateway: line with the receipt’s source, its file count and whether the service is running.

The installer owns only the marked Ghost-ALICE block in each global rule file. It refreshes that block while preserving adjacent user text. If the destination is a markerless user-owned file, installation leaves it unchanged, writes <rule-file>.ghost-alice-proposed, and status/doctor does not report the proposal as an installed global rule.

Common Governance and Project Instructions

Ghost-ALICE common governance applies across projects and task domains. On a normal Codex route, the current-session assistant reads the common contract at the path rendered into the managed ~/.codex/AGENTS.md loader. The installer writes that contract to the sibling ghost-alice-governance.md. Claude Code receives the common contract directly in the managed portion of ${CLAUDE_CONFIG_DIR:-~/.claude}/CLAUDE.md. Project instruction files add project-specific constraints; they do not supply a second copy of the common procedures. User instructions and project-specific constraints retain precedence.

flowchart LR
    S["Platform common-contract source"] --> I["Installer replaces owned block"]
    I --> C["Codex loader + common-contract file"]
    I --> H["Claude global common-contract block"]
    C --> M["Model applies common procedures"]
    H --> M
    P["Project-specific constraints"] --> M
    U["User objective and instructions"] --> M

If Codex cannot read the named common file, the assistant reports that missing input and stops only work that requires it. Answers fully supported by supplied conversation can use the loader’s no-tool rule. Status and doctor check the loader and its declared companion together. The installer preserves adjacent user text and markerless user-owned rule files; it refuses to replace a Codex common contract through a symlink. A proposal is not an installed contract. The installer does not change unrelated projects’ instruction budgets or rewrite their local rules.

merge-companion

When an update detects user-modified installed files, the installer isolates those candidates in a pending merge queue.

• manifest: ~/.ghost-alice/pending-merges/<platform>/manifest.json
• backup: ~/.ghost-alice/pending-merges/<platform>/
• install state: ~/.ghost-alice/install-state/<platform>.json

On the next Claude/Codex session, the hook reports pending entries. When you ask to review them, or when work changes an affected skill, merge-companion asks whether each should be merged, discarded, or deferred.

Uninstall

Uninstall uses the installer-owned install-state manifest and removes only the Ghost-ALICE managed block from the platform global rule file. User-authored text remains in place.

bash install.sh --uninstall

.\install.cmd --uninstall

See uninstall cleanup for the full cleanup contract.

Troubleshooting

When an update is blocked during git pull, a merge conflict, or an installer rerun, start with troubleshooting.

The GitHub Wiki install-troubleshooting page links to the online source guide, which can be read without updating a local checkout.