convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
raushankcode

Ripple — Portão de Controle de Desvio para Agentes IA

raushankcode/ripple

Valida limites de edição de código para agentes IA, detecta desvios, recomenda ações

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que funciona localmente para validar se agentes de IA ao editar código permaneceram dentro dos limites aprovados. Implementa um ciclo de planejamento → intenção → validação pós-edição, capturando desvios e fornecendo decisões claras (continuar, corrigir ou revisão humana). Totalmente local-first: sem telemetria, sem upload, sem chamadas remotas.

Instalação

$npx convez-ai raushankcode/ripple

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v1.0.4
Issues abertas
0
Contribuidores
1

Casos de uso

  • Proteger projetos reais contra edições fora de escopo de agentes IA
  • Criar barreiras de confiança explícitas entre funções e módulos
  • Implementar CI/CD guardrails que verifiquem respeito a limites aprovados

Veredito

Ripple resolve um problema real em automação de código: não apenas se o agente escreve bem, mas se permaneceu dentro do escopo aprovado. Ferramenta pragmática, local-first, com decisões estruturadas (continue/stop/human-review) que integram bem em pipelines CI/CD.

README

A tradução para o português deste README ainda está na fila.

Ripple — Local Drift-Control Gate for AI Coding Agents

Ripple is a local drift-control gate for AI coding agents that plans before edit, checks after edit, catches drift, and tells the agent what to fix.

Ripple tells AI coding agents when they may continue, when they must stop, and what they need to fix.

Plan before edit.
Save intent.
Choose a trust boundary.
Check after edit.
Catch drift.
Continue / stop / human review.

Ripple is local-first.

No account.
No telemetry.
No code upload.
No cloud indexing.
No remote model call required.

Ripple gate demo


What Ripple Does

A human approves one function edit:

Edit only source/utils/merge.ts::mergeHeaders

The agent changes the approved function. Ripple returns:

CONTINUE: agent stayed inside the approved boundary.

Now the agent also changes a second function:

source/utils/merge.ts::mergeHeaders   ← approved
source/utils/merge.ts::mergeHooks     ← not approved

Ripple returns:

STOP: agent crossed the approved function boundary.

Allowed:
  source/utils/merge.ts::mergeHeaders

Changed outside boundary:
  source/utils/merge.ts::mergeHooks

Fix:
  undo the mergeHooks change
  or create a wider human-approved intent

That is Ripple's core job:

You planned X.
The agent edited Y.
Ripple says continue, fix, or stop for human review.

Why Ripple Exists

AI coding agents can edit code fast.

The problem is not only whether the agent can write code.

The deeper question is:

Was the agent allowed to make this change?

In real projects, agents often drift from the original task:

  • They edit files they were only supposed to read.
  • They touch public utilities with wide blast radius.
  • They change nearby functions outside the approved scope.
  • They modify auth, payments, config, migrations, or other risky areas.
  • They continue working after the boundary should require human review.

Most AI coding tools ask:

Is the generated code correct?

Ripple asks:

Did the agent stay inside the work it was trusted to do?

These are different questions.

Ripple answers the second one.


Product Center: ripple gate

ripple gate gives one compact decision for humans, agents, and CI.

ripple gate --intent latest

One question. One answer.

CONTINUE

or:

STOP: agent crossed approved function boundary.

Allowed:
  src/auth.ts::refreshToken

Changed outside boundary:
  src/auth.ts::login

Fix:
  undo src/auth.ts::login
  or create a wider human-approved intent

Machine-readable output for agents and CI:

{
  "status": "closed",
  "decision": "human-review",
  "canContinue": false,
  "mustStop": true,
  "needsHuman": true,
  "why": ["Changed symbol outside approved boundary: src/auth.ts::login"],
  "fixNow": ["Undo src/auth.ts::login or replan with human approval."],
  "risk": {
    "level": "critical",
    "score": 100,
    "summary": "CRITICAL risk 100/100: Agent changed symbols outside the approved Ripple boundary.",
    "reasons": [
      {
        "kind": "boundary-crossed",
        "severity": "high",
        "message": "Agent changed symbols outside the approved Ripple boundary.",
        "evidence": [
          "allowed symbol: src/auth.ts::refreshToken",
          "changed outside boundary: src/auth.ts::login"
        ]
      }
    ],
    "requiredActions": [
      "Undo the outside-boundary change or create a wider human-approved intent.",
      "Review downstream callers/importers before continuing."
    ]
  }
}

