Waymark: The Control Layer Your AI Coding Agent Was Missing

se it enables organizations to deploy AI agents in production-adjacent environments with confidence. The governance layer transforms agents from unpredictable actors into auditable, reversible tools.

Core Solution

Waymark operates as an MCP (Model Context Protocol) server that intercepts file writes and shell commands. It evaluates each action against a defined policy, executes the appropriate response, and maintains a local snapshot of all changes for reversibility.

Implementation Steps

1. Install the CLI: The tool is distributed via npm.

   npm install -g @way_marks/cli
   

2. Initialize Agent Registration: Register your host application. The CLI detects the environment and configures the agent to route through Waymark.

   waymark init
   

   This command establishes the connection with supported platforms such as Claude Desktop, Claude Code, or GitHub Copilot CLI.

3. Define Governance Policy: Create a configuration file that specifies allowed, blocked, and approval-required resources.

   {
     "allowedPaths": ["src/modules/**", "integration/tests/**"],
     "blockedPaths": [".env.production", "secrets/**", "*.p12"],
     "requireApproval": ["tsconfig.json", "Makefile", "helm/values.yaml"],
     "blockedCommands": ["rm -rf /", "regex:dd\\s+if=.*of=/dev"]
   }
   

   Policy Logic:

   • Allow: Actions matching allowedPaths execute automatically and are logged.
   • Block: Actions matching blockedPaths or blockedCommands are rejected immediately. The agent receives a clear error message explaining the violation.
   • Require Approval: Actions targeting requireApproval paths pause execution. The agent enters a waiting state until a human approves or rejects the action via the dashboard or Slack.

4. Start the Control Plane: Launch the MCP server and dashboard.

   waymark start
   

Architecture Decisions

• Interception Model: Waymark intercepts calls at the tool-use layer. This ensures that no file write or shell command reaches the filesystem without policy evaluation. This design prevents race conditions where an agent might bypass checks by executing commands directly.
• Snapshot-Based Reversibility: Before any file modification is committed, Waymark captures a snapshot of the original state. This enables one-click restoration from the dashboard or bulk rollback of an entire agent session. This approach is superior to git-based recovery because it captures the exact state prior to the agent's intervention, regardless of git history.
• Local-Only Telemetry: All monitoring data, including context window fill rates, token counts, and active tasks, remains local. The waymark agents command provides a live view of running processes without transmitting data externally.

$ waymark agents

Agent     PID    Status      Ctx%  Tokens   Task                         Age
copilot   39897  thinking     52%  146,032  Refactor auth middleware       1m
claude    64586  waiting      37%   75,060  (idle)                        12m

• Async Approval Integration: For requireApproval actions, Waymark supports Slack notifications with interactive buttons. This allows developers to review and approve changes from mobile devices without interrupting their workflow. The dashboard maintains a complete audit trail of who approved what and when.

Pitfall Guide

Pitfall	Explanation	Fix
Over-Blocking Configuration	Defining blockedPaths too broadly can halt agent productivity, causing frequent false positives.	Use granular glob patterns. Reserve blockedPaths for truly sensitive files and use requireApproval for gray areas.
Shell Command Blind Spots	Focusing only on file paths while ignoring shell commands leaves the system vulnerable to destructive operations.	Define blockedCommands with regex patterns to catch dynamic threats like `curl
Snapshot Storage Bloat	Continuous snapshots can consume significant disk space over long sessions.	Monitor disk usage and implement session cleanup routines. Waymark allows rolling back entire sessions, so retain snapshots only as long as needed.
Approval Fatigue	Setting too many files to requireApproval can overwhelm developers, leading to blind approvals.	Limit requireApproval to critical infrastructure files (e.g., Dockerfile, package.json). Trust the agent for routine source code changes.
Context Window Saturation	Agents may degrade in quality as context fills, but developers remain unaware.	Monitor Ctx% via waymark agents. Set alerts or manually intervene when context usage exceeds 80%.
Ignoring Agent Status	Agents can enter stuck states (e.g., waiting for input) without developer knowledge.	Regularly check waymark agents for agents in waiting status with high age.
Config Drift	Policy configurations may diverge across environments or team members.	Version control the Waymark configuration file. Ensure all team members use the same governance baseline.

Production Bundle

Action Checklist

• Install Waymark CLI globally using npm install -g @way_marks/cli.
• Run waymark init to register your AI coding agent.
• Create a policy configuration with blockedPaths for all secrets and credentials.
• Define blockedCommands to prevent destructive shell operations.
• Configure Slack integration for async approvals on critical files.
• Verify telemetry by running waymark agents and confirming local data visibility.
• Test the rollback mechanism by modifying a dummy file and restoring via the dashboard.
• Commit the Waymark configuration to your repository to ensure consistent governance.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Solo Development	Local Dashboard	Provides full control and audit without external dependencies.	Free; minimal setup.
Team Collaboration	Slack Integration	Enables async approvals and shared visibility across the team.	Requires Slack App configuration.
High-Security Environments	Strict blockedPaths + requireApproval	Ensures no sensitive files are touched without explicit review.	Increases approval latency; improves security posture.
CI/CD Pipelines	Headless Mode (if supported)	Automates governance checks without human intervention.	May require custom scripting for approval simulation.

Configuration Template

Use this template as a starting point for your governance policy. Adjust paths and commands based on your project structure.

{
  "allowedPaths": [
    "src/**",
    "lib/**",
    "tests/**"
  ],
  "blockedPaths": [
    ".env",
    "*.pem",
    "*.key",
    "config/secrets/**"
  ],
  "requireApproval": [
    "package.json",
    "Dockerfile",
    "docker-compose.yml",
    "tsconfig.json",
    "helm/**"
  ],
  "blockedCommands": [
    "rm -rf",
    "sudo",
    "regex:curl.*-o\\s+/",
    "regex:chmod\\s+777"
  ]
}

Quick Start Guide

1. Install: Run npm install -g @way_marks/cli.
2. Initialize: Execute waymark init to connect your agent.
3. Configure: Create a policy file with blockedPaths for sensitive data.
4. Launch: Run waymark start to begin the control plane.
5. Monitor: Use waymark agents to view live telemetry and manage sessions.