SP-DevControl

Local governance layer for AI-assisted development.

SP-DevControl puts a human in charge of every AI coding session — from architecture design to production publish. It works inside every major AI editor (Claude Code, Cursor, Windsurf, Copilot, opencode, Codex) through a universal MCP integration and auto-generated editor config files.

Why DevControl

AI coding agents ship code at machine speed. Without guardrails, one bad prompt can reset a branch, expose secrets, or push untested code to production.

DevControl gives you:

Human authorization gates — design, development, review, and publish phases each require explicit human sign-off before agents can proceed
Policy enforcement — protect critical paths and block dangerous commands (git reset --hard, rm -rf, DROP TABLE blocked by default)
Change approval workflow — every change detected by a watched session needs your approval or rejection before it goes into git
Rollback — undo any change or entire session back to the captured before-state
Compliance engine — 36 controls mapped to OWASP, RGPD, ISO 27001, CWE, SLSA
Universal MCP — works with every major AI editor out of the box via MCP server

No other tool enforces governance across the full agentic development lifecycle. DevControl fills that gap.

Install

npm install -g sp-devcontrol

Standalone binary (no Node.js required)

# Linux x64
curl -L https://github.com/PRojas01/sp-devcontrol/releases/latest/download/devcontrol-linux-x64 -o devcontrol
chmod +x devcontrol && sudo mv devcontrol /usr/local/bin/

# Linux ARM64
curl -L https://github.com/PRojas01/sp-devcontrol/releases/latest/download/devcontrol-linux-arm64 -o devcontrol
chmod +x devcontrol && sudo mv devcontrol /usr/local/bin/

# Windows x64 — download devcontrol-win-x64.exe from the Releases page

Quickstart

# 1. Initialize governance in your project
cd my-project
sp-devcontrol init --project-name my-project

# 2. Inject config into your editor (CLAUDE.md, .cursorrules, opencode.json...)
sp-devcontrol inject

# 3. Approve the design gate before any agent starts coding
sp-devcontrol gate:approve --phase design --by "Your Name" --notes "architecture reviewed"

# 4. Start a governed session
sp-devcontrol session:start --objective "implement login feature"

# 5. Monitor all file changes in real time (separate terminal)
sp-devcontrol watch:start --session ds-YYYYMMDD-001

# 6. Approve or reject each change the agent makes
sp-devcontrol session:change:approve --change-id <id>
sp-devcontrol session:change:reject  --change-id <id>

# 7. Approve the review gate before any git push
sp-devcontrol gate:approve --phase review --by "Your Name"

# 8. Generate a compliance report
sp-devcontrol report:compliance

# 9. Close the session
sp-devcontrol session:close --session ds-YYYYMMDD-001

Human Authorization Gates

Gates are the core of DevControl's human-in-the-loop model. Every project has four gates that must be explicitly approved by a human before proceeding to the next phase.

design ──► development ──► review ──► publish
  🟡              🟡           🟡         🟡
 (pending)     (pending)   (pending)  (pending)

Gate phases

Phase	Meaning	Effect when not approved
`design`	Architecture and requirements reviewed	Agent sees warning in CLAUDE.md
`development`	Development actively authorized	Sessions can start with warning
`review`	Code reviewed, ready for push	`git push` blocked by pre-push hook
`publish`	Ready for production release	`npm publish`, `vsce publish` flagged as REVIEW

Gate commands

# Show current gate states
sp-devcontrol gate:status

# Approve a phase
sp-devcontrol gate:approve --phase design --by "Pedro" --notes "architecture reviewed"
sp-devcontrol gate:approve --phase development --by "Pedro"
sp-devcontrol gate:approve --phase review --by "Pedro" --notes "code review passed"
sp-devcontrol gate:approve --phase publish --by "Pedro" --notes "all tests green"

# Block a phase (halt progress)
sp-devcontrol gate:reject --phase publish --reason "failing tests on CI"

# Request approval (shows the exact command the reviewer needs to run)
sp-devcontrol gate:request --phase review

# Reset a gate to pending
sp-devcontrol gate:reset --phase review

Gate status visible in your editor

After running sp-devcontrol inject, your CLAUDE.md shows the live gate table at the top:

## ⚙ Human Authorization Gates

| Phase       | Status      | Approved By | Notes                 |
|-------------|-------------|-------------|-----------------------|
| design      | ✅ OPEN     | Pedro       | architecture reviewed |
| development | ✅ OPEN     | Pedro       |                       |
| review      | 🟡 PENDING  | —           | —                     |
| publish     | ⛔ BLOCKED  | —           | failing CI            |

> AGENT RULE: Stop and request human approval before crossing a gate boundary.
> Check gates:       sp-devcontrol gate:status
> Request approval:  sp-devcontrol gate:request --phase <phase>

Every AI editor that reads CLAUDE.md or .cursorrules sees this. Re-run inject after each gate change to refresh.

Editor Integration

