Hawiyat Claude

One-command setup for Claude Code and OpenCode with Hawiyat's LLM provider. Smart backup, merge, uninstall, and rollback — zero runtime dependencies.

Quickstart

npx @hawiyat-team/hawiyat-claude install --token <your-hawiyat-token>

That's it. After running this command, claude sessions will transparently use Hawiyat's API for all inference.

About

Hawiyat is a managed LLM inference provider. Hawiyat Claude is the official installer that configures Claude Code to use Hawiyat as its backend. It writes the required environment variables into Claude Code's settings.json (which Claude Code natively supports since v2.1.143), installs optional plugins, and sets up OpenCode with the Hawiyat-ai provider — all without touching your shell rc files.

Every write is preceded by a timestamped backup. Every operation is reversible. Nothing is global.

Prerequisites

• Node.js >= 20 (LTS). Check with node --version.
• Claude Code CLI installed and available in your PATH. Install from code.anthropic.com.
• A Hawiyat API token — sign up at hawiyat.cloud to get one.

Installation

No global install required. Run directly via npx:

npx @hawiyat-team/hawiyat-claude install --token sk-...

The first run may prompt you to confirm overwriting existing ANTHROPIC_* env vars if they differ from Hawiyat's defaults.

Commands

install

Configure Claude Code and OpenCode for the Hawiyat provider.

| Flag | Description | Default | |-------------------------|--------------------------------------------------------|----------------------------| | --token, -t <token> | Hawiyat API token (prompts if omitted) | — | | --full, -f | Full setup: env vars + superpowers plugin | false | | --base-url <url> | Custom API base URL | https://ai.hawiyat.cloud | | --model <model> | Model name to use | claude-opus-router | | --no-opencode | Skip writing OpenCode provider config | false | | --force | Overwrite existing non-Hawiyat values without prompting | false | | --yes, -y | Skip all prompts (non-interactive mode) | false | | --debug | Verbose output with stack traces | false | | --project | Write to project-local .claude/ instead of ~/.claude/ | false | | --self-test | Run install in temp HOME, assert output, clean up (CI) | false |

Exit codes:

| Code | Meaning | |------|-------------------------------------------| | 0 | Success (already configured) | | 1 | Generic error | | 2 | Invalid input (bad token format, etc.) | | 3 | Permission denied | | 4 | Partial failure (auto-rollback attempted) | | 5 | Already installed, no changes needed |

uninstall

Remove Hawiyat configuration.

| Flag | Description | |------------------|---------------------------------------------------------------| | --purge, -p | Remove only Hawiyat-managed keys from live files (no backup) | | --debug | Verbose output with stack traces |

Default (no --purge): restores the most recent backup of each modified file. If no backup is found, you must use --purge.

update

Apply manifest deltas when the package version changes.

npx @hawiyat-team/hawiyat-claude update

Updates ANTHROPIC_BASE_URL and ANTHROPIC_MODEL to current package defaults while preserving your existing ANTHROPIC_AUTH_TOKEN.

rollback

Restore from a timestamped backup.

| Flag | Description | |--------------------------|------------------------------------------------| | --list, -l | List available backups with timestamps and SHA | | --to <timestamp> | Restore a specific backup by timestamp | | --dry-run | Preview what would be restored without writing | | --debug | Verbose output with stack traces |

# See available backups
npx @hawiyat-team/hawiyat-claude rollback --list

# Restore from a specific backup
npx @hawiyat-team/hawiyat-claude rollback --to 20260601-120000

# Preview a rollback
npx @hawiyat-team/hawiyat-claude rollback --dry-run

Full Setup

The --full flag extends the basic install with OpenCode provider configuration and plugin installation.

What --full installs

1. Claude Code env vars in ~/.claude/settings.json — same as basic install
2. OpenCode provider hawiyat-ai in ~/.config/opencode/opencode.json — enables Hawiyat models inside OpenCode
3. Superpowers plugin superpowers@claude-plugins-official — adds advanced Claude Code capabilities (test-driven development workflows, code review, branch management, and more)

npx @hawiyat-team/hawiyat-claude install --full --token sk-...

What gets written

~/.claude/settings.json (env block):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.hawiyat.cloud",
    "ANTHROPIC_AUTH_TOKEN": "sk-...",
    "ANTHROPIC_MODEL": "claude-opus-router",
    "ENABLE_TOOL_SEARCH": "true",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

~/.config/opencode/opencode.json (provider block):

{
  "provider": {
    "hawiyat-ai": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://ai.hawiyat.cloud",
        "apiKey": "sk-..."
      }
    }
  }
}

All existing keys in both files are preserved. Only the Hawiyat-managed keys are added or updated.

Updating

To update your Hawiyat Claude installation after upgrading the npm package:

npx @hawiyat-team/hawiyat-claude update

This compares the installed manifest version against the current package version and applies safe deltas — URL defaults, model names, and any new env vars that later versions introduce. Your token is preserved.

Troubleshooting

"Token not recognized" after install

1. Verify the token is present in ~/.claude/settings.json:

   node -e "console.log(JSON.parse(require('fs').readFileSync(require('path').join(require('os').homedir(), '.claude', 'settings.json'), 'utf-8')).env?.ANTHROPIC_AUTH_TOKEN?.slice(0, 8))"

2. Ensure Claude Code is restarted after installation. The env block is read at startup.
3. Check that your Hawiyat token is still valid at hawiyat.cloud/account.

Permission denied when writing settings

The installer needs write access to ~/.claude/. If you encounter permission errors:

• Ensure the .claude directory is owned by your user
• On Linux/macOS: chown -R $(whoami) ~/.claude
• On Windows: run the terminal as your normal user (not as administrator)

"Another install in progress" error

This means a previous install was interrupted. Run the install again — it will detect the stale lock and prompt you to recover.

WSL vs Native Windows

Hawiyat Claude uses os.homedir() to locate config files, which resolves correctly on both WSL and native Windows PowerShell. However:

• WSL stores configs under the Linux home directory (/home/user/.claude/). If you also use Claude Code in native Windows, you will need to run the installer in both environments.
• Native Windows stores configs under the Windows home directory (C:\Users\<you>\.claude\). PowerShell is fully supported; cmd.exe is not supported in v1.

Rollback says no backups found

If uninstall with --purge was previously run, backups are removed along with the config. The manifest retains a reference but the files are gone. You will need to reconfigure manually or re-install.

Architecture

Hawiyat Claude is an npx-installable Node.js tool that writes ANTHROPIC_* environment variables into Claude Code's settings.json env block (natively supported since Claude Code v2.1.143). It uses a smart-merge engine to preserve all user customizations, a backup manager that keeps up to 5 timestamped copies per file, and atomic writes for crash safety.

For detailed architecture documentation, see docs/ARCHITECTURE.md.

Contributing

See CONTRIBUTING.md for development setup, TDD workflow, branch strategy, and commit conventions.

Security

See SECURITY.md for token storage details, vulnerability reporting, and recommendations for high-security environments.

License

MIT — see LICENSE.