Cygnal Code

Cygnal Code is Gray Swan's plugin for AI coding agents. It monitors tool calls from Codex, ChatGPT desktop with Codex, and Claude Code, then sends activity to Gray Swan so Cygnal can evaluate the agent's behavior against your policies.

Cygnal Code monitors tool calls through the PreToolUse hook.

Getting Started

To get started with Cygnal Code:

1. Check prerequisites

Before installing Cygnal Code, make sure you have:

• A Cygnal Code-enabled Gray Swan workspace
• A Gray Swan API key
• Codex CLI 0.131.0 or newer if you use Codex in a terminal
• Claude Code 2.1.147 or newer if you use Claude Code
• Python 3.9 or newer, available as python3
• Git
• curl

2. Get your personalized installer

The Cygnal Code installer is generated for each Cygnal Code workspace.

1. Sign in to your Cygnal Code-enabled workspace at platform.grayswan.ai
2. Open the Get Started page
3. Run your personalized installer command in a terminal
4. Enter your API key when prompted by the installer

Your installer command will look similar to this:

curl -fsSL 'https://platform.grayswan.ai/cygnal-code/install.sh?token=...' | bash

3. Follow the installer prompts

After you run the command, the installer will:

• Detect whether codex and/or claude are available on your PATH
• Let you install Cygnal Code for the supported agents available on your machine
• Add the Gray Swan plugin marketplace
• Install the cygnal-guardrail plugin
• Write Codex Cygnal config to ~/.cygnal/config.json when Codex support is installed
• Run a preflight check

Use With Codex

After installation:

1. Open a Codex session in the terminal or the ChatGPT desktop app
2. Run /hooks
3. Trust the cygnal-guardrail hook
4. Use Codex normally

Once the hook is trusted, Codex tool calls should appear in Gray Swan activity.

Use With Claude Code

After installation:

1. Restart Claude Code, or run /reload-plugins if Claude Code is already running
2. Use Claude Code normally

Claude Code tool calls should appear in Gray Swan activity after the plugin is loaded.

Verification

To verify that Cygnal Code protection is active:

1. Ask Codex or Claude Code to make a simple tool call, such as running:

   pwd

2. Monitor your dashboard at platform.grayswan.ai/activity to see tool calls, policy evaluations, and any security violations or alerts.

Uninstall

The Cygnal Code uninstaller is available from the same Get Started page as the installer.

1. Sign in to your Cygnal Code-enabled workspace at platform.grayswan.ai
2. Open the Get Started page
3. Copy the uninstall command and paste it into a terminal on the same machine where the plugin was installed

The uninstaller removes the Cygnal Code plugin and Gray Swan plugin marketplace from supported agents on the same machine.

Troubleshooting

If Cygnal Code does not install or activity does not appear in Gray Swan:

• Confirm python3 is installed and is version 3.9 or newer
• Confirm Git is installed
• Confirm curl is installed
• Confirm codex or claude is available on your PATH
• If you use Codex in a terminal, confirm Codex CLI is version 0.131.0 or newer
• Confirm Claude Code is version 2.1.147 or newer
• Confirm your Gray Swan API key starts with gsa-sk-
• Run the installer command in a terminal, not inside Codex, ChatGPT desktop, or Claude Code
• For Codex, run /hooks and trust the cygnal-guardrail hook
• For Claude Code, restart Claude Code or run /reload-plugins

If you are not using a Cygnal Code-enabled workspace, the Get Started page will not show the installer or uninstaller commands.