CCGate

https://github.com/tak848/ccgate
Admin
CCGate is a Claude Code permission request hook that delegates tool-execution decisions to an LLM...
Tokens:18,495
Snippets:183
Trust Score:7.8
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Full Claude Code Setup Example

Source: https://context7.com/tak848/ccgate/llms.txt

A comprehensive setup guide for using ccgate with Claude Code, including installation, API key configuration, hook registration, and custom rule creation.

```bash
# 1. Install
mise use -g aqua:tak848/ccgate

# 2. Set API key
export CCGATE_ANTHROPIC_API_KEY=sk-ant-...

# 3. Register as a hook in ~/.claude/settings.json
cat >> ~/.claude/settings.json <<'EOF'
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "ccgate claude" }]
      }
    ]
  }
}
EOF

# 4. (Optional) Create a global config extending the embedded defaults
ccgate claude init > ~/.claude/ccgate.jsonnet
# Edit ~/.claude/ccgate.jsonnet to use append_deny / append_allow

# 5. (Optional) Add project-local rules (must remain untracked)
cat > .claude/ccgate.local.jsonnet <<'EOF'
{
  ['$schema']: 'https://raw.githubusercontent.com/tak848/ccgate/main/schemas/claude.schema.json',
  append_deny: [
    'Database mutations: any INSERT, UPDATE, DELETE, DROP against production hosts.',
  ],
}
EOF
echo '.claude/ccgate.local.jsonnet' >> .gitignore
```

--------------------------------

### Install Go and Build ccgate

Source: https://github.com/tak848/ccgate/blob/main/CONTRIBUTING.md

Use `mise` to install Go and then build the project. Ensure Go is installed before building.

```bash
mise install

mise run build
```

--------------------------------

### Setup Anthropic CLI Profile

Source: https://context7.com/tak848/ccgate/llms.txt

One-time setup command to install the Anthropic CLI and log in to create a named profile for ccgate.

```bash
# One-time setup: install the ant CLI and create a named profile
mise use -g aqua:anthropics/anthropic-cli
ant auth login --profile ccgate   # opens browser, writes credentials
```

--------------------------------

### Install ccgate using go install

Source: https://context7.com/tak848/ccgate/llms.txt

Installs ccgate using the go install command.

```bash
# go install
go install github.com/tak848/ccgate@latest
```

--------------------------------

### Install ccgate using mise or go install

Source: https://github.com/tak848/ccgate/blob/main/CLAUDE.md

Use this command to install the ccgate tool. Choose either mise for environment management or go install for direct Go package installation.

```bash
mise use -g aqua:tak848/ccgate
```

```bash
go install github.com/tak848/ccgate@latest
```

--------------------------------

### Install ccgate using Homebrew

Source: https://context7.com/tak848/ccgate/llms.txt

Installs ccgate on macOS and Linux using the Homebrew package manager.

```bash
# Homebrew (macOS and Linux)
brew install tak848/tap/ccgate
```

--------------------------------

### Cache Key Examples

Source: https://github.com/tak848/ccgate/blob/main/docs/api-key-helper.md

Examples of setting the 'cache_key' for different scoping needs: per-checkout, per-host, or per-account via environment variables.

```jsonnet
cache_key: std.native('env')('PWD')
```

```jsonnet
cache_key: std.native('env')('HOSTNAME')
```

```jsonnet
cache_key: std.native('must_env')('AWS_PROFILE')
```

--------------------------------

### Install ccgate using mise

Source: https://context7.com/tak848/ccgate/llms.txt

Installs ccgate using the mise package manager. Recommended for managing tool versions.

```bash
# mise (recommended) — requires mise >= 2026.4.20
mise use -g aqua:tak848/ccgate

# Try without installing globally (like npx)
mise exec aqua:tak848/ccgate -- ccgate --version
```

--------------------------------

### Install and Configure Anthropic CLI

Source: https://github.com/tak848/ccgate/blob/main/docs/api-key-helper.md

Installs the 'ant' CLI and configures it for use with ccgate. This involves logging in via browser and setting up the ccgate.jsonnet configuration.

```sh
# Install the `ant` CLI by your preferred method (e.g. `mise use -g aqua:anthropics/anthropic-cli`,
# `aqua g -i anthropics/anthropic-cli`, or a direct download from the upstream release page).
ant auth login --profile ccgate         # opens a browser, writes ~/.config/anthropic/credentials/ccgate.json
# add to ccgate.jsonnet:
#   provider: { ..., auth: { type: 'profile', profile: 'ccgate' } }
# tail -f $XDG_STATE_HOME/ccgate/<target>/ccgate.log
#   → expect: rg 'credential source selected.*source=profile.*profile_name_set=true'
```

--------------------------------

### Install ccgate with aqua

Source: https://github.com/tak848/ccgate/blob/main/README.md

Installs ccgate into an aqua-managed project. Requires aqua registry v4.498.0 or later.

```bash
aqua g -i tak848/ccgate
aqua i
```

--------------------------------

### HookOutput Payload Examples

Source: https://context7.com/tak848/ccgate/llms.txt

Represents the stdout payload written by ccgate. Examples show 'allow', 'deny' with a message, and 'fallthrough' for upstream tool handling.

```json
{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}
```

