global-permission 0.0.3

gperm

gperm is a unified permission manager for multiple AI coding agent CLIs.

It keeps permission profiles in one place, applies them to native config files when possible, and falls back to inline CLI flags when a tool does not expose persistent project-level settings.

Japanese README: README.ja.md

Features

• Unified permission profiles for claude, geminicli, copilot, codex, opencode, and antigravity
• Global config under XDG_CONFIG_HOME/gperm/config.toml
• Project override under ./.gperm/config.toml with higher precedence
• gperm config show displays the active config source chain
• gperm check shows drift between desired and native settings
• gperm sync updates native settings, interactive by default
• gperm inline prints inline flags for agents that support runtime permission flags
• gperm exec runs the target CLI with expanded inline flags
• Locale-aware CLI messages: English by default, Japanese when LANG / LC_* starts with ja

Supported agents

Native config locations

Install

uv sync
uv run gperm --help

One-line installer:

curl -sSL https://raw.githubusercontent.com/igtm/global-permission/main/install.sh | bash

Commands

gperm --help
gperm --version
gperm agents
gperm import claude ~/.claude/settings.json
gperm import opencode ~/.config/opencode/opencode.jsonc
gperm doctor
gperm config init
gperm config show
gperm check
gperm sync
gperm inline codex
gperm exec copilot -- -p "review this repo"

Config resolution

Resolution order:

1. Built-in defaults
2. XDG_CONFIG_HOME/gperm/config.toml
3. ./.gperm/config.toml

The project-local ./.gperm/config.toml wins over the XDG config.

Example config

version = 1
default_profile = "balanced"

[profiles.safe]
approval = "plan"
sandbox = "read-only"
trust = false

[profiles.balanced]
approval = "default"
sandbox = "workspace-write"
trust = true
allow_shell = ["git status", "git diff"]
deny_shell = ["git push"]

[agents.codex]
profile = "balanced"
command = "codex"

[project]
profile = "safe"

Import native settings

Import a Claude or OpenCode native config into gperm:

gperm import claude ~/.claude/settings.json
gperm import opencode ~/.config/opencode/opencode.jsonc

Behavior:

• Claude global config imports into ~/.config/gperm/config.toml
• OpenCode global config imports into ~/.config/gperm/config.toml
• Project-local source files import into ./.gperm/config.toml
• Imported profiles default to imported-claude or imported-opencode

Notes

• gperm updates only permission-related keys and leaves unrelated settings intact.
• JSONC files are parsed correctly, but comments and whitespace may be normalized on write.
• For agents that cannot persist some permission concepts natively, gperm reports the gap instead of silently dropping it.
• Gemini sidecar policy files are generated under ~/.config/gperm/generated/ or ./.gperm/generated/.
• install.sh installs gperm, creates a starter config when missing, and runs gperm doctor.

Release automation

Merged PRs into main can trigger an automatic release when the PR carries exactly one of these labels:

• release:patch
• release:minor
• release:major

The repository now includes:

• prepare-release.yml
• publish-release.yml
• scripts/release.py

Required GitHub secrets:

• RELEASE_GITHUB_TOKEN
• PYPI_API_TOKEN

For a smoke test, a docs-only PR with one release label is enough to exercise the full pipeline.

References

• Claude Code permissions: https://code.claude.com/docs/en/permissions
• Claude Code settings: https://code.claude.com/docs/en/settings
• Gemini CLI policy engine: https://geminicli.com/docs/reference/policy-engine/
• GitHub Copilot CLI config: https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/configure-copilot-cli
• OpenCode permissions: https://opencode.ai/docs/ja/permissions/
• Codex config basics: https://developers.openai.com/codex/config-basics
• Codex config reference: https://developers.openai.com/codex/config-reference