Risk Explanation Layer

Ripple does not only say that an agent crossed a boundary.

It explains why the crossing matters.

Example:

Human approved:
  src/auth.ts::refreshToken

Agent changed outside boundary:
  src/auth.ts::login

Ripple can return:

Decision: human-review
Risk: CRITICAL 100/100

Why this is risky:
  - boundary-crossed: agent changed a symbol outside the approved function boundary
  - policy-rule: the saved intent is marked high/critical risk by policy
  - blast-radius: changed file has downstream importers
  - public-contract: exported/public symbols may affect callers

Evidence:
  - allowed symbol: src/auth.ts::refreshToken
  - changed outside boundary: src/auth.ts::login
  - direct importers may be affected

Required:
  - undo the outside-boundary change
  - or create a wider human-approved intent
  - review downstream callers/importers
  - run verification targets

The goal is to make the invisible consequence visible:

What was approved?
What changed outside approval?
Why is that risky?
What evidence proves it?
What must happen before continuing?

This risk layer is available through the CLI gate, MCP gate, JSON output, and CI summary.


Install

Run without installing globally:

npx -y @getripple/cli init

Install globally:

npm install -g @getripple/cli

VS Code extension:

code --install-extension rippleai.ripple

60-Second Start

Initialize Ripple inside a repository:

ripple init

Plan before editing:

ripple plan --file src/auth.ts --task "change token refresh behavior" --mode file --agent --save

After editing, stage and check:

git add src/auth.ts
ripple check --staged --agent --intent latest

Get the compact decision:

ripple gate --intent latest

Ripple returns CONTINUE or STOP with the reason and exact next action.


Core Workflow

1. Initialize

ripple init

Creates repo defaults and the CI gate:

.ripple/policy.json
.github/workflows/ripple.yml

For agents that do not use MCP, generate file-based context:

ripple workflow

This writes:

.ripple/WORKFLOW.md

Normal CLI runs stay lean. They use history and graph cache without generating broad context bundles.


2. Plan Before Editing

ripple plan --file src/auth.ts --task "change token refresh behavior" --mode file --agent --save

Returns a focused plan:

readFirst:              src/auth.ts, src/session.ts
readIfNeeded:           tests/auth.test.ts
avoidInitially:         docs/, unrelated UI files
risk:                   caution
editableFiles:          src/auth.ts
contextFiles:           src/session.ts
controlMode:            file
humanGate:              required-before-edit  (if policy requires it)
verificationTargets:    tests/auth.test.ts

If a human gate is required:

ripple approve --intent latest --gate before-risky-edit

3. Edit Inside the Boundary

The agent should:

read only the required context
edit only approved files or symbols
avoid unrelated files
respect the saved intent
stop if the task scope changes

The saved intent becomes the trust boundary for the work.


4. Check After Staging

git add src/auth.ts
ripple check --staged --agent --intent latest

The handoff field is what the agent should read first:

handoff.canContinue=true  → continue after listed verify commands
handoff.mustStop=true     → stop, follow fixNow, and askHuman
handoff.needsHuman=true   → do not self-approve, ask the human

5. Repair If Needed

ripple repair --agent --intent latest

Returns exact repair actions:

unstage-file:     src/session.ts was context-only
review-symbol:    src/auth.ts::refreshToken changed outside the plan
review-contract:  public contract may have changed
verify:           run tests/auth.test.ts
replan:           create a new Ripple plan if the task scope changed

Trust Boundary Contract

The Trust Boundary Contract is Ripple's core safety model.

It compares:

planned work

against:

actual changes

to determine whether an AI coding agent stayed inside the work it was trusted to perform.

The Trust Boundary Contract includes:

planned work       -> what the human approved
approved boundary  -> file, function, task, brainstorm, or PR scope
actual changes     -> what the agent modified
drift result       -> whether the agent left the approved work
gate decision      -> continue, repair, human-review, or restore-readiness

This contract is consumed by:

humans       -> CLI and VS Code
AI agents    -> MCP tools
CI systems   -> ripple ci and ripple gate