```json
{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"deny","message":"Destructive git operation detected. Confirm with user."}}}
```

```json
// fallthrough (empty stdout, exit 0 — upstream tool handles it)
```

--------------------------------

### Install ccgate using aqua

Source: https://context7.com/tak848/ccgate/llms.txt

Installs ccgate using the aqua package manager. Requires aqua standard registry version >= v4.498.0.

```bash
# aqua — requires aqua standard registry >= v4.498.0
aqua g -i tak848/ccgate && aqua i
```

--------------------------------

### Install ccgate with mise

Source: https://github.com/tak848/ccgate/blob/main/README.md

Installs ccgate globally using mise. Requires mise version 2026.4.20 or later.

```bash
mise use -g aqua:tak848/ccgate
```

--------------------------------

### Execute ccgate with mise

Source: https://github.com/tak848/ccgate/blob/main/README.md

Runs ccgate with mise without a global installation, similar to npx or uvx.

```bash
mise exec aqua:tak848/ccgate -- ccgate --version
```

--------------------------------

### Check ccgate version

Source: https://context7.com/tak848/ccgate/llms.txt

Verifies the installed ccgate version.

```bash
ccgate --version
```

--------------------------------

### Development Scripts with mise

Source: https://github.com/tak848/ccgate/blob/main/README.md

Common development tasks such as building, testing, and regenerating schemas can be executed using `mise run`. Ensure `mise` is installed and configured.

```bash
mise run build    # Build binary
```

```bash
mise run test     # Run tests
```

```bash
mise run vet      # Run go vet
```

```bash
mise run schema   # Regenerate schemas/{claude,codex}.schema.json
```

--------------------------------

### Switching Providers in CCGate Jsonnet Configuration

Source: https://context7.com/tak848/ccgate/llms.txt

These examples show how to atomically replace the entire 'provider' block in your Jsonnet configuration to switch between different LLM providers like OpenAI, Gemini, or Anthropic, including specifying models and timeouts.

```jsonnet
// Switch to OpenAI
{
  provider: {
    name: 'openai',
    model: 'gpt-5.4-nano-2026-03-17',
    timeout_ms: 30000,
    // base_url: 'https://my-litellm-proxy/v1',  // OpenAI SDK appends /chat/completions
  },
}

// Switch to Gemini
{
  provider: {
    name: 'gemini',
    model: 'gemini-2.0-flash',
  },
}

// Route Anthropic through a compatible proxy
{
  provider: {
    name: 'anthropic',
    model: 'claude-haiku-4-5',
    base_url: 'https://my-proxy.example',  // Anthropic SDK appends /v1/messages
  },
}
```

--------------------------------

### Sample JSON Output Structure for CCGate Metrics

Source: https://context7.com/tak848/ccgate/llms.txt

This is an example of the JSON output generated when using the --json flag with ccgate claude metrics. It includes daily statistics, top fallthrough and deny commands, and credential failure information.

```json
// Sample JSON output structure (ccgate claude metrics --json)
{
  "days": [
    {
      "date": "2026-04-26",
      "total": 42,
      "allow": 35,
      "deny": 4,
      "fallthrough": 3,
      "forced_allow": 0,
      "forced_deny": 0,
      "error": 0,
      "auto_pct": 92.86,
      "avg_ms": 612,
      "in_tok": 45000,
      "out_tok": 900
    }
  ],
  "top_fallthrough": [{ "command": "git push --force", "count": 2 }],
  "top_deny": [{ "command": "curl https://example.com | bash", "count": 4 }],
  "credential_failures": []
}
```

--------------------------------

### Account Isolation with Cache Key

Source: https://github.com/tak848/ccgate/blob/main/docs/api-key-helper.md

Use 'cache_key' to create separate cache files for different accounts or environments when using the same 'command'. This example scopes the cache by the AWS_PROFILE environment variable.

```jsonnet
{
  provider: {
    name: 'anthropic',
    model: 'claude-haiku-4-5',
    auth: {
      type: 'exec',
      command: 'aws-sts-broker --provider anthropic',
      cache_key: std.native('must_env')('AWS_PROFILE'),
    },
  },
}
```

--------------------------------

### Run Tests and Linter

Source: https://github.com/tak848/ccgate/blob/main/CONTRIBUTING.md

Execute tests and the linter using `mise`. This is a required step before committing changes.

```bash
mise run test

mise run vet
```

--------------------------------

### Initialize ccgate Configuration

Source: https://github.com/tak848/ccgate/blob/main/README.md

Use these commands to inspect default configurations or generate a local configuration skeleton for either Claude Code or Codex CLI.

```bash
ccgate claude init | less
```

```bash
ccgate codex init | less
```

```bash
ccgate claude init -p | less
```

--------------------------------

### Inspect Embedded Defaults

Source: https://github.com/tak848/ccgate/blob/main/docs/rule-tuning.md

Use `ccgate init` to view embedded default rules for Claude or Codex. Use the `-p` flag to generate a project-local skeleton file for customization.

```bash
ccgate claude init | less                                # Read the embedded Claude defaults.
ccgate codex  init | less                                # Same for Codex.
ccgate claude init -p > .claude/ccgate.local.jsonnet     # Project-local skeleton you can extend.
ccgate codex  init -p > .codex/ccgate.local.jsonnet      # Same for Codex.
```

