blastproof
CLAUDE.md1 starsChanged 10 days agoApache-2.0View on GitHub
Blastproof is a safety gateway for AI agents. Every tool call an agent makes passes through it: reads run directly; writes are previewed on a Neon database branch, explained in plain language, judged by rules and an LLM, then auto-approved, blocked, or held for the owner's approval before being committed with an audit trail. The plans are the source of truth. Read the relevant one before any task: Historical, not for implementation: docs/plan-audit.md and docs/audit-response.md record the pre-build audit. Where…
- Reads credentials
In this repository2 other files it gives its agents.
- frontend/AGENTS.mdAGENTS.md
- frontend/CLAUDE.mdCLAUDE.md
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
15 rules. About 0 are common, 9 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 49
Start every session by reading PROGRESS.md and the plan step you are asked to do.
- Distinctive: line 53
If the plan seems wrong, say so and propose a change.
- Distinctive: line 54
Every change comes with tests.
- Very specific: line 57
Update PROGRESS.md; add any real decision (with the reason) to docs/decisions.md.
- Distinctive: line 58
Keep changes small and focused.
- Very specific: line 64
Commit exactly what was previewed: pinned_sql is previewed, approved and committed.
- Distinctive: line 68
Every number in an LLM summary must match the computed facts.
- Distinctive: line 88
Every route declares a Pydantic response model (the frontend generates types from it).
- Distinctive: line 93
Always read and fix autogenerated Alembic migrations before applying them.
- Distinctive: line 101
Use shadcn/ui components before writing custom ones.
- Very specific: line 105
Before using these, check their CURRENT documentation, because APIs change often: MCP Python SDK, LangGraph (interrupts, Postgres …
- Distinctive: line 109
If installing on a company machine, use the approved package registry (e.g.
- Very specific: line 123
Never print, copy or commit values from .env files or secrets.
- Very specific: line 124
Only connect to the development Neon projects (blastproof-company-dev).
- Distinctive: line 127
Never weaken a security rule to make a test pass.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Blastproof
Blastproof is a safety gateway for AI agents. Every tool call an agent makes passes through it: reads run directly; writes are previewed on a Neon database branch, explained in plain language, judged by rules and an LLM, then auto-approved, blocked, or held for the owner's approval before being committed with an audit trail.
The plans are the source of truth. Read the relevant one before any task:
docs/spec.md- what we are building and whydocs/backend-plan.md- backend MVP, built in numbered steps 1-20docs/frontend-plan.md- dashboard MVP, built in steps F1-F13docs/decisions.md- decisions made during the build (append-only)
Historical, not for implementation: docs/plan-audit.md and docs/audit-response.md record the
pre-build audit. Where they differ from the plans or decisions.md, the plans win.
PROGRESS.md- which steps are done, what is next, known issues
Repo layout
backend/- FastAPI app: MCP server, hook API, REST API, LangGraph workflowfrontend/- Next.js dashboard and public landing pagedemo_company/- fake customer database (schema, seed, schema docs)claude_hook/- PreToolUse hook script for Claude Codedocs/- plans and decision log
Commands
Backend (run from backend/):
docker compose up -d(repo root) - start Blastproof's local Postgresuv sync- install dependenciesuv run uvicorn app.main:app --reload --env-file .env --log-config log_config.json- run the API on :8000 (--env-fileputs the model key where LangChain reads it;--log-configmakes uvicorn's own startup lines JSON too)uv run pytest- fast unit tests only, no Docker (the local default, D-179);uv run pytest --integration --skip-slow- the local integration run, 3 minutes, without the seed-heavy files (needs Docker up; D-190); the full suite (--integrationalone) runs only in CI and is never run locally (D-191)uv run ruff check . ../demo_company ../claude_hook && uv run ruff format --check . ../demo_company ../claude_hook- lint (as CI does)uv run python -m app.cli bootstrap --admin-email ... --admin-name ...- first admin, agent, main system and knowledge base (safe to re-run)uv run alembic revision --autogenerate -m "..."thenuv run alembic upgrade headuv run python -m evals.run- eval suitedocker build -f backend/Dockerfile -t blastproof-backend:local .(repo root), thenbash docker/image-smoke.sh blastproof-backend:local- build and smoke-test the deploy image (CI:image.yml)uv run python -m app.cli deploy-check --url https://blastproof.fly.dev- read-only probe of the deployed backend; the owner's deploy checklist isdocs/deploy.mduv run python -m app.cli dashboard-check --url https://blastproof.in- read-only probe of the deployed dashboard; the Vercel checklist isdocs/deploy-dashboard.md
Frontend (run from frontend/):
npm run dev- dashboard on :3000npm run lint && npm run format:check && npm run typecheck && npm test- checksnpm run gen:api- regenerate API types frombackend/openapi.json(no server needed); after a route change runuv run python -m app.cli export-openapifirst
How we work
- Start every session by reading
PROGRESS.mdand the plan step you are asked to do. - Work on ONE plan step at a time. Do not start the next step unless asked.
- Plan before code: list files, functions, tests, and anything in the step that looks unclear or wrong. Wait for approval before writing code.
- If the plan seems wrong, say so and propose a change. Never silently deviate.
- Every change comes with tests. Run tests and lint before saying a step is done.
- Finish by running the step's "Done when" check and reporting the result honestly, including anything that does not work yet.
- Update
PROGRESS.md; add any real decision (with the reason) todocs/decisions.md. - Keep changes small and focused. Explain non-obvious code in plain language when asked.
Architecture rules (do not break these)
- Fail closed: any error, timeout or unparseable SQL blocks the write. The one exception: if only the AI judge fails, the write goes to human review. A failed check never lets a write through.
- Commit exactly what was previewed:
pinned_sqlis previewed, approved and committed; the commit must reproduce the approved diff or roll back. - The security boundary is credential isolation, not the hook. Hook rules are guardrails.
- Code counts, the LLM explains: numbers come from the database, never from a model. Every number in an LLM summary must match the computed facts.
- Rules run before the judge; the judge can only make a decision stricter, never looser.
- Reads take a fast path outside the LangGraph workflow. Only writes enter the graph.
- One SQL statement per write; reject BEGIN/COMMIT/ROLLBACK from agents.
- Ownership: every action stores the agent owner's
user_id. All action queries go throughvisible_actions(user). Another user's action returns 404, never 403. - Company database credentials live only in the backend's environment. Never in agent workspaces, logs, traces, prompts or API responses.
- Mask sensitive columns (email, phone, etc.) before data reaches logs, prompts or the UI.
- Pluggable by design:
Judge,VectorStoreandEmbedderare interfaces; LLMs are created fromprovider:modelconfig strings. Never hard-code a provider. - Knowledge text lives in Postgres (
knowledge_chunks); vector stores hold only vectors. - The backend never imports from
demo_company/. - The dashboard holds no business logic; the backend enforces every permission.
Conventions
Backend:
- Python 3.13, type hints everywhere, async I/O.
- Thin routes; logic in
app/services/; database code inapp/db/. - Every route declares a Pydantic response model (the frontend generates types from it).
- Errors:
{"error": {"code": "...", "message": "..."}}, including validation errors. - Lists:
{"items": [...], "total": n, "limit": n, "offset": n}. - IDs are UUID strings; timestamps are ISO 8601 UTC.
- Log with structlog; bind
request_idandaction_id. - Always read and fix autogenerated Alembic migrations before applying them.
Frontend:
- TypeScript strict mode. Server data only in TanStack Query; filters in the URL.
src/lib/api/schema.d.tsis generated: never edit it by hand.- The browser calls only
/api/blastproof/*; the proxy is the only code that knowsBLASTPROOF_API_URL. Never store tokens in localStorage. - Render agent-provided text as plain text. Never use
dangerouslySetInnerHTML. - Use shadcn/ui components before writing custom ones.
Libraries and docs
- Before using these, check their CURRENT documentation, because APIs change often:
MCP Python SDK, LangGraph (interrupts, Postgres checkpointer), Neon API (branches),
Claude Code hooks, Vercel AI Gateway, LangChain
init_chat_model. - Pin exact versions. Do not add a new dependency without asking first.
- If installing on a company machine, use the approved package registry (e.g. Artifactory) instead of public PyPI and npm.
Testing
- Unit tests: no network. Use fakes for LLM calls and the Neon client.
- Integration tests: real Postgres from Docker Compose.
- Authorization matrix test: every endpoint as owner, other user and admin.
- Integration tests and CI use the local
company-dbandFakeNeonClient; they never call Neon. - Evals live in
backend/evals/; the MVP incident replays (evals/scenarios/incidents.yaml) must stay at 100% caught.
Safety while building
- Never print, copy or commit values from
.envfiles or secrets. - Only connect to the development Neon projects (
blastproof-company-dev); never toblastproof-company, which only the deployed backend uses. Ask before any command that could delete or overwrite data on a Neon main branch, even the fake company database. - Never weaken a security rule to make a test pass; report the problem instead.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