The Trust Boundary Contract enables Ripple to:

detect intent drift
detect boundary drift
require repair
require human review
produce continue / stop decisions
protect approved workflows

Trust Boundaries

Ripple saves the freedom level the agent was given before editing and checks whether the agent stayed inside it after editing.

Example function-level boundary:

ripple plan --file src/auth.ts --symbol refreshToken --task "fix retry behavior" --mode function --agent --save

Supported modes:

ModeWhat the agent is allowed to touch
brainstormNo edits. Suggest and explain only.
functionOnly the approved symbol.
fileOnly the selected file.
taskAll files in the saved plan.
prFull task scope. Human reviews before merge.

After staging, Ripple checks two things independently:

intent drift    -> did the edit leave the task plan?
boundary drift  -> did the edit cross the chosen freedom level?

If function mode allowed only refreshToken but the agent also changed login, Ripple reports:

boundary_verdict: DANGER

Then ripple repair tells the agent exactly what to undo or when to ask the human for a wider approved intent.


Drift Verdict Contract

Every check returns one clear verdict:

PASS   -> continue
DRIFT  -> fix before commit
DANGER -> stop and ask human

The same contract appears in CLI output, CI annotations, and MCP tool results.

Example:

{
  "driftVerdict": {
    "status": "drift",
    "decision": "fix-before-commit",
    "label": "DRIFT",
    "summary": "DRIFT: staged changes left the saved Ripple plan.",
    "why": ["Context-only file changed: src/session.ts"],
    "fix": ["Unstage context-only file: src/session.ts"]
  }
}

Interfaces

One engine. Multiple interfaces.

@getripple/core    -> local architectural context engine
@getripple/cli     -> terminal and CI interface
@getripple/mcp     -> MCP interface for AI agents
rippleai.ripple    -> VS Code human interface

CLI — @getripple/cli

Install:

npm install -g @getripple/cli

Common commands:

ripple init
ripple doctor
ripple agent
ripple workflow
ripple scan .
ripple focus src/auth.ts
ripple blast src/auth.ts
ripple imports src/auth.ts
ripple importers src/auth.ts
ripple symbols src/auth.ts
ripple callers src/auth.ts::validateToken
ripple history --last 10
ripple plan --file src/auth.ts --task "..." --agent --save
ripple check --staged --agent --intent latest
ripple check --changed --base origin/main --strict
ripple audit --agent --intent latest
ripple approval --intent latest --agent
ripple approve --intent latest --gate before-risky-edit
ripple repair --agent --intent latest
ripple gate --intent latest
ripple ci --base origin/main --intent latest --github-annotations
ripple init-ci
ripple policy init
ripple policy explain --file src/auth.ts

In CI, --github-annotations emits GitHub errors for drift findings.

The gate exits non-zero when drift blocks merge.


MCP — @getripple/mcp

Install through any MCP-compatible client.

Replace the workspace path with your project path.

macOS / Linux example:

/Users/yourname/projects/myapp

Windows example:

C:\\Users\\yourname\\projects\\myapp

MCP config:

{
  "mcpServers": {
    "ripple": {
      "command": "npx",
      "args": [
        "-y",
        "@getripple/mcp",
        "--workspace",
        "/absolute/path/to/your/repo"
      ]
    }
  }
}

Available MCP tools:

ripple_get_agent_workflow      full agent workflow guide and loop
ripple_doctor                  check project readiness
ripple_plan_context            plan before editing a target file
ripple_check_staged            check staged changes against saved intent
ripple_check_changed           check changed files against a git base ref
ripple_audit_change            audit a completed change for drift signals
ripple_gate                    compact continue/stop decision
ripple_get_approval_status     check whether a human gate is required
ripple_repair_intent_drift     get repair actions when drift is detected
ripple_get_focus               focused context for a single file
ripple_get_blast_radius        files that depend on a target file
ripple_explain_policy          explain the active trust boundary policy
ripple_get_recent_changes      recent architectural changes from history

Recommended agent loop:

Use ripple_plan_context before editing.
Use ripple_gate after editing.
Use ripple_repair_intent_drift when drift is detected.
Ask the human when needsHuman=true.

VS Code Extension

Install:

code --install-extension rippleai.ripple