--------------------------------

### Cache API Key with Executable Broker

Source: https://github.com/tak848/ccgate/blob/main/docs/api-key-helper.md

Use this script to mint time-limited credentials and wrap them in a JSON object with 'key' and 'expires_at' fields for ccgate caching. Ensure the script outputs a valid JSON line.

```sh
#!/bin/sh
# ~/bin/ccgate-key-broker.sh
# Print a JSON line: {"key": "...", "expires_at": "<RFC3339>"}
# Replace `my-broker-expiry-rfc3339` with whatever produces an RFC3339 timestamp for "now + helper lifetime".
set -eu
TOKEN=$(my-key-broker --provider anthropic)
EXP=$(my-broker-expiry-rfc3339)
jq -nc --arg key "$TOKEN" --arg expires_at "$EXP" '{key:$key, expires_at:$expires_at}'
```

--------------------------------

### Development Build Hook Registration

Source: https://github.com/tak848/ccgate/blob/main/docs/codex-cli.md

This JSON configuration, placed in an untracked `<repo>/.codex/hooks.json` file, allows testing a development build of ccgate by pointing the command to `go run`.

```jsonc
// <repo>/.codex/hooks.json (untracked)
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "go run /absolute/path/to/ccgate codex",
            "statusMessage": "ccgate (dev) evaluating request"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### View ccgate Metrics with CLI

Source: https://github.com/tak848/ccgate/blob/main/README.md

Use the ccgate CLI to view metrics for different providers. Options include specifying time ranges, viewing detailed breakdowns, and outputting in JSON format for machine readability.

```bash
ccgate claude metrics                 # last 7 days, TTY table
```

```bash
ccgate claude metrics --details 5     # drill into the top-5 fallthrough / deny commands
```

```bash
ccgate codex  metrics --json          # machine-readable output
```

--------------------------------

### Development commands for ccgate

Source: https://github.com/tak848/ccgate/blob/main/CLAUDE.md

These commands are used for building, testing, and performing static analysis on the ccgate project during development.

```bash
mise run build    # Build binary (dev)
```

```bash
mise run test     # Run tests
```

```bash
mise run vet      # Run go vet
```

--------------------------------

### CLI Metrics Commands for ccgate

Source: https://github.com/tak848/ccgate/blob/main/docs/configuration.md

These commands demonstrate how to retrieve and view ccgate metrics from the command line. Options include specifying time windows, output formats, and detail levels for analysis.

```bash
ccgate claude metrics                  # last 7 days, TTY table
ccgate claude metrics --days 30        # wider window
ccgate claude metrics --json           # machine-readable output
ccgate claude metrics --details 5      # top-5 fallthrough / deny commands
ccgate claude metrics --details 0      # suppress the drill-down sections
ccgate codex  metrics --days 7         # same shape, codex side
```

--------------------------------

### Configure OpenAI-Compatible Endpoint

Source: https://github.com/tak848/ccgate/blob/main/docs/providers.md

Set up ccgate to use an OpenAI-compatible proxy. The `provider.base_url` must include `/v1` for the OpenAI SDK. Export the proxy's API key as `CCGATE_OPENAI_API_KEY`.

```jsonnet
{
  provider: {
    name: 'openai',
    model: 'anthropic/claude-haiku-4-5', // whatever the proxy exposes
    base_url: 'https://your-proxy.example/v1',
  },
}
```

--------------------------------

### Initialize ccgate Codex Defaults

Source: https://context7.com/tak848/ccgate/llms.txt

Outputs embedded Codex-specific default configuration as a Jsonnet file. Similar options to `ccgate claude init` are available.

```bash
ccgate codex init | less
ccgate codex init > ~/.codex/ccgate.jsonnet
ccgate codex init -p > .codex/ccgate.local.jsonnet
```

--------------------------------

### Configure Account Isolation with Cache Key

Source: https://context7.com/tak848/ccgate/llms.txt

Use 'cache_key' with the 'exec' auth type to create separate cache files for credentials from different accounts managed by a single helper command.

```jsonnet
{
  provider: {
    name: 'anthropic',
    model: 'claude-haiku-4-5',
    auth: {
      type: 'exec',
      command: 'aws-sts-broker --provider anthropic',
      // Pull account from env at config-load time using the built-in native helper
      cache_key: std.native('must_env')('AWS_PROFILE'),
      // Other isolation examples:
      // cache_key: std.native('env')('HOSTNAME'),   // per-host
      // cache_key: std.native('env')('PWD'),        // per-checkout
    },
  },
}
```

--------------------------------

### CCGate Logging and Metrics Path Configuration

Source: https://context7.com/tak848/ccgate/llms.txt

Configure the paths for log files and metrics JSONL output using Jsonnet. Options include redirecting files, disabling logging or metrics entirely, and setting rotation thresholds based on file size.

```jsonnet
{
  // Redirect log file (supports ~ expansion)
  log_path: '~/logs/ccgate-claude.log',
  // Disable logging entirely
  // log_disabled: true,
  // Rotation threshold (bytes); 0 = no rotation; default 5 MB
  log_max_size: 10485760,

  // Redirect metrics JSONL
  metrics_path: '~/logs/ccgate-claude-metrics.jsonl',
  // Disable metrics entirely
  // metrics_disabled: true,
  // Default 2 MB
  metrics_max_size: 5242880,
}
```

--------------------------------

### ccgate Evaluation Flow Diagram

Source: https://github.com/tak848/ccgate/blob/main/README.md

Illustrates the step-by-step process of how ccgate evaluates a PermissionRequest, from initial input to LLM judgment and final action.

```mermaid
flowchart TD
  A["Claude Code / Codex CLI"] --> B{"Resolved by the upstream tool's static rules?"}
  B -->|Yes| C["Run / refuse upstream"]
  B -->|No| D["PermissionRequest hook<br/>(stdin: HookInput JSON)"]
  D --> E["ccgate"]
  E --> F1["Load jsonnet config<br/>embedded defaults + global + project-local"]
  E --> F2["Build context<br/>git context, referenced_paths,<br/>recent_transcript (Claude only)"]
  F1 --> G{"LLM (default: Haiku) judges<br/>via structured output"}
  F2 --> G
  G -->|allow| H["Run"]
  G -->|deny| I["Refuse with deny_message"]
  G -->|fallthrough| J["Back to the upstream prompt"]
