⬡ Gate Keeper

Graph-aware quality gates for AI-assisted development.

---

What it is

Gate Keeper sits between you and your AI coding agent — Claude Code, GitHub Copilot, or any MCP-compatible editor. Every file the agent writes is analyzed (TypeScript Compiler API for TS/JS/JSX, Roslyn for C#), rated 0–10, and published to a live dependency graph. The agent sees the graph through a 5-tool MCP server; you see it at a live dashboard.

Quality feedback loop: Claude Code hooks tell the agent to use the MCP tools at the right moments — get_dependency_graph at session start, get_file_context before edits, get_codebase_health after bulk changes. The agent self-corrects based on the data these tools return.

---

Install

npm install -g @mohantn/gate-keeper

Installs two CLI commands: gate-keeper and gk.

---

Quick Start

gate-keeper setup           # Configure for both Claude Code and Copilot
gate-keeper setup claude    # Claude Code only (writes ~/.claude/settings.json)
gate-keeper setup copilot   # Copilot / VS Code only (prints .vscode/ setup)

This starts the daemon and configures the tools you're using. Open http://localhost:5378/viz for the live dashboard.

Command	Description
gate-keeper daemon	Start the daemon (ports 5378 / 5379)
gate-keeper mcp	Start the MCP server (stdio)
gate-keeper register	Register current directory as a repo with the daemon
gate-keeper guide session-start	Register repo + print MCP tool guidance
gate-keeper guide pre-edit	Print pre-edit guidance (get_file_context)
gate-keeper guide post-edit	Print post-edit guidance (get_file_context + get_codebase_health)
gate-keeper dashboard	Open the dashboard in browser
gate-keeper status	Check daemon health
gk <command>	Short alias for any command

The npm package ships pre-built. gate-keeper setup detects whether you're running from a git clone (builds from source) or a global install (skips build, starts directly).

---

Claude Code Integration

gate-keeper setup writes three hooks to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "gate-keeper guide session-start"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "gate-keeper guide pre-edit"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "gate-keeper guide post-edit"
          }
        ]
      }
    ]
  }
}

SessionStart — fires once when a new Claude Code session begins. Registers the repo with the daemon, fetches the dependency graph from the daemon's API, and outputs a compact summary: file count, module directories, most-depended-on files, and average quality rating. Claude sees this architecture context immediately without needing to call a separate MCP tool.

PreToolUse — fires before every Write/Edit. Prints a reminder to call get_file_context with the file path to check its quality rating and dependencies before making changes.

PostToolUse — fires after every Write/Edit. Prints a reminder to call get_file_context again to see the latest quality rating, and to call get_codebase_health if 3+ files were changed.

The hooks don't block or analyze anything — they output lightweight guidance text that Claude sees and acts on. The actual quality analysis happens when the agent calls the MCP tools.

No .github/instructions/ file needed — the hooks themselves guide the agent at the right moments.

---

GitHub Copilot / VS Code Integration

1. Repository registration task (auto-runs on folder open)

Add .vscode/tasks.json in the repo:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "gate-keeper: register repo",
      "type": "shell",
      "command": "gate-keeper",
      "args": [
        "register"
      ],
      "runOptions": {
        "runOn": "folderOpen"
      },
      "presentation": {
        "reveal": "never",
        "echo": false,
        "close": true
      },
      "problemMatcher": []
    }
  ]
}

This fires automatically when VS Code opens the workspace. It calls gate-keeper register, which tells the daemon to watch this repo. The task runs silently — no terminal popup. Works whether gate-keeper is globally installed or locally cloned.

2. Agent instructions (auto-loaded)

Create .github/instructions/gate-keeper.instructions.md in the repo with applyTo: "**/*.{ts,tsx,jsx,js,cs}". Copilot auto-loads it on every matching edit. The instructions tell the agent to:

• Call get_quality_rules at session start
• Call get_file_context before editing any file
• Call get_codebase_health after bulk changes
• Follow the quality thresholds

3. MCP server for VS Code

To let VS Code discover the MCP server, add .vscode/mcp.json:

{
  "servers": {
    "gate-keeper": {
      "command": "gate-keeper",
      "args": ["mcp"]
    }
  }
}

Works with both global install and local clone — gate-keeper is always on PATH.

---

Troubleshooting

Symptom	Cause	Fix
Daemon won't start	Missing runtime dependency (eslint) or port conflict	Run npm install -g @mohantn/gate-keeper again, or kill the process on ports 5378/5379.
Hooks not firing	~/.claude/settings.json missing or wrong path	Run gate-keeper setup again.
gate-keeper register fails	Daemon isn't running	Start it first: gate-keeper daemon
Copilot doesn't see MCP tools	.vscode/mcp.json missing or incorrect	Use "command": "gate-keeper" and "args": ["mcp"] (not a file path)
Agent isn't calling MCP tools	Hooks output not being followed	The hooks print guidance — Claude should act on it. If not, check ~/.claude/settings.json is correct.

---

License

MIT — see LICENSE.