# Install Ophanimus Forge

Canonical instructions: https://ophanimus.com/install.md

Give your coding agent this prompt:

> Install Ophanimus Forge by following https://ophanimus.com/install.md. Check the prerequisites, explain the changes, and use the managed installer. Let me complete authentication. Verify the connection before reporting success.

This public document can be read without an app account. Installing still needs an
available hosted service and your authorization. It connects your coding agent to
Ophanimus Forge; it does not install a local server.

## 1. Get the approved installer

**Current distribution: prerelease tarball.** The installer version covered here is
`0.10.3`. It is not available on public npm. Do not use `ophanimus@latest`, substitute
the npm placeholder, or clone the private product repository.

Your Ophanimus onboarding contact must supply:

- The approved `ophanimus-0.10.3.tgz` file.
- Its expected SHA-256 checksum through a trusted channel separate from the download.
- The hosted service origin approved for your account, including `https://`.

If any item is missing, stop and ask for it. A public instruction page is not proof
that a package or hosted service is available. Do not infer the service address from
this marketing site's address. For onboarding help, email [hello@ophanimus.com](mailto:hello@ophanimus.com).

Use Node.js 22 or newer, npm, and the coding agent you want to connect. Check:

```sh
node --version
npm --version
```

Keep the approved tarball for later verification and removal. Replace the example
absolute paths below with its real path. On Windows, use a Windows absolute path.
Compute its checksum with the command for your system:

```sh
# macOS
shasum -a 256 "/absolute/path/ophanimus-0.10.3.tgz"
# Linux or WSL
sha256sum "/absolute/path/ophanimus-0.10.3.tgz"
```

```powershell
# Windows PowerShell
Get-FileHash -Algorithm SHA256 "C:\absolute\path\ophanimus-0.10.3.tgz"
```

Compare the entire checksum with the expected value. **Do not execute the package
if it differs.** Recheck the checksum if the file changes or you download it again.

## 2. Select the service and agent

Replace `https://your-approved-host.invalid` with the supplied origin. The example
is a placeholder, not a service. Set it in the terminal that will run the installer.

```sh
# macOS, Linux, or WSL
export OPHANIMUS_HOSTED_URL='https://your-approved-host.invalid'
```

```powershell
# Windows PowerShell
$env:OPHANIMUS_HOSTED_URL = 'https://your-approved-host.invalid'
```

The commands below select Claude Code. Replace `--client claude` with `--client codex`
or `--client cursor` for that agent. Repeat `--client` to select more than one.

Explain these changes before installation: the CLI registers the `ophanimus-forge`
MCP connection and installs the supported managed rules and hooks in your user
configuration. Claude's task hook replaces its native durable task tools with Forge
tools. Codex keeps its native goal and plan tools and adds steering guidance. Cursor's
integration is advisory. The CLI retains its runtime outside the temporary npm cache
and stores credentials under your user profile.

Preview the plan:

```sh
npm exec --yes --package="/absolute/path/ophanimus-0.10.3.tgz" -- ophanimus install --dry-run --json --client claude
```

Use the managed installer for all changes. Do not manually write MCP registrations,
rules, or hooks, or start a separate harness login.

## 3. Install and authenticate

For browser approval, run this in an interactive terminal:

```sh
npm exec --yes --package="/absolute/path/ophanimus-0.10.3.tgz" -- ophanimus install --client claude
```

Review the plan. The CLI opens or prints its browser authorization URL. The user
signs in and approves the displayed connection. An agent must not invent credentials
or approve consent for the user. Keep the terminal open until the CLI finishes. If
the agent cannot maintain an interactive terminal, the user runs this command.

For an approved API-key setup, have the user prepare a protected key file without
pasting the key into chat. Use an absolute path; on POSIX the file must be owned by
the user with no group or other permissions. On Windows, keep it inside the user's
profile with restricted access. Then run:

```sh
npm exec --yes --package="/absolute/path/ophanimus-0.10.3.tgz" -- ophanimus install --client claude --api-key-file "/absolute/path/to/protected-key-file" --non-interactive --yes
```

An existing protected `OPHANIMUS_API_KEY` environment variable can be used with
`--api-key-env` instead of `--api-key-file`. Never put the key in command arguments,
chat, logs, or harness configuration. API-key verification does not prove browser
onboarding completed.

If the installer reports unavailable service content, missing readiness evidence,
conflicting files, or authentication failure, report the exact failed step and stop.
Do not add `--allow-unproven`, `--offline`, or takeover flags to bypass a refusal;
ask the onboarding contact to resolve it or provide an explicitly approved procedure.

## 4. Activate and verify

- **Claude Code:** restart existing sessions. In a fresh session, inspect `/mcp` for
  the connected `ophanimus-forge` server and `/hooks` for the managed hooks. Confirm
  Forge tools are available and make a read-only Forge tool call.
- **Codex:** run `/hooks`, trust the Ophanimus Forge hooks, and start a new session.
  The installation is staged until this trust step and fresh verification succeed.
- **Cursor:** reload the client and check its MCP connection. Its integration does
  not deny native task tools.

Run verification for each selected client, using the same approved tarball and
`OPHANIMUS_HOSTED_URL`:

```sh
npm exec --yes --package="/absolute/path/ophanimus-0.10.3.tgz" -- ophanimus verify --client claude
```

Report the installed version, selected client, verification result, and any remaining
manual step. A downloaded package, written configuration, or staged hook is not a
working connection. Preserve failures; do not call the setup complete while checks
fail or the client cannot use Forge tools.

## 5. Repair or uninstall

Rerun the same installation command to repair managed state. If ownership checks
refuse a changed file, report the conflict instead of deleting it by hand.

To remove the selected local integration, run and review the removal plan:

```sh
npm exec --yes --package="/absolute/path/ophanimus-0.10.3.tgz" -- ophanimus uninstall --client claude
```

Plain uninstall works offline and removes only managed state whose ownership it can
establish. Credentials, retained runtime, and server-side grants may remain.
`--purge` requests additional cleanup; inspect each reported purge outcome.
`--purge --offline` does not revoke server access. Revoke remaining connections or
API keys through the app. Uninstall does not cancel billing or delete hosted tasks.

When a public npm release is approved, these instructions will name its exact
version and replace the tarball bootstrap. Until then, use the supplied artifact.