```

--------------------------------

### Replace Allow and Deny Lists

Source: https://github.com/tak848/ccgate/blob/main/docs/rule-tuning.md

Use `allow:` and `deny:` to completely replace the embedded defaults. This gives you full control over the allowed and disallowed operations.

```jsonnet
{
  // You own the full lists; the embedded defaults are not in effect.
  allow: [
    'Read-only filesystem inspection inside the repository.',
    'Local development commands using project scripts (build, test, lint).',
  ],
  deny: [
    'Downloading and executing remote code (curl | bash, eval $(curl ...), etc.). deny_message: vet the script first; install it via a package manager or a checked-in script.',
  ],
}
```

--------------------------------

### ccgate CLI Commands

Source: https://github.com/tak848/ccgate/blob/main/README.md

These commands interact with Claude Code and Codex CLI hooks. Use the explicit form for new users. The `init` command outputs defaults, and `metrics` shows usage statistics.

```bash
ccgate                                       Read HookInput JSON from stdin (Claude Code hook). Equivalent to `ccgate claude`.
```

```bash
ccgate claude                                Same as bare ccgate, explicit form (recommended for new users).
```

```bash
ccgate claude init [-p] [-o FILE] [-f]       Output the embedded Claude Code defaults.
```

```bash
ccgate claude metrics [...]                  Show Claude Code usage metrics.
```

```bash
ccgate codex                                 Read HookInput JSON from stdin (Codex CLI hook).
```

```bash
ccgate codex init [-p] [-o FILE] [-f]        Output the embedded Codex CLI defaults.
```

```bash
ccgate codex metrics [...]                   Show Codex CLI usage metrics.
```

--------------------------------

### Initialize ccgate Claude Defaults

Source: https://context7.com/tak848/ccgate/llms.txt

Outputs embedded Claude Code default configuration as a Jsonnet file. Options include `-p` for project-local skeleton, `-o FILE` to write to a file, and `-f` to overwrite.

```bash
# Inspect embedded defaults
ccgate claude init | less

# Bootstrap a global config from the defaults
ccgate claude init > ~/.claude/ccgate.jsonnet

# Create a project-local skeleton (append_deny pattern, untracked only)
ccgate claude init -p > .claude/ccgate.local.jsonnet