Run sp-devcontrol inject once to generate all editor config files for your project:

File generated	Read by
`CLAUDE.md`	Claude Code
`.cursorrules`	Cursor
`.windsurfrules`	Windsurf
`.devcontrol/injected/copilot-instructions.md`	GitHub Copilot
`opencode.json`	opencode
`.cursor/mcp.json`	Cursor (MCP)
`.windsurf/mcp.json`	Windsurf (MCP)

Claude Code

# MCP server via stdio (no daemon needed)
claude mcp add devcontrol -- sp-devcontrol mcp:stdio

Or add to .claude/mcp.json:

{
  "mcpServers": {
    "devcontrol": { "type": "sse", "url": "http://localhost:7893/mcp" }
  }
}

opencode

sp-devcontrol inject generates opencode.json with the MCP server entry. To configure your AI provider, add an inference section to .devcontrol/config.json:

{
  "inference": {
    "providerName": "my-ollama",
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "ollama",
    "model": "my-ollama/qwen2.5-coder:7b"
  }
}

Cursor / Windsurf

sp-devcontrol inject writes .cursorrules, .windsurfrules, and the MCP config files. Open your project and the rules apply automatically.

Policy Engine

Command policy — three tiers

# BLOCK — command is always rejected
# (git reset --hard, rm -rf /, DROP TABLE are blocked by default)

# REVIEW — agent must request human approval before running
sp-devcontrol policy:command:review:add    --command "git push"
sp-devcontrol policy:command:review:list
sp-devcontrol policy:command:review:remove --command "git push"

# ALLOW — command is explicitly approved
sp-devcontrol policy:command:approve --command "npm run deploy:staging"
sp-devcontrol policy:command:revoke  --command "npm run deploy:staging"

# Evaluate any command
sp-devcontrol policy:command --command "git push origin main"
# → REVIEW: Command matches review pattern: git push

Protected paths

sp-devcontrol policy:protected:add    --pattern "src/auth/**"
sp-devcontrol policy:protected:list
sp-devcontrol policy:protected:remove --pattern "src/auth/**"

sp-devcontrol policy:path --path "src/auth/login.ts"
# → HIGH risk, protected, approval required

Default blocked commands

