veto

93 agentic tools. 49 specialists. Every major AI CLI. Self-learning. Zero extra cost on subscriptions.

An MCP server that runs locally on your machine, plugs into Claude Code, Codex CLI, Gemini CLI, Antigravity CLI, Cursor, Windsurf, Zed, and JetBrains using your existing subscriptions — giving every AI a council of specialist agents, local LLM support, SDD agents, playwright automation, persistent cross-platform memory, a self-learning router that re-tunes its tier thresholds automatically every 20 recorded task outcomes (reviews record outcomes for you; configurable via auto_apply_learning), CI/CD gates, workspace discovery, and bidirectional IDE communication.

Billing note: "Zero cost" applies to subscription plans (Claude Max, Gemini Advanced, etc.). If you are on API/pay-per-token billing, LLM reasoning done for Veto agents (via the agentic loop or MCP Sampling) counts toward your token usage like any other turn. veto init detects API key environment variables and warns you automatically.

---

Getting Started

# 1. Install the CLI — puts the bare `veto` command on your PATH
npm i -g @jigyasudham/veto

# 2. Register Veto with every AI client you use (Claude Code, Gemini, Codex, Cursor, …)
veto init

Prefer not to install anything? Every command also works via npx:

npx -y @jigyasudham/veto@latest init

The two are independent by design. veto init writes MCP configs that launch the server with npx -y --package @jigyasudham/veto@latest veto-server — npx re-resolves @latest against the registry on every client restart, so the MCP server auto-updates itself and a global copy can never pin it to an old version. The global install only provides the CLI (veto doctor, veto sessions, the statusline, …); keep it current with npm i -g @jigyasudham/veto@latest when veto doctor says it's behind.

---

How the Agents Work

No API keys, zero extra cost. Every worker agent is a deterministic expert module at its core, with two optional layers of LLM reasoning on top — all of it delegated to the AI you're already paying for.

Default — Deterministic expert modules

Out of the box, each of the 42 worker agents runs as a hand-written expert module (plan() / analyze() in src/agents/) — not an LLM. They always run, work offline, and cost zero tokens. Their depth varies by design: analysis agents (security scanner, secrets, dependency audit, clone detector, privacy, auth, performance, compatibility, …) apply real algorithms — regex/AST detection, OWASP/CWE rules, hash-based clone matching — while planning agents (coder, debugger, tester, …) are structured expert playbooks: curated steps, checklists, and pitfalls for the task category, built to be reasoned over by the AI you already pay for rather than to reason themselves.

Path A — Agentic loop (most clients: Claude Code, Cursor, Windsurf)

Veto returns the specialist's role, rubric, and an output contract as an llm_upgrade prompt. The host AI reasons as the specialist and passes structured JSON back to complete the operation. This is the primary path — it costs nothing beyond your existing subscription and works on every client.

Path B — MCP Sampling (clients that support server.createMessage)

Where Sampling is available, the same upgrade happens server-side without the extra round-trip. Note: the July 2026 MCP spec revision deprecates Sampling protocol-wide (12-month sunset), so the agentic loop (Path A) is Veto's long-term default; Sampling remains a transparent optimization where it exists.

The 7-agent Council is LLM-first — its value is the multi-agent debate — but it too falls back to a deterministic verdict when no LLM path is available. When multiple agents run, they execute in parallel.

---

Specialist Roles

49 specialists: 42 deterministic worker agents across 6 domains + a 7-agent Council. The Council debates trade-offs before you build; the worker agents do the hands-on analysis and planning. Each is a deterministic expert module that can upgrade to LLM reasoning — see How the Agents Work. List them anytime with veto agents.

Council (7) Lead Dev · PM · Architect · UX · Devil's Advocate · Legal · Security

Development (12) Coder · Code Reviewer · Tester · Debugger · Refactor · Database · API · Frontend · Backend · DevOps · Performance · Migration

Security (6) Security Scanner · Auth Agent · Data Privacy · Secrets Agent · Dependency Audit · Penetration Tester

Memory (5) Context Manager · Decision Logger · Project Mapper · Pattern Learner · Knowledge Base