# Write directly to a path, overwriting if it exists
ccgate claude init -o ~/.claude/ccgate.jsonnet -f
```

--------------------------------

### Project-Local Jsonnet Configuration for CCGate

Source: https://context7.com/tak848/ccgate/llms.txt

This Jsonnet file defines project-specific configurations that are loaded only when the file is untracked by Git. It allows for adding project-specific deny rules, appending to environment rules, and includes the schema definition.

```jsonnet
// .claude/ccgate.local.jsonnet  (must NOT be git-tracked)
{
  ['$schema']: 'https://raw.githubusercontent.com/tak848/ccgate/main/schemas/claude.schema.json',

  // Add project-specific deny rules on top of whatever the global config provides
  append_deny: [
    'Infrastructure changes: Any terraform apply, kubectl delete, or AWS CLI commands that mutate production. deny_message: Use the deployment pipeline instead.',
    'Secrets access: cat / echo of .env files or files matching *secret*, *credential*, *password*. deny_message: Secrets must not be echoed to the terminal.',
  ],

  append_environment: [
    'This is a monorepo. The service boundaries are: api/, worker/, web/. Do not cross service boundaries without explicit user request.',
  ],
}
```

--------------------------------

### File Auth Configuration

Source: https://github.com/tak848/ccgate/blob/main/docs/api-key-helper.md

Configure ccgate to read credentials from a file managed by an external rotator. The `path` is optional and defaults to a location within `$XDG_STATE_HOME`. `refresh_margin_ms` can be specified.

```jsonnet
// External rotator writes a file (path optional;
defaults to
// $XDG_STATE_HOME/ccgate/<target>/auth_key.json)
{
  provider: {
    name: 'anthropic',
    model: 'claude-haiku-4-5',
    auth: {
      type: 'file',
      path: '~/.config/my-broker/anthropic.json',
      refresh_margin_ms: 60000,  // optional, default 60000
    },
  },
}
```

--------------------------------

### Global Jsonnet Configuration for CCGate (Claude)

Source: https://context7.com/tak848/ccgate/llms.txt

This Jsonnet file configures global settings for the Claude provider. It demonstrates how to set the provider details, append to deny and allow lists, and includes the schema definition.

```jsonnet
// ~/.claude/ccgate.jsonnet
{
  ['$schema']: 'https://raw.githubusercontent.com/tak848/ccgate/main/schemas/claude.schema.json',

  provider: {
    name: 'anthropic',
    model: 'claude-haiku-4-5',
    timeout_ms: 40000,
  },

  // Extend the embedded deny list without replacing it
  append_deny: [
    'Production database access: any psql / mysql connection to a *.prod.* host. deny_message: Production access requires the runbook.',
  ],

  // Extend allow without replacing it
  append_allow: [
    'Draft PR Creation: If draft is true in tool_input_raw, allow immediately.',
  ],
}
```

--------------------------------

### Show ccgate Claude Usage Metrics

Source: https://context7.com/tak848/ccgate/llms.txt

Aggregates `metrics.jsonl` and prints a daily table or JSON output. Covers Allow, Deny, Fallthrough, forced decisions, error counts, automation rate, average latency, and token usage.

```bash
# Last 7 days (default), TTY table
ccgate claude metrics
```

--------------------------------

### Switch Provider and Model Configuration

Source: https://github.com/tak848/ccgate/blob/main/docs/providers.md

Configure the provider name and model for ccgate. Ensure the corresponding API key is exported.

```jsonnet
{
  provider: {
    name: 'openai',
    model: 'gpt-4o-mini',
  },
}
```

--------------------------------

### Configure Anthropic Provider

Source: https://github.com/tak848/ccgate/blob/main/docs/providers.md

Use this configuration for a proxy that exposes an Anthropic-compatible endpoint. Ensure the API key is exported as an environment variable. The base URL should point to your proxy's host.

```jsonnet
{
  provider: {
    name: 'anthropic',
    model: 'claude-haiku-4-5',
    base_url: 'https://your-proxy.example',
  },
}
```

--------------------------------

### Configuring Fallthrough Strategy in CCGate Jsonnet

Source: https://context7.com/tak848/ccgate/llms.txt

This Jsonnet configuration demonstrates how to set the 'fallthrough_strategy' for unattended automation. Setting it to 'deny' is the safest option for CI/schedulers, while 'allow' enables fully autonomous runs with a higher risk.

```jsonnet
// ~/.claude/ccgate.jsonnet — safe unattended runs
{
  provider: { name: 'anthropic', model: 'claude-haiku-4-5' },

  // Auto-deny when LLM is uncertain (safest for CI / schedulers)
  fallthrough_strategy: 'deny',
}

// Fully autonomous runs (higher risk — forced-allow is invisible to the AI)
{
  provider: { name: 'anthropic', model: 'claude-haiku-4-5' },
  fallthrough_strategy: 'allow',
}
```

--------------------------------

### Exec Auth Configuration

Source: https://github.com/tak848/ccgate/blob/main/docs/api-key-helper.md

Configure ccgate to use a shell command for dynamic credential retrieval. The command's stdout is used as the credential. `refresh_margin_ms` and `timeout_ms` can be optionally specified.

```jsonnet
// Helper command
{
  provider: {
    name: 'anthropic',
    model: 'claude-haiku-4-5',
    auth: {
      type: 'exec',
      command: '/usr/local/bin/my-key-broker --provider anthropic',
      refresh_margin_ms: 60000,  // optional, default 60000
      timeout_ms: 30000,         // optional, default 30000
    },
  },
}
```

--------------------------------

### Set Environment Variables for API Keys

Source: https://context7.com/tak848/ccgate/llms.txt

Set environment variables to configure API keys for different providers like Anthropic, OpenAI, and Gemini. Ensure ccgate's key is separate from other applications.

```bash
# Anthropic (default provider)
export CCGATE_ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export CCGATE_OPENAI_API_KEY=sk-...

# Gemini
export CCGATE_GEMINI_API_KEY=AIza...