git reset --hard · git push --force · git push -f · rm -rf / · rm -rf ~ · chmod 777 · sudo rm -rf · DROP TABLE · TRUNCATE · eval $(curl · curl | bash

Default review commands

git push · npm publish · npx publish · pnpm publish · vsce publish · docker push · kubectl apply · kubectl delete · terraform apply · terraform destroy

Session Workflow

# Start session
sp-devcontrol session:start \
  --objective "Add payment integration" \
  --agent claude-code \
  --mode watch

# Watch file changes (separate terminal)
sp-devcontrol watch:start --session ds-20260626-001

# List detected changes
sp-devcontrol session:changes:list --session ds-20260626-001

# Approve a change (interactive TUI)
sp-devcontrol session:change:approve --change-id <id>

# Approve without TUI — for CI or non-interactive environments
sp-devcontrol session:change:approve --change-id <id> --yes --message "approved in CI"

# Reject and rollback a change
sp-devcontrol session:change:reject --change-id <id>

# Close session
sp-devcontrol session:close --session ds-20260626-001

Snapshots and Rollback

DevControl captures the before-state of every file before a change is applied.

# Create a manual snapshot
sp-devcontrol snapshot:create --session <id> --label "before-refactor"

# List snapshots
sp-devcontrol session:snapshots:list --session <id>

# Rollback one change to its before-state
sp-devcontrol session:rollback --session <id> --change-id <change-id>

# Rollback entire session (restores earliest before-state per file)
sp-devcontrol session:rollback --session <id>

Rollback safety guarantees:

New files (snapshotBefore = '') are deleted on rollback
Path traversal outside project root is blocked and throws
Partial rollbacks skip missing files and continue

Compliance Reports

36 controls mapped to OWASP A01–A10, RGPD Art. 25/32, ISO 27001, CWE, and SLSA.

sp-devcontrol report:compliance
sp-devcontrol report:session --session <id>

Control categories: security · privacy · architecture · commits · testing · documentation · memory

Git Hooks

# Install hooks (pre-commit, pre-push, commit-msg)
sp-devcontrol hooks:install

# The pre-push hook:
#   - blocks push if there are open unresolved sessions
#   - warns if the review gate is not approved
#   - shows a DevControl status banner

sp-devcontrol hooks:status
sp-devcontrol hooks:uninstall

MCP Server

DevControl exposes a Model Context Protocol server compatible with all MCP clients.

# stdio mode (Claude Code)
sp-devcontrol mcp:stdio

# HTTP/SSE mode (Cursor, Windsurf, opencode, port 7893)
sp-devcontrol mcp:serve --port 7893

MCP tools exposed: get_policy · evaluate_command · evaluate_path · get_session · list_changes · get_compliance

Daemon Mode

# Start background daemon (REST API on :7891 + MCP on :7893)
sp-devcontrol daemon

# Health check
curl http://localhost:7891/health

# API (Bearer token required)
curl -H "Authorization: Bearer $(cat .devcontrol/api-token)" \
     http://localhost:7891/api/policy

Configuration

{
  "project": "my-project",
  "version": "1.0.0",
  "stack": ["typescript", "node"],
  "agents": {
    "allowed": ["claude-code", "opencode", "cursor", "windsurf"],
    "default": "claude-code"
  },
  "scope": {
    "allowed": ["src/", "tests/", "docs/"],
    "protected": ["src/auth/", ".env", ".devcontrol/"]
  },
  "controls": {
    "security": ["sec-secrets", "sec-sqli", "sec-cmd", "sec-xss", "sec-deps"],
    "privacy": ["priv-pii", "priv-logging"],
    "commits": ["vcs-conv-commits"]
  },
  "inference": {
    "providerName": "my-ollama",
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "ollama",
    "model": "my-ollama/qwen2.5-coder:7b"
  }
}

Project Health Check

sp-devcontrol project:check
# Checks: git present · docs written · policy configured
#         baseline snapshot · agent config injected · gate states

sp-devcontrol project:status
# Shows: project name, phase, session count, last session, gate table

Storage

# JSON files (default — zero dependencies, portable, human-readable)
sp-devcontrol storage:backend json

# SQLite (better for large projects with many sessions)
sp-devcontrol storage:backend sqlite

Full Command Reference

init --project-name              Initialize DevControl in a project

gate:status                      Show authorization gate states
gate:approve --phase --by        Approve a phase gate
gate:reject  --phase --reason    Block a phase gate
gate:reset   --phase             Reset gate to pending
gate:request --phase             Show approval instructions

policy:path --path               Evaluate path risk level
policy:command --command         Evaluate command risk (ALLOW/REVIEW/BLOCK)
policy:protected:list/add/remove Manage protected path patterns
policy:command:approved:list     List approved commands
policy:command:approve/revoke    Manage approved commands
policy:command:review:list/add/remove  Manage review commands

session:start --objective        Start a governed session
session:check                    Token usage / context refresh
session:changes:list             List detected changes
session:change:show              Show one change detail
session:change:approve [--yes]   Approve change (TUI or --yes for CI)
session:change:reject            Reject and rollback a change
session:close                    Close session
session:rollback [--change-id]   Rollback change or full session
session:snapshots:list           List session snapshots
session:approval:list/grant/revoke  Manage session-scoped approvals

snapshot:create --label          Create manual snapshot

hooks:install/uninstall/status   Manage git hooks

inject                           Generate CLAUDE.md, .cursorrules, opencode.json...
skill:generate [--editor]        Generate skill/tool files

report:compliance                Full compliance report
report:session --session         Per-session detailed report

daemon                           Start background REST+MCP daemon
mcp:serve [--port]               Start MCP HTTP/SSE server
mcp:stdio                        Start MCP stdio server (Claude Code)

storage:backend json|sqlite      Set storage backend
agent:run --agent --objective    Run agent in governed sandbox
project:status                   Show local governance status
project:check                    Run preflight checks

Testing

npm test              # 93 tests, 16 files
npm run typecheck     # TypeScript strict, 0 errors
npm run build         # Compile TypeScript → dist/
npm run test:watch    # Watch mode

Security

See SECURITY.md for the vulnerability disclosure process.

Security invariants (do not revert):

commandMatches() — exact token prefix matching, not .includes() (prevents bypass)
resolve()+startsWith(root+'/') — path traversal blocked in both policy and snapshot
Bearer token required on all API and MCP endpoints except /health
Per-project DB isolation in the MCP server via mcpDbCache Map
Atomic daemon lock via openSync(LOCK_PATH, 'wx') — prevents duplicate daemons

Contributing

See CONTRIBUTING.md for development setup, testing guidelines, and pull request process.

License

SP-DevControl v2.1.0 — Built for teams that want humans in the loop.

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.cursor		.cursor
.devcontrol		.devcontrol
.github		.github
.windsurf		.windsurf
docs		docs
scripts		scripts
src		src
tests		tests
.cursorrules		.cursorrules
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmignore		.npmignore
.windsurfrules		.windsurfrules
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
opencode.json		opencode.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

SP-DevControl

Why DevControl

Install

Standalone binary (no Node.js required)

Quickstart

Human Authorization Gates

Gate phases

Gate commands

Gate status visible in your editor

Editor Integration

Claude Code

opencode

Cursor / Windsurf

Policy Engine

Command policy — three tiers

Protected paths

Default blocked commands

Default review commands

Session Workflow

Snapshots and Rollback

Compliance Reports

Git Hooks

MCP Server

Daemon Mode

Configuration

Project Health Check

Storage

Full Command Reference

Testing

Security

Contributing

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages