JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 15
  • Score
    100M100P100Q52129F
  • License MIT

A sacred covenant between machine and man. Accountability gates for AI agents.

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@probelabs/vow) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    🤝 Vow

    npm version License: MIT Website

    A pinky promise between robot and human representing the sacred covenant of AI accountability

    A sacred covenant between machine and man. Accountability gates for AI agents.

    Vow ensures AI agents pause and honestly self-review before taking action. No shortcuts. No lies. No claiming completion without actual completion.

    ✨ Features

    • 🛡️ Accountability Gates - AI must affirm checklist requirements before proceeding
    • 📝 Customizable Rules - Override default vows with your own requirements
    • 🔌 Universal Integration - Works with git hooks, Husky, Claude Code, and any trigger
    • 🎯 Zero Config - Sensible defaults that work out of the box
    • 🪶 Lightweight - 40 lines of JavaScript, no dependencies

    🚀 Quick Start

    npx -y @probelabs/vow@latest install

    This will:

    • Detect your git setup (including worktrees and custom hooks)
    • Find existing hook managers (Husky, pre-commit, etc.)
    • Detect AI tools (Claude Code, Cursor)
    • Let you choose where to install Vow
    • Uses AGENT_VOW.md for rules (local if exists, otherwise from package)

    Non-Interactive Installation

    # Auto-detect and install everywhere applicable
npx -y @probelabs/vow@latest install --yes

# Install only in specific locations
npx -y @probelabs/vow@latest install --git     # Git hooks only
npx -y @probelabs/vow@latest install --husky   # Husky only
npx -y @probelabs/vow@latest install --claude  # Claude Code only

    📖 How It Works

    The Flow

    1. AI attempts an action (e.g., git commit)
    2. Vow intercepts via configured hook
    3. Rules are displayed from AGENT_VOW.md
    4. AI must self-assess against each requirement
    5. Consent required - AI creates .AGENT_CONSENT file with '1'
    6. Action proceeds only after consent

    Technical Details

    • Hook Integration: Vow installs as a git pre-commit hook or similar
    • Exit Codes: Returns 1 (block) if no consent, 0 (allow) if consent given
    • Consent File: .AGENT_CONSENT file created to indicate consent
    • Auto-cleanup: Consent file is removed after check
    • Rules Source: Uses local AGENT_VOW.md if exists, otherwise uses package's AGENT_VOW.md

    🎯 Use Cases

    Git Commit Hooks

    Prevent AI from committing without review. Learn more about Git hooks:

    Automatic Installation (Recommended):

    npx -y @probelabs/vow@latest install --git

    Manual Installation:

    # Add this one-liner to your existing pre-commit hook:
npx -y @probelabs/vow@latest check || exit 1

# Or for Husky v9 (recommended): https://typicode.github.io/husky/
npx husky init
echo 'npx -y @probelabs/vow@latest check' >> .husky/pre-commit

    Claude Code Integration

    Vow automatically configures Claude Code settings with intelligent scope selection. Learn more about Claude Code hooks:

    # Interactive installation with scope choice
npx -y @probelabs/vow@latest install

# Choose between:
# • Local (settings.local.json) - affects only your user account
# • Project (settings.json) - affects all users of this project

    Manual Configuration:

    // .claude/settings.local.json or .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.command' | grep -q '^git commit'; then npx -y @probelabs/vow@latest check; fi"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @probelabs/vow@latest check"
          }
        ]
      }
    ]
  }
}

    Custom Triggers

    Use in any workflow where AI accountability matters:

    # In your CI/CD pipeline
npx -y @probelabs/vow@latest check || exit 1

    📝 Custom Vows

    Vow works out of the box with built-in defaults, but you can customize the accountability rules for your specific project needs.

    View Current Rules

    See what rules are currently active (local AGENT_VOW.md or package default):

    npx -y @probelabs/vow@latest rules

    Create Custom Rules

    Step 1: Generate starting template

    # Export current rules to a file as your starting point