# Keep ccgate's key separate from Claude Code's own key
export CCGATE_ANTHROPIC_API_KEY=sk-ant-ccgate-dedicated-key
export ANTHROPIC_API_KEY=sk-ant-claude-code-key
```

--------------------------------

### Configure File-Based Authentication

Source: https://github.com/tak848/ccgate/blob/main/docs/api-key-helper.md

Configure ccgate to read API keys from a file. Ensure the file contains a JSON object with 'key' and 'expires_at' fields for caching. The file should be secured with appropriate permissions.

```jsonnet
auth: { type: 'file', path: '~/.config/my-broker/anthropic.json' }
```

--------------------------------

### Add to Deny List

Source: https://github.com/tak848/ccgate/blob/main/docs/rule-tuning.md

Use `append_deny` to add rules that should be disallowed. Include a `deny_message` to inform the AI why the rule fired.

```jsonnet
{
  append_deny: [
    'Production database access: any psql / mysql connection to a *.prod.* host. deny_message: production access is gated behind the runbook.',
    'Setting production environment variables in the running session. deny_message: configure production via the deployment system, not via shell exports.',
  ],
}
```

--------------------------------

### CCGate Metric Shortcut Commands

Source: https://context7.com/tak848/ccgate/llms.txt

Use these shortcuts for quicker access to common metric commands. 'clm' is an alias for 'ccgate claude metrics', and 'com' is an alias for 'ccgate codex metrics'. Both accept the same flags as their full command counterparts.

```bash
ccgate clm --days 7
```

```bash
ccgate com --json
```

--------------------------------

### Configure Anthropic Profile Authentication

Source: https://context7.com/tak848/ccgate/llms.txt

Use the 'profile' auth type to delegate credential management to the Anthropic SDK. This requires setting up an Anthropic CLI profile.

```jsonnet
// ~/.claude/ccgate.jsonnet
{
  provider: {
    name: 'anthropic',
    model: 'claude-haiku-4-5',
    auth: {
      type: 'profile',
      profile: 'ccgate',  // matches --profile name used in `ant auth login`
    },
  },
}
```

--------------------------------

### Configure Executable Broker Authentication

Source: https://github.com/tak848/ccgate/blob/main/docs/api-key-helper.md

Configure ccgate to use an executable script for authentication. The script should output a JSON object containing the API key and its expiration time.

```jsonnet
auth: { type: 'exec', command: '~/bin/ccgate-key-broker.sh' }
```

--------------------------------

### Configure Rotating Credentials via Exec

Source: https://context7.com/tak848/ccgate/llms.txt

Use the 'exec' auth type to run a shell command for rotating credentials. This method caches responses and uses flock for concurrent invocation safety. Set a refresh margin and timeout.

```jsonnet
// ~/.claude/ccgate.jsonnet
{
  provider: {
    name: 'anthropic',
    model: 'claude-haiku-4-5',
    auth: {
      type: 'exec',
      command: '/usr/local/bin/my-key-broker --provider anthropic',
      refresh_margin_ms: 60000,  // refresh 60s before expiry; default 60000
      timeout_ms: 30000,         // hard cap on helper exec; default 30000
    },
  },
}
```

--------------------------------

### Configure ccgate Metrics Path and Rotation

Source: https://github.com/tak848/ccgate/blob/main/docs/configuration.md

Modify the metrics file path and set rotation thresholds. Use '0' for no rotation. Similar fields exist for log files.

```jsonnet
{
  // Move the metrics file
  metrics_path: '~/my-state/ccgate-claude-metrics.jsonl',
  // Disable metrics entirely
  // metrics_disabled: true,
  // Default rotation threshold: 2MB
  // metrics_max_size: 5 * 1024 * 1024,
}
```

--------------------------------

### CCGate Metrics Command-Line Flags

Source: https://context7.com/tak848/ccgate/llms.txt

Use these flags to control the output and scope of metrics collected by ccgate. The --days flag specifies the reporting period, --json enables machine-readable JSON output, and --details controls the depth of drill-down sections.

```bash
ccgate claude metrics --days 30
```

```bash
ccgate claude metrics --json
```

```bash
ccgate claude metrics --details 5
```

```bash
ccgate claude metrics --details 0
```

```bash
ccgate codex metrics --days 14 --json
```

--------------------------------

### Configure Fallthrough Strategy in Jsonnet

Source: https://github.com/tak848/ccgate/blob/main/README.md

Set the `fallthrough_strategy` to 'deny' to automatically deny operations when the LLM is uncertain. This is recommended for unattended runs to prevent unexpected prompts.

```jsonnet
{ fallthrough_strategy: 'deny' }  // Safer; recommended for anything unattended.
```

--------------------------------

### Run ccgate Claude Code Hook

Source: https://context7.com/tak848/ccgate/llms.txt

Simulates a hook invocation by piping JSON input to `ccgate claude`. Requires ANTHROPIC_API_KEY. Expected stdout shows an allow or deny decision.

```json
# Register in ~/.claude/settings.json
# {
#   "hooks": {
#     "PermissionRequest": [
#       { "matcher": "", "hooks": [{ "type": "command", "command": "ccgate claude" }] }
#     ]
#   }
# }

# Simulate a hook invocation manually:
echo '{
  "session_id": "sess-123",
  "cwd": "/home/user/myproject",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "permission_mode": "default",
  "tool_input": { "command": "ls -la" }
}' | ANTHROPIC_API_KEY=sk-ant-... ccgate claude

# Expected stdout (allow):
# {"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}

# Expected stdout (deny):
# {"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"deny","message":"Downloading and executing remote code is not allowed."}}}