Open any JavaScript or TypeScript project and wait for:

Ripple: ready

Provides:

  • Impact Lens sidebar
  • File dependency context
  • Reverse importer context
  • CodeLens caller counts above exported functions
  • Safety Check before commits
  • Blast radius warnings
  • Copy Agent Prompt for file context
  • Setup panel for AGENTS.md, CLAUDE.md, or .cursorrules

Core — @getripple/core

The pure Node.js engine used by CLI and MCP.

Most users should not start here.

Use @getripple/core when building custom integrations.

import { GraphEngine } from "@getripple/core";

const engine = new GraphEngine(process.cwd());

try {
  await engine.initialScan();

  const importers = engine.downstreamFiles("src/auth.ts");
  const blastRadius = engine.blastRadius(["src/auth.ts"]);

  console.log({ importers, blastRadius });
} finally {
  engine.dispose();
}

Trust Policy

Define repo-level trust defaults in:

.ripple/policy.json

Example:

{
  "defaultMode": "file",
  "riskRules": [
    {
      "paths": ["src/auth/**", "src/security/**"],
      "risk": "high",
      "requireHumanBeforeEdit": true,
      "requireHumanBeforeMerge": true
    },
    {
      "paths": ["src/payments/**", "migrations/**"],
      "risk": "critical",
      "requireHumanBeforeEdit": true,
      "requireHumanBeforeDeploy": true
    },
    {
      "paths": ["docs/**"],
      "risk": "low",
      "allowPrMode": true
    }
  ]
}

ripple plan reads the policy, applies the matching rule, and includes policyExplanation in agent output.

If the policy changes after an intent is saved, Ripple reports policyDrift and requires human review before continuing.


Generated Files

Ripple keeps durable audit state in .ripple/ and machine cache in .ripple/.cache/.

.ripple/
  history.json                   structural changes since install
  policy.json                    repo trust defaults
  intents/
    latest.json                  most recently saved change intent
  approvals/
    <intent-id>/
      before-risky-edit.json     recorded human approval
  .cache/                        gitignore this entire folder
    graph.cache.json             fast startup cache

Running ripple workflow adds the broader context bundle:

.ripple/
  WORKFLOW.md
  .cache/
    context.json
    context.files.json
    context.symbols.json
    focus/
      <file>.json

Recommended .gitignore:

.ripple/.cache/

MCP-capable agents should use ripple_plan_context and ripple_gate directly rather than reading generated files.


What Ripple Tracks

File dependency graph     every import and reverse import
Symbol and call edges     exported functions and who calls them
Blast radius              files affected by a change
Risk signals              dangerous / caution / safe per file
Focused context           per-file summaries for AI agents
Change history            structural changes since first install
Layer classification      logic / ui / handler / state / data / effect
Framework signals         Next.js, Vite, Turborepo, MobX, Prisma, Tailwind
Saved change intents      what the agent was allowed to do
Approval records          human gate decisions tied to intent fingerprints
Risk explanations         boundary, graph, policy, contract, and verification evidence
Required actions          what the agent or human must do before continuing

Language Support

LanguageStatusTracks
TypeScript / JavaScriptDeepImports, exports, symbols, call edges, blast radius, risk, focused context, staged drift
PythonBasicStatic imports, from-imports, functions, classes, methods, basic call signals, file-level staged checks

The strongest current experience is JavaScript and TypeScript.

Python support is basic and improving carefully.

What works for Python today

Ripple's Python support is intentionally basic, but useful for local agent control:

Supported today:
- discover Python files in the repo
- parse static imports and from-imports
- detect functions, classes, and methods
- build basic file-level dependency signals
- perform file-level staged checks
- apply saved file/task boundaries
- surface risk explanations for changed Python files using policy, boundary, graph, and verification signals

Python support is strongest for clear, static Python code.

Use carefully with:
- dynamic imports
- runtime monkey-patching
- decorators that create hidden call paths
- framework routing that is not visible through static imports
- generated files

For Python repos, Ripple should be treated as a local boundary/risk signal, not a perfect semantic analyzer.


Release Identity

Ripple's official release identity is:

Ripple is a local drift-control gate for AI coding agents that plans before edit, checks after edit, catches drift, and tells the agent what to fix.