npx -y @probelabs/vow@latest rules > AGENT_VOW.md

    Step 2: Customize the rules Edit AGENT_VOW.md to add your project-specific requirements:

    # AGENT TASK COMPLETION CONSENT

Before finishing this task, you must honestly review your work.
**Do not lie** - if any items below are not true, fix it.

## TASK ADHERENCE
- ✓ I have followed the task exactly
- ✓ I have not cut corners or taken shortcuts

## CODE QUALITY (if code was modified)
- ✓ The code builds successfully without errors
- ✓ All tests pass and new tests are added where needed

## PROJECT-SPECIFIC RULES
- ✓ I have updated the changelog with my changes
- ✓ Documentation reflects the new functionality
- ✓ No sensitive API keys or credentials are exposed
- ✓ Code follows the project's style guide
- ✓ I have tested the changes in staging environment

---

**If you agree with all above**, create consent file:
\`\`\`bash
printf '1' | tee .AGENT_CONSENT >/dev/null
\`\`\`

    Step 3: Test your custom rules

    # Test that your custom rules work
git commit --allow-empty -m "test custom rules"

    Reset to Defaults

    Remove your custom rules to return to built-in defaults:

    rm AGENT_VOW.md
npx -y @probelabs/vow@latest check  # Now uses built-in defaults again

    🎮 Commands

    vow

    Interactive installation wizard. This is the default command for setup.

    npx -y @probelabs/vow@latest  # Interactive installation (same as vow install)

    npx -y @probelabs/vow@latest check

    Check if AI has taken the vow. This command runs in git hooks.

    npx -y @probelabs/vow@latest check  # Returns exit code 1 if vow not taken, 0 if taken

    npx -y @probelabs/vow@latest consent <code>

    Write validation code to the consent file. This command is used by AI to provide consent after reviewing the rules.

    npx -y @probelabs/vow@latest consent 123  # Writes "123" to .vow-consent file

    vow install

    Interactive installation wizard with smart detection.

    npx -y @probelabs/vow@latest install [options]

Options:
  -y, --yes        Non-interactive mode (auto-detect and install)
  --dry-run        Show what would be installed without making changes
  --force          Force installation even if already installed
  --global         Install globally for all git repositories
  --git            Install only git hooks
  --husky          Install only Husky hooks
  --claude         Install only Claude Code settings
  --all            Install in all detected locations
  --uninstall      Remove Vow from all locations
  -v, --verbose    Show detailed output

    npx -y @probelabs/vow@latest rules

    Display the current rules being used (local AGENT_VOW.md or package default).

    npx -y @probelabs/vow@latest rules  # Shows the active accountability rules

    🔍 Detection Capabilities

    Vow automatically detects:

    Git Configurations

    • ✅ Standard git repositories
    • ✅ Git worktrees (with main repo detection)
    • ✅ Custom hooks directories (core.hooksPath)
    • ✅ Global git hooks
    • ✅ Bare repositories

    Hook Managers

    • ✅ Husky v4, v8, v9 (with v9 simplified syntax)
    • ✅ pre-commit framework
    • ✅ lefthook
    • ✅ simple-git-hooks

    AI Tools

    • ✅ Claude Code with comprehensive hook support:
      • Basic gitCommitHook configuration
      • Advanced PreToolUse, Stop hooks
      • Intelligent scope selection (local vs project settings)
    • ✅ Cursor AI (.cursor/)
    • ✅ Custom AI tool configurations

    🏛️ Philosophy

    "Examine yourself without mercy."
    "Accept your duty as given."
    "Let your work speak truth."
    "Embrace failure as teacher."

    Vow brings stoic principles to AI development. It's not about controlling AI—it's about AI learning to control itself through honest self-reflection.

    🛠️ Advanced Usage

    Git Worktrees

    Vow intelligently handles git worktrees:

    # In a worktree, Vow detects:
# - Main repository location
# - Worktree-specific configuration
# - Shared hooks directory

vow install  # Will offer options for worktree-only or main repo

    Claude Code Scope Selection

    Vow offers flexible configuration for Claude Code users:

    # Interactive installation shows scope options
npx -y @probelabs/vow@latest install

# When Claude Code is detected, you'll see:
# ❯ Local (settings.local.json)    [Affects only your user account]
#   Project (settings.json)        [Affects all users of this project]

    Scope Details:

    • Local (.claude/settings.local.json) - User-specific settings that don't affect other team members
    • Project (.claude/settings.json) - Shared settings that apply to all project contributors
    • Default: Local scope is recommended for individual accountability

    Custom Hooks Directory

    If you use a custom hooks directory:

    # Set custom hooks path
git config core.hooksPath ~/.git-hooks

# Vow will detect and install there
vow install

    Dry Run Mode

    Preview changes before installation:

    npx -y @probelabs/vow@latest install --dry-run
# Shows what would be changed without modifying files

    Uninstalling

    Remove Vow from all locations:

    # Using the uninstall subcommand (recommended)
npx -y @probelabs/vow@latest uninstall

# Or using install with --uninstall flag
npx -y @probelabs/vow@latest install --uninstall

# With confirmation bypass
npx -y @probelabs/vow@latest uninstall --yes

    Rules System

    Vow uses AGENT_VOW.md for accountability rules. If no local AGENT_VOW.md exists in your project, the package's default AGENT_VOW.md is used automatically. This ensures AI accountability works immediately without setup.

    # View current rules (local or package default)
npx -y @probelabs/vow@latest rules

# Create custom AGENT_VOW.md to override defaults
npx -y @probelabs/vow@latest rules > AGENT_VOW.md
# Then customize the generated file

# Remove local rules to use package defaults again
rm AGENT_VOW.md
npx -y @probelabs/vow@latest check  # Uses package's AGENT_VOW.md

    🌐 Ecosystem

    Part of the Probe Labs ecosystem—tools dedicated to improving human and AI collaboration in engineering.

    • 🧠 Probe - Intelligent code context extraction
    • 🤝 Vow - Accountability gates for AI agents
    • 🚀 More tools coming soon...

    📄 License

    MIT © Probe Labs

    🔧 Troubleshooting

    Vow not triggering in git hooks

    1. Check if hooks are executable:

      ls -la .git/hooks/pre-commit
# Should show executable permissions (x)

    2. Verify Vow installation:

      npx -y @probelabs/vow@latest install --dry-run
# Check detection results

    3. For custom hooks directories:

      git config core.hooksPath
# Ensure Vow is installed in the correct directory

    Worktree issues

    If Vow isn't working in a worktree:

    # Check worktree configuration
git worktree list

# Reinstall for the main repository
cd $(git rev-parse --git-common-dir)/..
vow install

    Claude Code not detecting

    Vow prioritizes .claude/settings.local.json over .claude/settings.json. Ensure your settings file exists and is valid JSON:

    # Check local settings (user-specific)
cat .claude/settings.local.json | jq .

# Or check project settings (shared)
cat .claude/settings.json | jq .

# Reinstall with scope selection
vow install --claude --force

    🔌 Compatibility

    • Node.js: v14 or higher
    • Git: v2.0 or higher
    • Operating Systems: macOS, Linux, Windows (with Git Bash)
    • Hook Managers: Husky v4-v9, pre-commit, lefthook, simple-git-hooks
    • AI Tools: Claude Code, Cursor AI, GitHub Copilot

    🤝 Contributing

    We welcome contributions! Please see our Contributing Guide for details.

    Development

    # Clone the repository
git clone https://github.com/probelabs/vow.git
cd vow

# Install dependencies (none currently)
npm install

# Run tests
npm test

# Deploy website
npm run deploy:site

    🙏 Acknowledgments

    Inspired by the need for trust in human-AI collaboration and the principles of stoic philosophy.

    Website • GitHub • npm

    Built with reverence in the year of our digital lord, 2025