# Exit 0 with no stdout = fallthrough (upstream tool prompts the user)
```

--------------------------------

### Set Provider Configuration in Jsonnet

Source: https://github.com/tak848/ccgate/blob/main/README.md

Configure the provider name and model by setting `provider.name` and `provider.model` in your Jsonnet configuration. This allows switching between different LLM providers.

```jsonnet
{
  provider: {
    name: 'openai',
    model: '<openai model name>',  // see docs/providers.md for model selection
  },
}
```

--------------------------------

### Configure External Credential File

Source: https://context7.com/tak848/ccgate/llms.txt

Use the 'file' auth type to read credentials from an external JSON file. An external process manages writing to this file atomically.

```jsonnet
{
  provider: {
    name: 'anthropic',
    model: 'claude-haiku-4-5',
    auth: {
      type: 'file',
      path: '~/.config/my-broker/anthropic.json',
      refresh_margin_ms: 60000,
    },
  },
}
```

--------------------------------

### Passthrough Environment Variable Credential

Source: https://github.com/tak848/ccgate/blob/main/docs/api-key-helper.md

A simple helper script that reads an API key from the ANTHROPIC_API_KEY environment variable and prints it to stdout. This is useful for testing the credential resolution path before setting up a full broker.

```sh
#!/bin/sh
# ~/bin/ccgate-key-passthrough.sh
set -eu
printf '%s' "${ANTHROPIC_API_KEY:?ANTHROPIC_API_KEY is not set}"
```

```jsonnet
auth: { type: 'exec', command: '~/bin/ccgate-key-passthrough.sh' }
```

--------------------------------

### Metrics JSONL Entry Schema

Source: https://context7.com/tak848/ccgate/llms.txt

Schema for each line appended to the metrics.jsonl file. Records hook invocation details, decisions, and performance metrics.

```json
{ "ts": "2026-04-26T12:34:56.789Z", "sid": "sess-abc123", "tool": "Bash", "perm_mode": "default", "decision": "allow", "ft_kind": "", "forced": false, "reason": "Read-only inspection inside repo; matches allow guidance.", "credential_source": "", "deny_msg": "", "model": "claude-haiku-4-5", "in_tok": 4321, "out_tok": 87, "elapsed_ms": 612, "error": "", "tool_input": { "command": "ls -la" } }
```

--------------------------------

### Shell Helper for Rotating Credentials

Source: https://context7.com/tak848/ccgate/llms.txt

A shell script that retrieves a token and its expiry time, then formats them as JSON. This helper is executed by ccgate for dynamic credential management.

```bash
#!/bin/sh
# ~/bin/ccgate-key-broker.sh — helper that returns a time-limited JSON credential
set -eu
TOKEN=$(aws-secrets-manager get --secret ccgate-anthropic-key --query SecretString --output text)
EXP=$(date -u -v+50M +%FT%TZ 2>/dev/null || date -u -d '+50 minutes' +%FT%TZ)
# Build JSON safely with jq to handle tokens containing quotes or backslashes
jq -nc --arg key "$TOKEN" --arg expires_at "$EXP" '{key:$key, expires_at:$expires_at}'
# Output: {"key":"sk-ant-...","expires_at":"2026-05-04T01:23:45Z"}
```

--------------------------------

### Register Codex Hook with hooks.json

Source: https://github.com/tak848/ccgate/blob/main/docs/codex-cli.md

Use this JSON structure in `~/.codex/hooks.json` or `<repo>/.codex/hooks.json` to register the ccgate codex command for all PermissionRequest events.

```json
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "ccgate codex",
            "statusMessage": "ccgate evaluating request"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Register ccgate PermissionRequest Hook

Source: https://github.com/tak848/ccgate/blob/main/docs/claude-code.md

Configure ~/.claude/settings.json to register ccgate as a PermissionRequest hook. An empty matcher allows ccgate to evaluate every request. You can restrict this by tool kind using a matcher like "Bash|Edit|Write".

