@gitconductor/cli

Prevent git mistakes before they happen — rules, education, and recovery guidance.

gitconductor intercepts your git commands and enforces safety rules — blocking force-pushes to protected branches, detecting committed secrets, warning about direct commits to main, and more. Works entirely offline; AI is optional.

Install

npm install -g @gitconductor/cli

Then set up the shell alias (intercepts all git commands):

gitconductor install --global
source ~/.zshrc   # or ~/.bashrc for bash, or open a new terminal

Or set up for a single repo only (no shell alias):

gitconductor install

Requirements

• Node.js ≥ 18
• bash, zsh, or fish shell (macOS, Linux, or Windows via Git Bash / WSL)

Commands

| Command | Description | |---|---| | gitconductor install [--global] | Set up for this repo, or globally with the shell alias | | gitconductor status | Show active config and all rules | | gitconductor check | Proactive workspace health scan | | gitconductor rescue [scenario] | Step-by-step recovery from common git mistakes | | gitconductor explain <rule> | Deep docs for a rule: why it exists, how to recover | | gitconductor log [--limit N] | Recent interception history | | gitconductor ask "<question>" | AI-powered git Q&A (requires AI provider) | | gitconductor config set <key> <value> | Change a config value | | gitconductor config show | Print merged config as YAML | | gitconductor uninstall [--global] | Remove gitconductor |

13 Built-in Rules

| Rule | Default | Severity | |---|---|---| | forcePushProtectedBranch | on | block | | secretDetection | on | block | | wipCommit | on | block | | directCommitToProtectedBranch | on | warn | | hardResetWithChanges | on | warn | | largePush | on | warn | | rebaseSharedBranch | on | warn | | deleteBranchWithOpenPR | on | warn | | mergeIntoProtectedBranch | on | warn | | tagDeletion | on | warn | | stashDrop | on | warn | | amendPublishedCommit | on | warn | | commitMessageFormat | off | warn |

Configuration

gitconductor merges config from three sources (in order):

1. Built-in defaults
2. ~/.gitconductor/config.yml (global)
3. .gitconductor.yml in the repo root

Example .gitconductor.yml:

protectedBranches:
  - main
  - master
  - release/*

rules:
  commitMessageFormat:
    enabled: true
    severity: warn

ai:
  provider: anthropic
  model: claude-opus-4-6

Set config from the CLI:

gitconductor config set rules.commitMessageFormat.enabled true
gitconductor config set ai.provider anthropic --global
gitconductor config unset ai.apiKey --global

AI Providers (optional)

gitconductor works fully without AI. Configure one for richer analysis:

# Anthropic
gitconductor config set ai.provider anthropic --global
export GITCONDUCTOR_AI_KEY=sk-ant-...

# OpenAI
gitconductor config set ai.provider openai --global
export GITCONDUCTOR_AI_KEY=sk-...

# Ollama (local, no API key needed)
gitconductor config set ai.provider ollama --global
gitconductor config set ai.model llama3 --global

Disable Temporarily

gitconductor config set enabled false
# ... do your thing ...
gitconductor config set enabled true

Links

• Documentation
• GitHub
• Changelog
• @gitconductor/core — rule engine (for building custom integrations)

License

MIT