Research (7) Researcher · Tech Advisor · Cost Analyzer · Competitor Analyzer · Risk Assessor · Estimator · Ethics & Bias

Quality (5) Code Quality · Documentation · Accessibility · Compatibility · Error Handling

Workflow (7) Task Planner · Task Coordinator · File Manager · Git Agent · Search Agent · Reporter · Automation

---

MCP Tools (93)

Category	Tools
Session	veto_status · veto_session_save · veto_session_restore · veto_sessions_list · veto_autosave_status · veto_session_replay
Router	veto_route_task · veto_rate_status
Council	veto_council_debate · veto_benchmark · veto_adr
Agents	veto_agent_plan · veto_execute_parallel · veto_explain · veto_compose_agents · veto_delegate
Review	veto_code_review · veto_security_scan · veto_secrets_scan · veto_diff_review · veto_full_review · veto_pr_review
Pipelines	veto_ci_gate · veto_pre_commit · veto_new_feature · veto_workflow · veto_task_parse
Advanced	veto_local_llm · veto_semantic_search · veto_sdd_agent · veto_playwright · veto_notify_ide
Quality	veto_clone_detector · veto_lint_rules · veto_api_contract · veto_a11y_advisor · veto_type_coverage · veto_test_gaps
Advisors	veto_dep_advisor · veto_dep_verify · veto_query_advisor · veto_bundle_advisor · veto_dead_code · veto_hitl_checkpoint · veto_drift_check
Watching	veto_watch · veto_watch_poll · veto_watch_stop
Memory	veto_memory_store · veto_memory_search · veto_memory_delete · veto_decisions · veto_project_map_update · veto_project_map_get · veto_pattern_store · veto_patterns_list · veto_memory_export · veto_memory_import
Learning	veto_record_outcome · veto_learning_stats · veto_learning_apply
Handoff	veto_handoff · veto_continue · veto_platform_setup
Observability	veto_usage_status · veto_audit_log · veto_health · veto_metrics · veto_snapshot
Discover	veto_discover · veto_summarize · veto_git_blame · veto_changelog · veto_onboard · veto_debt_register
DevTools	veto_docs_fetch · veto_context_status · veto_openapi_gen · veto_flag_auditor · veto_env_setup · veto_commit_message · veto_pr_description · veto_pr_post · veto_prompt_optimizer · veto_sre_advisor · veto_diagram · veto_rca · veto_doc_gen · veto_postmortem · veto_release_notes · veto_translate · veto_merge_conflict
Plugins	veto_plugins

Compact Mode — 93 tools without the context tax

93 tool schemas cost a client ~20K context tokens before the user types a word. Compact mode advertises a surface that is 5–6× smaller: seven core tools (veto_status, veto_session_save, veto_session_restore, veto_route_task, veto_council_debate, veto_memory_search, veto_record_outcome) plus two meta-tools — veto_find_tools searches the full catalog by keyword and returns matching schemas on demand; veto_call invokes any catalog tool by name. Every tool remains directly callable in both modes; compact only changes what is advertised up front.

Enable it with VETO_COMPACT=1 in your MCP server config env, or "compact_tools": true in ~/.veto/config.json:

{
  "mcpServers": {
    "veto": {
      "command": "npx",
      "args": ["-y", "--package", "@jigyasudham/veto@latest", "veto-server"],
      "env": { "VETO_COMPACT": "1" }
    }
  }
}

Dependency-Hallucination Guard

LLMs propose plausible-but-nonexistent package names, and adversaries register those names on public registries (slopsquatting) — a supply-chain attack class with no pre-install check in most AI workflows. veto_dep_verify checks every proposed package against the live registry before you install:

veto_dep_verify { packages: ["axios", "axois", "left-padd"], ecosystem: "npm" }
→ axios      verified    (14 years old, 40M downloads/month)
→ axois      HIGH_RISK   (1 edit from "axios" — possible typosquat)
→ left-padd  NOT_FOUND   (likely hallucinated — do NOT retry the install later:
                          nonexistent AI-suggested names are prime slopsquat targets)

Signals per package: registry existence, age, monthly downloads, version history, deprecation, and typo-distance from popular packages. Supports npm, PyPI, and crates.io. Network failures return unverifiable — never silently safe.

Decision-Drift Enforcement

AI assistants forget architectural decisions and re-litigate them sessions later — the most common complaint about long-running AI projects. Veto's memory doesn't just store decisions; it enforces them. Record a decision once as a machine-checkable constraint:

veto_decisions {
  action: "add",
  rule: "We use Postgres — no Mongo",
  why: "Decided 2026-05: relational data, team expertise",
  forbidden_patterns: ["mongoose", "mongodb"],
  severity: "block"
}

From then on, veto_diff_review and veto_ci_gate automatically fail any diff whose added lines match a forbidden pattern — when an AI quietly adds mongoose to the imports three sessions later, the review fails with the rule and the rationale attached. Patterns are case-insensitive regexes (with substring fallback), optionally scoped to a file glob (src/**/*.ts), per-project or global, severity block or warn. Manage with action: list / check / disable / enable.

You don't have to remember to do this. When a council verdict (the LLM-backed one) or an ADR settles something, its result carries a one-time constraint_invitation: your AI asks you once whether it should become a rule, and passes your answer back as add or decline with the invitation_id. It never asks twice about the same verdict. action: list shows how many invitations were offered, accepted and declined; that count stays on your machine.

A rule can't stall your reviews. add refuses a pattern that could hang the check: one over 200 characters, or a repeated group that itself repeats, like (a+)+. Every check is also time-boxed, so a slow rule turns into a warning instead of blocking veto_ci_gate.

Compounding-Error Circuit Breaker

Agents fail silently in loops — retrying the same broken call, re-hitting the same error, thrashing between two tools — and burn a whole session before anyone notices. veto_drift_check scans the recent tool-call trace for that pattern mid-flight and trips a breaker before the spiral compounds:

veto_drift_check
→ DRIFT DETECTED
  • 4 consecutive failed calls (veto_diff_review)
  • same error repeated 3× ("no diff provided")
  • tool veto_route_task called 6× in a row
→ remediation (debugger agent): stop retrying; the diff is empty —
  point at a project_dir with uncommitted changes or pass `diff` explicitly.

It looks for three drift signals — consecutive failures, duplicate error messages, and single-tool repetition — and when any trips, it runs the debugger agent over the trace for a concrete recovery step instead of letting the loop continue. Call it as a periodic checkpoint in long agentic runs.

Which tool do I use?

Several tools overlap by design (different granularity or entry point). Quick guide:

Reviewing code

You have…	Use	Note
A snippet or single file in hand	veto_code_review	not veto_diff_review, which reads a git diff
Uncommitted/changed files (git diff)	veto_diff_review	code + security + secrets scans in parallel
To gate a commit (hard-block on secrets)	veto_pre_commit	tuned for commit-time
To gate CI (exit code + pass/warn/fail)	veto_ci_gate	for GitHub Actions / GitLab CI
A deeper pre-merge/pre-ship pass (+ quality)	veto_full_review	richer than veto_diff_review
A GitHub PR by number/URL	veto_pr_review	fetches the diff, returns postable comments

Remembering things

Want to…	Use
Save/recall a solution, decision, or reference	veto_memory_store / veto_memory_search
Track a recurring code convention	veto_pattern_store / veto_patterns_list
Navigate the codebase without scanning the filesystem	veto_project_map_get (refresh via veto_project_map_update)

Running multi-step work

Want to…	Use
Run several agents at once on one task	veto_execute_parallel
Run a sequential pipeline with pass/fail gates	veto_workflow
Turn a PRD / plain English into a task DAG	veto_task_parse (feeds veto_workflow)
Plan a new feature end-to-end (council → plan → tasks)	veto_new_feature

Sessions

Want to…	Use
Resume work with full saved context	veto_session_restore (or veto_continue for the latest)
See the event / tool-call timeline of a session	veto_session_replay
Move work to another AI tool	veto_handoff → veto_continue

MCP Resources