This identity should stay consistent across the root README, package READMEs, CLI docs, MCP docs, and release metadata.

Run the release identity check before publishing:

npm run release:identity

Release Proof

Ripple release checks are documented in RELEASE.md.

Before publishing Ripple packages, run the agent-control proof:

npm run proof:agent-control

Run the package publish-readiness proof:

npm run proof:publish-readiness

Run the MCP package install proof:

npm run proof:mcp-package-install

Verify release identity before publishing:

npm run release:identity

Run the full release check:

npm run release:check

Run live npm registry preflight checks before a real publish:

npm run release:npm-preflight -- --live

Run the release-check proof:

npm run proof:release-check

After publishing, run the live post-publish smoke test:

npm run smoke:post-publish -- --live

The full release chain verifies:

@getripple/cli
@getripple/mcp
agent-control proof
publish-readiness proof
MCP package install proof
release identity proof
npm live preflight
release check proof
post-publish smoke test

These checks make sure the package identity, documentation, CLI, MCP server, gates, proofs, registry readiness, and release metadata are ready before publishing.

Validation

Ripple has been tested on a local clone of sindresorhus/ky, a real-world TypeScript HTTP library.

For a targeted edit around:

source/utils/merge.ts::mergeHeaders

Ripple surfaced a file-level blast radius larger than a direct text search found and marked the edit as dangerous based on importer count.

Full validation:

docs/validation.md

This validation does not imply endorsement by the ky project or its maintainers.


Known Limitations

Ripple uses static analysis.

It can miss or approximate:

  • Dynamic imports
  • Runtime dependency injection
  • Decorator-driven framework behavior
  • Complex aliasing
  • Reflection
  • Generated code
  • Framework routing conventions
  • Runtime-only call paths
Ripple gives the agent a better map.
It does not guarantee the terrain is complete.

Output language is intentionally careful:

may affect
likely used by
possible blast radius

These are signals, not proofs.


What Ripple Is Not

Ripple is not:

another coding agent
a code generator
a code review replacement
a test replacement
a typechecker replacement
a cloud scanner
a sandbox
a full semantic compiler
a magic AI safety system

Ripple is a local gate that checks whether an AI coding agent stayed inside the work it was trusted to do.


Privacy

Ripple runs locally.

No account required.
No telemetry.
No cloud indexing.
No code upload.
No remote model call required.

Your repository is scanned on your machine.

Nothing leaves the local file system by default.


Current Status

Public alpha.

What exists today:

  • Core engine: @getripple/core
  • CLI and CI interface: @getripple/cli
  • MCP interface: @getripple/mcp
  • VS Code extension: rippleai.ripple
  • Plan / check / repair workflow with trust boundaries
  • Intent drift detection
  • Boundary drift detection
  • Human approval gates
  • Compact continue / stop gate
  • Risk explanation layer with score, reasons, evidence, and required actions
  • Structural evidence in stop reports
  • Blast-radius proof in gate output
  • MCP risk contract for agents
  • GitHub Actions CI gate with risk summary
  • JavaScript and TypeScript deep support
  • Python basic support

What is still early:

  • Python depth beyond basic imports and symbols
  • Framework-specific intelligence beyond signal detection
  • Perfect semantic accuracy on complex aliasing
  • Product-flow risk intelligence across arbitrary frameworks
  • Code-owner / reviewer routing
  • Team policy tooling at scale
  • Large monorepo tuning

Roadmap

Near-term:

  • Add more risk fixtures for risky paths such as auth, payments, config, infra, and migrations
  • Improve ripple_plan_context context ranking quality
  • Strengthen repair action specificity
  • Add more regression fixtures
  • Deepen Python adapter carefully

Later:

  • Framework-specific adapters
  • Better test-target mapping
  • Product-flow impact mapping
  • Code-owner and reviewer routing
  • More language adapters
  • Richer architectural memory over time
  • Stronger team policy workflows

Contributing

Repository:

https://github.com/raushankcode/ripple

Issues and pull requests are welcome.

If Ripple misses an import, caller, framework pattern, or staged-change risk, open an issue with a small reproduction.

The most useful reports include:

minimal repo
exact command
expected result
actual result
small explanation of the project structure

License

MIT

Ver o original no GitHub

Bom para

Relacionados