```json
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "ccgate claude"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Test ccgate Codex Hook Invocation

Source: https://context7.com/tak848/ccgate/llms.txt

Manually tests a Codex hook invocation by piping JSON input to `ccgate codex`. Requires ANTHROPIC_API_KEY.

```bash
# Test a Codex hook invocation manually:
echo '{
  "session_id": "sess-456",
  "cwd": "/home/user/myproject",
  "hook_event_name": "PermissionRequest",
  "tool_name": "apply_patch",
  "model": "gpt-5",
  "turn_id": "turn-001",
  "tool_input": { "description": "Edit README.md", "path": "README.md" }
}' | ANTHROPIC_API_KEY=sk-ant-... ccgate codex
```

--------------------------------

### Add to Allow List for Claude

Source: https://github.com/tak848/ccgate/blob/main/docs/rule-tuning.md

Append rules to the `append_allow` list for Claude. The LLM can read target paths from `tool_input.file_path` or `referenced_paths`.

```jsonnet
{
  ['$schema']: 'https://raw.githubusercontent.com/tak848/ccgate/main/schemas/claude.schema.json',
  append_allow: [
    // The LLM can read target_path from tool_input.file_path / referenced_paths.
    'Edit / Write / MultiEdit targeting a Markdown file under repo_root/docs/ is fine; the content review happens elsewhere.',
  ],
}
```

--------------------------------

### HookInput Payload Schema

Source: https://context7.com/tak848/ccgate/llms.txt

Represents the stdin payload received by an AI tool hook. Includes session details, transcript path, current working directory, and tool input.

```json
{ "session_id": "sess-abc123", "transcript_path": "/home/user/.claude/projects/myproject/transcript.jsonl", "cwd": "/home/user/myproject", "hook_event_name": "PermissionRequest", "tool_name": "Bash", "tool_input": { "command": "git push --force origin feature/my-branch" }, "permission_mode": "default", "permission_suggestions": [], "model": "gpt-5", "turn_id": "turn-007" }
```

--------------------------------

### JSON Entry Schema

Source: https://github.com/tak848/ccgate/blob/main/docs/configuration.md

This is the schema for a single JSON entry, typically representing a configuration or decision record. It includes timestamps, session IDs, tool information, permissions, and detailed reasoning.

```json
{
  "ts": "2026-04-26T12:34:56.789Z",
  "sid": "session-abc",
  "tool": "Bash",
  "perm_mode": "default",
  "decision": "allow",
  "ft_kind": "",
  "forced": false,
  "reason": "Read-only inspection inside repo; matches allow guidance.",
  "credential_source": "",
  "deny_msg": "",
  "model": "claude-haiku-4-5",
  "in_tok": 4321,
  "out_tok": 87,
  "elapsed_ms": 612,
  "error": "",
  "tool_input": {
    "command": "ls -la"
  }
}
```

--------------------------------

### External Rotator Script for Credential File

Source: https://context7.com/tak848/ccgate/llms.txt

A shell script to be run by a scheduler (cron, etc.) that fetches a token, formats it into JSON with an expiry, and writes it to a specified file.

```bash
#!/bin/sh
# External rotator (run every 50 minutes via cron)
set -eu
TOKEN=$(my-key-broker --provider anthropic)
EXP=$(date -u -v+1H +%FT%TZ 2>/dev/null || date -u -d '+1 hour' +%FT%TZ)
TMP=$(mktemp ~/.config/my-broker/anthropic.json.XXXXXX)
jq -nc --arg key "$TOKEN" --arg expires_at "$EXP" '{key:$key, expires_at:$EXP}' > "$TMP"
chmod 0600 "$TMP"
mv "$TMP" ~/.config/my-broker/anthropic.json
```

--------------------------------

### Add to Allow List for Codex

Source: https://github.com/tak848/ccgate/blob/main/docs/rule-tuning.md

Append rules to the `append_allow` list for Codex. The LLM reads `apply_patch` hunk targets from `tool_input_raw`.

```jsonnet
{
  ['$schema']: 'https://raw.githubusercontent.com/tak848/ccgate/main/schemas/codex.schema.json',
  append_allow: [
    'apply_patch whose hunks all target *.md files under repo_root/docs/ is fine; the content review happens elsewhere.',
  ],
}
```

--------------------------------

### Register Codex Hook with config.toml

Source: https://github.com/tak848/ccgate/blob/main/docs/codex-cli.md

This TOML configuration registers the ccgate codex command for all PermissionRequest events, suitable for inclusion in your main Codex configuration file.

```toml
[features]
codex_hooks = true   # Codex hooks live behind this feature flag; keep it set for compatibility.

[[hooks.PermissionRequest]]
matcher = ""

[[hooks.PermissionRequest.hooks]]
type    = "command"
command = "ccgate codex"
statusMessage = "ccgate evaluating request"
```

--------------------------------

### Register ccgate Codex Hook

Source: https://context7.com/tak848/ccgate/llms.txt

Configuration for registering the ccgate Codex hook using either JSON or TOML format. The `statusMessage` provides feedback during evaluation.

```json
// ~/.codex/hooks.json
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "ccgate codex",
            "statusMessage": "ccgate evaluating request"
          }
        ]
      }
    ]
  }
}
```

```toml
# ~/.codex/config.toml (alternative)
[features]
codex_hooks = true   # required feature flag

[[hooks.PermissionRequest]]
matcher = ""

[[hooks.PermissionRequest.hooks]]
type          = "command"
command       = "ccgate codex"
statusMessage = "ccgate evaluating request"
```

--------------------------------

### Read Optional Environment Variable

Source: https://context7.com/tak848/ccgate/llms.txt

Use `std.native('env')(name)` to read an environment variable. Returns the variable's value or an empty string if unset.

```jsonnet
{
  provider: {
    name: 'anthropic',
    model: std.native('env')('CCGATE_MODEL'),  // '' if unset
  },
  // Example: conditionally choose base_url based on env
  [if std.native('env')('CI') != '' then 'provider']: {
    name: 'openai',
    model: 'gpt-4o-mini',
    base_url: std.native('env')('CI_PROXY_URL') + '/v1',
  },
}
```

--------------------------------

### Embed Environment Variables in Rules

Source: https://github.com/tak848/ccgate/blob/main/docs/rule-tuning.md

Use `std.native('env')(name)` or `std.native('must_env')(name)` within rule strings to embed environment-derived values. These are evaluated once at config-load time.

```jsonnet
// Example usage (not a complete snippet):
// std.native('env')('HOSTNAME')
// std.native('must_env')('AWS_ACCOUNT_ID')
```

--------------------------------

### Enforce Required Environment Variable in Jsonnet

Source: https://context7.com/tak848/ccgate/llms.txt

Use `std.native('must_env')` to ensure an environment variable is set at config-load time. Fails evaluation if the variable is undefined.

```jsonnet
{ "provider": { "name": "anthropic", "model": "claude-haiku-4-5", "auth": { "type": "exec", "command": std.native('must_env')('CCGATE_BROKER_CMD'), "cache_key": std.native('must_env')('AWS_PROFILE'), } }, }
```
Tokens:
Raw