URI	What it returns
veto://sessions	All saved sessions across platforms
veto://project-map?dir=<path>	Stored project structure map
veto://memory?q=<query>	Knowledge base search results
veto://patterns	Learned coding patterns

MCP Prompts

Prompt	What it does
code-review	Full code review — paste code, get scored findings
security-audit	OWASP Top 10 scan with CWE references
deploy-checklist	Council reviews your deployment plan before you ship
explain-file	Expert explanation of any file, auto-routed by type

---

CLI Commands

These work standalone in any terminal — no AI client needed. The bare veto command comes from the global install (npm i -g @jigyasudham/veto, see Getting Started); without it, prefix any command with npx -y @jigyasudham/veto@latest.

veto init                        # Register Veto with every AI app found + scan project
veto doctor                      # Per app: does it list Veto, does Veto start, has the app started it?
veto doctor --quick              # Same, without launching the server to test it
veto doctor --fix                # Also move aside old Veto guides left in Codex/Gemini files
veto status                      # Version, DB path, session/memory/outcome counts
veto version                     # Alias for veto status
veto sessions [words]            # Newest 20 saved sessions, and how many exist ([auto] = auto-save)
veto sessions --all | --limit N  # All of them, or N; add --json for machine output
veto sessions --clean            # Remove auto-saves older than 7 days
veto continue <id> --as <client> # Restore a session from a terminal (8-character id prefix is enough) —
                                 #   the same code as veto_continue, for an app that did not load Veto
veto memory [query]              # Search knowledge base (blank = all entries)
veto patterns [prefix]           # List learned agent/routing patterns
veto tools [filter]              # List all 93 MCP tools (--json for machine output)
veto agents [filter]             # List all 49 specialists — workers + council (--json)
veto routing [status|log|reset]  # Inspect the opt-in routing feedback loop
veto transcripts <sub>           # Opt-in transcript capture (off by default) —
                                 #   enable|status|sources|list|show|purge|disable
veto lessons <sub>               # Opt-in note sharing between your AIs (off by default) —
                                 #   on|status|list|why|forget|flows|off|exclude|include|alias|recheck
veto statusline <sub>            # Veto line under the Claude Code prompt, or beside
                                 #   Codex/Gemini — install|status|print|watch|uninstall
veto api <command>               # JSON for editor extensions — version|snapshot|recall search|
                                 #   recall expand|diagnostics (see "For editor extensions" below)
veto hook install                # Install pre-commit secrets scan hook
veto hook remove                 # Remove the veto pre-commit hook
veto check                       # Scan staged changes for secrets (used by hook)
veto help                        # Commands + MCP tools reference
veto help --troubleshoot         # Full troubleshooting guide

veto doctor

veto doctor

  Veto Doctor — system health check
  ─────────────────────────────────────────────────────
  ✓ Node.js v22.13.0 (this terminal)
  ✓ ~/.veto exists
  ✓ Database ~/.veto/veto.db
    17 sessions · 12 memories · 3 patterns

  AI apps — registration · launch test · last start
  ─────────────────────────────────────────────────────
  ✓ Claude Code — connected
      source: claude mcp list
      launch test: answered in 1.2 s — Veto 3.7.0, 93 tools
      last started by claude-code 2.1.0 3 h ago — Veto 3.7.0, Node v22.13.0
  ✗ Antigravity — Veto is only in ~/.gemini/antigravity-cli/mcp_config.json, a file Antigravity no longer reads
      fix: veto init   (then fully restart the app)
  · Gemini CLI — not installed

  Fallback guidance — what an AI is told when Veto did not load
  ─────────────────────────────────────────────────────
  ✓ ~/.claude/skills/veto/SKILL.md

  ⚠  1 issue found. Each has its fix above.

Every ✓ says what it rests on. Registration is what the app's own mcp list reports (or the file the app reads, when its CLI is not on PATH). The launch test runs the exact configured command and completes the MCP handshake, which catches npx failing to reach the registry and a server that exits on start. Last started comes from the server itself: each time an app starts Veto, it records which app, which Node, and whether SQLite loaded in that app's runtime (~/.veto/host-starts.json). That is the only check that sees a GUI app launching Veto with a different Node than your terminal. veto doctor exits with status 1 when it finds an issue, so scripts can rely on it.

