pywrit

Find the dangerous writes in your Python agent's code, then gate it. pywrit is the Python client and writ CLI for Writ: an allow/deny gate that sits in front of your agent's consequential writes (database, HTTP, files, email, queues, AWS) and records a hash-chained receipt for every decision.

writ scan is local, deterministic, and free: it parses your code with Python's ast module, makes no network calls, and needs no API key.

Install

pip install pywrit

Requires Python 3.9+. Installs the writ command and the pywrit Python client.

JavaScript/TypeScript devs: run the scanner with no Python setup via npm:

npx writ-scan .

The writ-scan package wraps the same scanner (including TS/JS support). On first run it installs pywrit[polyglot] from PyPI using your Python 3.9+ (one-time); afterwards it starts instantly. See npm/ for details, environment overrides (WRIT_PYTHON, WRIT_SCAN_NO_INSTALL), and the install test.

Related MCP server: Vorim AI — Agent Identity & Trust

Language coverage

60-second quickstart: scan → wrap → gate

1. Scan. See which functions write, and how many of them are gated.

writ scan .

writ scan: /path/to/support-agent
  files scanned: 4  skipped: 0
  write sites: 4 in 3 function(s)
  gated: 0/4 (0%)
  verbs discovered: 3
    crm.update
    payments.refund
    tickets.close

It also prints a risk report (0-100, weighted by risk tier), writes the discovered verbs to writ-policy.json, and shows the instrumentation it would add as a unified diff. Nothing in your code changes yet. writ scan . --score prints just the risk report.

2. Wrap. One command takes the repo from unwrapped to wrapped: scan, show the diff, ask for explicit approval, apply the gates, and report before/after coverage.

writ wrap .        # interactive approval
writ wrap . --yes  # no prompt (e.g. in CI)

--dry-run previews the plan and exits before prompting; --diff-only prints the unified diff for review tools. Each gated function now asks Writ before it writes, and fails closed:

def issue_refund(charge_id, amount_cents):
    if _writ_check("payments.refund") != "ALLOW":
        raise PermissionError("writ denied payments.refund")
    ...

writ scan . --apply is still available as the manual alternative. Re-run writ scan . and you'll see gated: 4/4 (100%).

3. Gate. Get a free API key, load the discovered policy, and run your agent.

writ key --email you@example.com                  # free API key + tenant
export WRIT_API_KEY=writ_...                      # read by the inserted gate
export WRIT_SPONSOR=acme WRIT_AGENT=support-agent # optional: who is acting
writ scan . --push-policy --key "$WRIT_API_KEY"   # upload the discovered verb policy

Every gated write now gets ALLOW, DENY, or STEP_UP (a human sponsor must approve), and every decision is written to your tenant's tamper-evident audit log:

writ receipts --key "$WRIT_API_KEY"       # latest receipts
writ verify-chain --key "$WRIT_API_KEY"   # verify the receipt hash chain
writ stream --key "$WRIT_API_KEY"         # tail decisions live
writ report --key "$WRIT_API_KEY"         # Agent Action Report

What writ scan detects

Python (.py) files, parsed with the stdlib ast (no extra dependencies):

• Each write is mapped to a verb such as payments.refund or crm.update, inferred from the file path and function name.

• A function that already calls writ_check(...) / _writ_check(...) counts as gated.

• Skipped: tests, hidden directories, virtualenvs, node_modules, dist, build. Use --exclude SUBSTR (repeatable) to skip more.

• Not covered (review by hand): writes behind dynamically built SQL, third-party SDK calls such as stripe.Refund.create(...), deferred task queues, or shared clients several layers down. The risk report lists these gaps every time.

TypeScript / JavaScript (scan-only)

writ scan also finds write sites in TypeScript and JavaScript. It needs the optional extra (tree-sitter based):

pip install 'pywrit[polyglot]'
writ scan .

Without the extra, the scanner prints a prominent warning block naming the unscanned TS/JS files and keeps going — Python scanning never needs it.

Findings from non-product paths (docs/, scripts/, sandbox/, examples/, benchmark/, demo/, and build-tooling files such as gulpfile.js or webpack.config.*) are suppressed by default: the report counts them per class and names every suppressed path instead of listing them as findings. Pass --include-non-product to report them like any other finding.

Every scan report ends with a one-line pointer to the Writ GitHub App (install: https://github.com/apps/writ-scanner, guide: https://docs.withwrit.com/git-hub-app), which runs the scan on every push and pull request; the JSON report (--format json) carries the same pointer under github_app.

TS/JS is scan-only: findings are listed with verbs for your policy file, but writ scan --apply never rewrites TS/JS files — gate those by hand. Covered patterns: fetch/axios writes, fs writes, SQL through knex-style clients, Prisma writes, JS SDK calls such as stripe.refunds.create(...), and generated REST resource clients: create / update / patch / remove methods (plus their ...WithHttpInfo variants) that build request options with an explicit write HTTP method and route them through the client request pipeline (twilio-style generated clients, e.g. twilio-node). (Still not covered: the Python SDK equivalents like stripe.Refund.create(...) — see "Not covered" above.)

Go (scan-only)

writ scan also finds write sites in Go. It needs the optional extra (tree-sitter based):

pip install 'pywrit[polyglot]'

Covered in this first family plus request-pipeline detection: database/sql Exec / ExecContext, GORM Create / Save / Update / Updates / Delete, HTTP client Post / Put / Patch / Delete and http.NewRequest / NewRequestWithContext with a write method, generated-client calls shaped <client>.<Resource>.<New|Update|Delete|Create> with an uppercase resource segment (the stripe-go shape), and request-pipeline calls X.Call(method, ...) / X.RawRequest(method, ...) where argument 0 is a write method (the stripe.Backend shape, e.g. c.B.Call(http.MethodPost, "/v1/accounts", ...)). GET/HEAD requests, db.Query / QueryRow, bare constructors, and pipeline calls with a variable method or a non-method first argument are not flagged. _test.go files and vendor/ trees are skipped. Go is scan-only: writ scan --apply never rewrites .go files, gate those by hand. Not yet covered: package-level generated clients (charge.New(...), the pre-v87 stripe-go shape), GORM raw-SQL helpers, and other Go write patterns.

GitHub Action

Scan every pull request for ungated write sites. Findings land as check annotations on the exact file and line, plus a Markdown risk report in the job summary. The check fails when an ungated finding meets your fail-on-risk threshold (default: high).

- uses: actions/checkout@v4
- uses: withwrit/pywrit@v0
  with:
    fail-on-risk: high   # high | medium | low | never

No API key needed. Full reference: docs/github-action.md · example workflow: examples/github-action/writ-scan.yml

GitHub App

Install the Writ GitHub App on selected repositories: every push and pull request is scanned for ungated write-sites, with results as a check run on the PR and in the portal, where you manage policy, keys, and the audit log. Setup and data handling: GitHub App docs.

MCP server (writ-mcp)

Give any MCP-compatible agent point-of-action policy checks. writ-mcp is a Model Context Protocol server (stdio transport, built on the MCP Python SDK) that exposes the Writ gate as 17 MCP tools: the agent calls writ_check before a consequential write and gets back ALLOW, DENY, or STEP_UP — with a tamper-evident, hash-chained audit receipt for every decision.

uvx writ-mcp            # no install — runs on demand
# or
pip install writ-mcp   # then run `writ-mcp`

The gate tools need a free Writ API key (WRIT_API_KEY): 10,000 receipts/month free, no credit card. writ_sandbox works with no key at all.

The server implementation lives in mcp/ (MIT). Also published on the official MCP Registry as io.github.withwrit/writ and listed on Glama.

Python client

from pywrit import WritClient

client = WritClient(api_key="writ_...")

result = client.check(
    sponsor_id="acme",
    agent_id="agent-7",
    verb="db.write",
    target="prod.customers",
    purpose="backfill region field",
)

if result.decision == "ALLOW":
    # result.auth_token is a short-lived token bound to this exact write
    perform_write(...)
elif result.decision == "STEP_UP":
    # a human sponsor must approve first: client.grant(...), then re-check
    ...
else:
    # DENY
    ...

No API key yet? Try the keyless sandbox:

client = WritClient()
client.sandbox({
    "sponsorId": "acme",
    "agentId": "agent-7",
    "verb": "demo_write",       # sandbox only allows demo_write ...
    "target": "demo-customers", # ... on targets starting with demo-
    "purpose": "trying the gate",
})

What's covered:

• check(...): the gate. ALLOW / DENY / STEP_UP, plus a receipt every time

• verify_token(...): validate an ALLOW auth token (catches purpose drift)

• grant(...): human-sponsor approval for the STEP_UP path

• get_policy() / set_policy(...): manage the tenant policy

• revoke(...) / reinstate(...) / revoked(): the kill switch

• receipts() / receipt(id) / verify_chain() / stream_receipts(): the audit log

• sandbox(...): keyless trial, no API key required

CLI reference

writ wrap .                         # scan, diff, approve, apply, verify coverage
writ wrap . --dry-run               # preview only
writ wrap . --yes                   # non-interactive CI mode
writ check --key writ_... --sponsor acme --agent agent-7 \
  --verb db.write --target prod.customers --purpose "backfill region field"
writ policy --key writ_... --set payments.refund require_grant
writ revoke --sponsor acme --agent agent-7 --reason "runaway loop"   # kill switch (sponsor token)
writ grant --sponsor acme --agent agent-7 --verb payments.refund \
  --target ch_123 --purpose "approved refund"                        # STEP_UP approval (sponsor token)

Sponsor-token commands (revoke, reinstate, revoked, grant) read --sponsor-token or WRIT_SPONSOR_TOKEN. Run writ --help for the full command list.

README badge

Show that your agent's writes are gated by Writ. Two flavors:

Static (works today, no API key) — same design, no live count:

[![agent writes gated by Writ](https://cdn.jsdelivr.net/gh/withwrit/pywrit@main/badge/writ-gated.svg)](https://withwrit.com)

Dynamic (live 30-day gated-write count from your audit log) — mint a badge token, then embed the snippet the API returns:

curl -s https://api.withwrit.com/v1/badge/tokens \
  -H "Authorization: Bearer writ_..." \
  -H "Content-Type: application/json" \
  -d '{}'

The dynamic endpoint ships with the gate — until it's live, POST /v1/badge/tokens returns 404 and the static badge above is the one to use.

See badge/ for embed docs and the verification model (what the badge proves — and what it doesn't).

Docs

Full docs: docs.withwrit.com · Quickstart: docs.withwrit.com/quickstart · Site: withwrit.com

License

MIT