@codapult/guard

Architecture guardrails for AI-assisted development

Codapult Guard helps teams preserve the architecture that makes their project work as it changes. It maps a JavaScript or TypeScript codebase, lets the team approve project-specific boundaries, and checks future changes locally and in CI. AI agents can use the same project context and verification results as developers.

Catch project-specific regressions

A type checker can confirm that code is valid TypeScript. It cannot know that this project requires client components to stay away from persistence modules. Once the team approves that boundary, Guard can detect a violating import in changed files and show which rule was triggered.

Project boundary:  Client → Server Action → Service → Repository → Database
Possible regression: Client ─────────────────────────────────────→ Database

Guard discovers the architecture in the repository; it does not prescribe one universal structure or activate proposed rules without approval.

Get started

Requirements: Node.js >=20.19 and a JavaScript or TypeScript project.

# pnpm
pnpm add -D @codapult/guard
pnpm exec codapult-guard init

# npm
npm install --save-dev @codapult/guard
npx codapult-guard init

Review the generated project model, proposed rules, contracts, and baseline under .codapult/guard/ before relying on the results. Then run Guard's architecture checks:

pnpm exec codapult-guard verify --no-project-checks --tools off

verify can run your configured project checks and detected adapters. The flags above limit this run to Guard's built-in checks. With npm, run npx codapult-guard verify --no-project-checks --tools off. See the complete guide for initialization and daily workflows.

Use Guard with an AI agent

Install a managed instruction block for your agent so it knows when to load Guard context and run verification:

pnpm exec codapult-guard install-agent codex

Supported hosts and MCP setup are in the AI-agent integration guide and host integration guides.

The MCP server uses host-managed local stdio, with no network listener or application-level authentication. The host and operating system control process access and workspace permissions; see the security model.

Choose a GitHub setup

Choose a preset from the existing workflow templates and follow only the hosting steps for that level of protection. Most projects can start with standard PR checks.

| Preset | Use it when

... View full README on GitHub