When an AI's app did not load Veto, Veto's veto skill (written by veto init into Claude Code, Codex and Antigravity/Gemini skill folders) tells it to say so and use veto continue / veto sessions / veto doctor instead of reading Veto's database by hand.

Versions of veto init before this release wrote Veto's guide over ~/.gemini/GEMINI.md (Gemini's own memory file) and into ~/.codex/AGENTS.override.md, which Codex reads instead of your ~/.codex/AGENTS.md. Current versions never write either file. veto doctor reports any copy left behind, and veto doctor --fix (or veto init) renames a copy to *.veto-backup — only when the file is exactly a guide Veto shipped. A file with anything else in it, such as memories Gemini saved below the guide, is reported and never touched. What an old init overwrote cannot be recovered.

For editor extensions: veto api

An extension that shows Veto's state reads it through veto api, not by opening Veto's databases. Every response is one JSON envelope on stdout (contract, command, backend_version, state, and message / next_action whenever state is not ok). Its shape is versioned apart from Veto. Within contract 1, fields are only added, so ignore fields you do not know.

Command	Request	Returns
version	—	contract version, commands, the CLI's path, whether SQLite loads
snapshot	{ project, db? }	capture state, archive counts for the project, lesson sharing and counts, the trial's progress. Read-only, and returns counts rather than paths
recall search	{ project, query, limit?, source?, db? }	masked hits from that project's archived chats, and the matching chats' segments
recall expand	{ project, event_id } or { project, archive_id, segment_index }	masked text of one turn or segment, only if it belongs to that project
diagnostics	{ checks?: ["host_cli", "probe"], db? }	veto doctor's per-app checks. The slow ones run only when named

Send the request as JSON on stdin, and start the CLI with an argument array and no shell: execFile(process.execPath, [cliPath, 'api', 'recall', 'search', '--stdin']), where cliPath comes from veto api version. On Windows, veto is a .cmd shim that only a shell can start, and passing a search query through a shell turns it into a command line. A project is always required, and a db other than the one Veto uses is refused with db_mismatch rather than answered from the wrong database. Archives kept after capture is turned off can still be searched, and each response says what state capture is in. veto transcripts purge is what deletes them. The JSON Schemas and example responses ship in the package under contracts/api-v1/.

veto statusline

In Claude Code, veto statusline install adds a Veto line under the prompt: the latest council verdict, router confidence, live context and rate-limit use, and memory size. While note sharing is on, it also shows how many notes Veto holds (notes 178); with sharing off, that count is left out rather than shown as zero.

Codex and Gemini cannot run a custom status line — each only shows its own built-in items (Codex: openai/codex#20244). So there, the same line runs in a small split pane beside the AI and follows its session in the current folder:

veto statusline watch                    # follows whichever AI is working in this folder
veto statusline watch --client=codex     # or pin one: claude | codex | gemini
veto statusline install --client=codex   # prints the split-pane setup for your terminal; writes nothing

For Codex it reads context and rate-limit use from Codex's own session file; Gemini records no usage figures, so its line shows the live session without gauges. veto statusline print --client=codex prints one line, for a tmux status bar or a script.

---

Council Debate

Two-phase flow — works on Claude Code, Gemini CLI, Antigravity CLI, and Codex CLI with no API keys:

# Phase 1 — call with task, get instant deterministic result + LLM upgrade prompt
veto_council_debate {
  task: "migrate auth from sessions to JWTs",
  project_dir: "/your/project",
  strictness: "standard"
}
→ {
    llm_backed: false,
    final_verdict: "YELLOW",
    votes: { lead_dev: {...}, architect: {...}, security: {...}, ... },
    llm_upgrade: {
      available: true,
      instruction: "Read debate_prompt, reason as all 7 agents, call again with agent_responses",
      debate_prompt: "You are running a Veto Council debate. Analyze the task as each specialist..."
    }
  }