{"id":48414964,"url":"https://github.com/waymarks/waymark","last_synced_at":"2026-06-05T08:00:55.715Z","repository":{"id":349351068,"uuid":"1201067692","full_name":"waymarks/waymark","owner":"waymarks","description":"Control what AI agents can do in your codebase","archived":false,"fork":false,"pushed_at":"2026-05-30T17:07:11.000Z","size":3946,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T19:06:08.841Z","etag":null,"topics":["agent-control","ai-agents","claude-code","developer-tools","llm","mcp","security","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@way_marks/cli","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/waymarks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T06:55:59.000Z","updated_at":"2026-05-30T17:07:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/waymarks/waymark","commit_stats":null,"previous_names":["waymarks/waymark"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/waymarks/waymark","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waymarks%2Fwaymark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waymarks%2Fwaymark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waymarks%2Fwaymark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waymarks%2Fwaymark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/waymarks","download_url":"https://codeload.github.com/waymarks/waymark/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waymarks%2Fwaymark/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33935514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-control","ai-agents","claude-code","developer-tools","llm","mcp","security","typescript"],"created_at":"2026-04-06T07:06:24.691Z","updated_at":"2026-06-05T08:00:55.672Z","avatar_url":"https://github.com/waymarks.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"https://github.com/user-attachments/assets/5940e42a-e231-4311-8e24-1ea37699662e\n\n# Waymark\n\n[![npm downloads](https://img.shields.io/npm/dm/%40way_marks%2Fcli?label=%40way_marks%2Fcli\u0026style=flat-square\u0026color=6366f1)](https://www.npmjs.com/package/@way_marks/cli)\n[![npm downloads](https://img.shields.io/npm/dm/%40way_marks%2Fserver?label=%40way_marks%2Fserver\u0026style=flat-square\u0026color=10b981)](https://www.npmjs.com/package/@way_marks/server)\n[![npm version](https://img.shields.io/npm/v/%40way_marks%2Fcli?label=version\u0026style=flat-square\u0026color=374151)](https://www.npmjs.com/package/@way_marks/cli)\n\n![npm download chart](./docs/npm-downloads.svg)\n\n\u003e Updated every 6 hours via GitHub Actions\n\n---\n\n\u003e ⚠️ **Package renamed as of v0.5.0**\n\u003e The old `@shaifulshabuj-waymarks` packages have been deprecated.\n\u003e Please switch to the new package scope:\n\u003e\n\u003e ```bash\n\u003e npm uninstall @shaifulshabuj-waymarks/cli @shaifulshabuj-waymarks/server\n\u003e npm install @way_marks/cli\n\u003e ```\n\u003e\n\u003e All future updates will be published under `@way_marks` only.\n\n---\n\n## ✨ What's New in v5.0.0 — Unified Architecture\n\n**One daemon, all projects, one URL — global management for multi-project teams**\n\n### 🚀 Global Daemon (`waymark daemon`)\nSingle process on port 47000 for all projects. Dashboard is always `http://localhost:47000`.\n\n```bash\nwaymark daemon start           # start once, handles all projects\nwaymark service install        # auto-start on login (launchd/systemd)\n```\n\n### 🔌 Universal MCP (`waymark global-setup`)\nOne Claude Desktop MCP entry for all projects. Stable tool names: `mcp__waymark__write_file`, `mcp__waymark__read_file`, `mcp__waymark__bash`.\n\n```bash\nwaymark global-setup           # register once\nwaymark cleanup-mcp            # remove old per-project entries\n```\n\n### 🪪 Stable Project Identity\n`\"id\"` field in `waymark.config.json` — stable across renames, moves, and clones. `waymark init --id my-service --yes` for CI/automation.\n\n### 📋 Policy Inheritance\n`\"extends\": \"global\"` inherits from `~/.waymark/global.config.json`. Global blocked rules are always enforced.\n\n### 👥 Global Team + 🗂️ Workspaces\n`waymark team` manages a shared `~/.waymark/team.json`. `waymark workspace` groups related projects for bulk start/stop/status.\n\n### 🛠️ New Commands\n`waymark doctor`, `waymark relocate`, `waymark update-instructions`, `waymark prompt-status`, `waymark shell-integration`, `waymark global-config`.\n\n### Migration\n```bash\nwaymark global-setup \u0026\u0026 waymark daemon start \u0026\u0026 waymark service install\nwaymark cleanup-mcp \u0026\u0026 waymark update-instructions --all \u0026\u0026 waymark doctor\n```\n\nSee [CHANGELOG](CHANGELOG.md) for full details.\n\n---\n\n## ✨ What's New in v4.9.0\n\n**Enterprise notifications \u0026 analytics — block persistence, webhook fan-out, email approval tokens, per-member prefs, analytics cards**\n\n### 🔒 Active block persistence (F-54)\n- Blocks written to `active_blocks` SQLite table on creation — survive server restarts\n- On startup, all uncleared blocks (`WHERE unblocked_at IS NULL`) are reloaded automatically\n- Cleared blocks stay cleared; restarts no longer silently unblock sessions\n\n### 🔔 Webhook notifications (F-55)\n- POST to any HTTP endpoint when events fire: `action.pending`, `action.blocked`, `action.approved`, `action.rejected`, `block.added`, `block.cleared`\n- HMAC-SHA256 signed payloads (`X-Waymark-Signature: sha256=\u003chex\u003e`) — verify integrity server-side\n- Configure multiple webhooks (PagerDuty, Slack, custom) in `.waymark/config.json`\n\n### 📧 Email approval tokens (F-56)\n- Every pending action generates two single-use 48h token URLs (approve + reject)\n- Approvers click a link in email — no dashboard login required\n- Tokens are invalidated immediately on use; expired/used tokens return HTTP 410\n\n### 🔕 Per-member notification preferences (F-57)\n- Each team member can opt in/out of email and webhook notifications per event type\n- Configure via **Settings → Team → Prefs** or `PUT /api/team/:id/notification-prefs`\n- Default: email + webhook enabled for `action.pending` and `action.blocked`\n\n### 📊 Analytics dashboard cards (F-58)\n- **Top Blocked Paths** — which files trigger block rules most often\n- **Busiest Hours** — when agents are most active (plan human coverage)\n- **Avg Approval Latency** — average minutes from pending → decision\n- Data sourced from `GET /api/analytics/summary`; cards appear automatically when data exists\n\nSee [CHANGELOG](CHANGELOG.md) for full details including 4 critical bug fixes.\n\n---\n\n## ✨ What's New in v4.8.0\n\n**Complete rebuild of the Agent Monitor dashboard (`/agents` route), CLI commands, and server-side collection.**\n\n- **Session history** — Completed sessions saved to `agent_history` table; new History tab shows all past runs with duration, tokens, model, and Waymark badge.\n- **Waymark badge** — Cards and CLI rows now distinguish sessions whose tool calls flow through Waymark policy enforcement (`⬡ Waymark`).\n- **Sparklines \u0026 burn rate** — Token and context-window sparklines per session card; burn rate label (`+Nk/turn`).\n- **Port management** — Ports classified as browser/api/db/system/other; 🌐/🔒 binding visibility; Kill button for orphan ports.\n- **Full-content modal** — Click any tool call row to see complete untruncated args (up to 2000 chars) in a scrollable overlay.\n- **Rate-limit guide \u0026 `waymark setup-hook`** — Actionable setup guide when rate data is absent; new CLI command installs the Claude Code Stop hook automatically.\n- **Token usage by project** — New bar chart in Stats view showing top 10 projects by total agent tokens.\n\nSee [CHANGELOG](CHANGELOG.md) for full details.\n\n---\n\n## ✨ What's New in v4.7.0\n\n**Major feature release — bash approval queue, new CLI commands, policy editor, dashboard enhancements, and wired remediation engine**\n\n### 🛡️ Policy engine extensions\n- **`requireApprovalBash[]`** — queue bash commands for human approval, just like file writes\n- **`allowedCommands[]`** — explicit bash command allowlist\n- **Policy editor in dashboard** — add/remove rules visually with live save\n- **`POST /api/policy/test`** — test any path/command against active policy\n\n### 🖥️ New CLI commands\n```bash\nwaymark explain \u003cid\u003e    # human-readable summary of any logged action\nwaymark watch           # live terminal dashboard (ANSI, 2s refresh)\nwaymark init --dry-run  # preview init without writing files\n```\n\n### 📊 New API endpoints\n- `GET /api/sessions/:id/diff` — unified patch across all session writes\n- `GET /api/audit/export?format=csv|json` — downloadable audit log\n- `POST /api/actions/:id/approve-with-edit` — approve with inline content changes\n- `POST /api/sessions/:id/rollback-partial` — selective per-action rollback\n- `GET /api/analytics/summary` — top blocked paths, busiest hours, approval latency\n\n### 🎛️ Dashboard enhancements\n- **Agent pause/resume** — SIGSTOP/SIGCONT from SessionCard\n- **Selective session rollback** — checkboxes per write_file + \"Rollback selected\" button\n- **Escalation deadline badges** — amber/red urgency in Approvals inbox\n- **Approve-with-edit** — edit file content inline before approving\n- Context window progress bar, pending count badge, dark mode auto-detection, tab title badge\n\n### 🔒 Remediation engine (now live)\nRisk scoring, HIPAA/SOC2/PCI/GDPR compliance evaluation, and remediation recommendations are fully wired (were stub responses in v4.6.x).\n\nSee [CHANGELOG](CHANGELOG.md) for the full entry with all 7 phases and bug fixes.\n\n---\n\n## ✨ What's New in v4.3.2\n\n**Bug fix: Approvals inbox now shows all pending actions**\n\nThe `/approvals` page was always showing “Inbox zero” even when policy-held writes were waiting. Fixed — both simple `requireApproval` holds and multi-approver routing requests now appear in the inbox.\n\nAlso in v4.3.1:\n- Anyone-can-approve routes no longer incorrectly reject all approvers\n- Reviewer ID is now editable from the settings popover (top-right ⚙️)\n- Actions list refreshes immediately after an escalation decision (no more 30-second wait)\n- Slack Approve / Reject buttons now push live updates to all open browser tabs instantly\n\nSee [CHANGELOG](CHANGELOG.md) for details.\n\n---\n\n## ✨ What's New in v4.1.0\n\n**Stability Patch**\n\n- ✅ Database initialization optimized for test isolation\n- ✅ All test assertions passing (92% pass rate)\n- ✅ Risk assessment and approval routing fully tested\n- ✅ Production-ready patch release\n\nSee [CHANGELOG](CHANGELOG.md) for patch details.\n\n---\n\n## ✨ What's New in v1.0.0\n\n**Session-Level Rollback + Production Readiness**\n\n- ✅ **Session-level rollback**: Undo an entire agent run in one click\n  - Atomic all-or-nothing semantics\n  - Restores files from snapshots\n  - Validates reversibility before executing\n- ✅ **Approval routing**: Route pending actions to specific teammates\n- ✅ **Escalation management**: Automatic escalation of stale approvals\n- ✅ **Risk assessment**: AI-powered risk scoring for every action\n- ✅ **Predictive analytics**: Trend analysis and forecasting dashboard\n- ✅ **Persistent policies**: Policies saved across sessions\n\n**What works**:\n- ✅ Policy enforcement (blocked/allowed/pending)\n- ✅ Action logging and dashboard\n- ✅ Single-action rollback\n- ✅ Session-level rollback (atomic)\n- ✅ Approval workflows and team routing\n- ✅ Escalation rules and notifications\n- ✅ Slack integration\n- ✅ Email notifications (SMTP)\n- ✅ Multi-project support\n- ✅ Windows, macOS, and Linux support\n\n**Known gaps** (see [CHANGELOG](CHANGELOG.md)):\n- ⚠️ REST API endpoints not integration-tested\n- ⚠️ Database layer not fully covered by unit tests\n- ⚠️ Production readiness: 2-4 weeks stabilization needed\n\nSee [CHANGELOG](CHANGELOG.md) for complete details.\n\n---\n\n**Control what AI agents can do in your codebase.**\n\nWaymark sits between your team and any AI agent.\nEvery file action is intercepted, logged, and checked\nagainst your policies before it executes.\nDangerous commands are blocked. Sensitive paths\nrequire human approval. Everything is reversible.\n\n---\n\n## The Problem\n\nAI agents like Claude Code are powerful.\nThey can also write to your .env, run rm -rf,\nor modify your database schema without asking.\n\nYou find out after it happens.\n\n## The Solution\n\nWaymark intercepts every action before it runs:\n\n| Agent tries to...          | Waymark does...                        |\n|----------------------------|----------------------------------------|\n| Write to .env              | Blocks it instantly. Logged.           |\n| Run rm -rf                 | Blocks it instantly. Logged.           |\n| Pipe curl to bash          | Blocks it instantly. Logged.           |\n| Modify src/db/schema.ts    | Holds it. Asks for your approval.      |\n| Write to src/              | Allows it. Logged with full rollback.  |\n| Read any file              | Logged with path and content snapshot. |\n\n---\n\n## Install\n\n```bash\ncd your-project\nnpx @way_marks/cli init\nnpx @way_marks/cli start\n```\n\nRestart Claude Code. Done.\nWaymark is now active in this project.\n\n---\n\n## How It Works\n\n```\nYour Prompt\n    ↓\nClaude Code\n    ↓\nWaymark MCP Server  ← intercepts here\n    ↓\nPolicy Engine\n    ↓\nallowed  → executes + logged\nblocked  → stopped + logged\npending  → held + approval required\n    ↓\nDashboard: http://localhost:\u003cport\u003e\n```\n\n---\n\n## Dashboard\n\nOpen **[http://localhost:\\\u003cport\\\u003e](http://localhost:47000)** after running\n`npx @way_marks/cli start`.\n\n- **Project name shown in header** — dashboard title displays\n  the active project automatically (e.g. \"waymark — my-app\")\n- See every agent action in real time\n- Approve or reject pending actions\n- Roll back any write with one click\n- Filter by allowed / blocked / pending\n\n---\n\n## Configuration\n\nEdit `waymark.config.json` in your project root:\n\n```json\n{\n  \"policies\": {\n    \"allowedPaths\": [\n      \"./src/**\",\n      \"./data/**\",\n      \"./README.md\"\n    ],\n    \"blockedPaths\": [\n      \"./.env\",\n      \"./.env.*\",\n      \"./package-lock.json\",\n      \"/etc/**\"\n    ],\n    \"blockedCommands\": [\n      \"rm -rf\",\n      \"DROP TABLE\",\n      \"regex:\\\\|\\\\s*bash\",\n      \"regex:\\\\$\\\\(curl\"\n    ],\n    \"requireApproval\": [\n      \"./src/db/**\",\n      \"./waymark.config.json\"\n    ]\n  }\n}\n```\n\n### Policy Rules\n\n**allowedPaths** — Agent can read and write these.\nSupports glob patterns.\n\n**blockedPaths** — Agent can never touch these.\nTakes priority over allowedPaths.\n\n**blockedCommands** — Bash commands containing\nthese strings are blocked. Prefix with `regex:`\nfor pattern matching.\n\n**requireApproval** — Actions on these paths are\nheld until a human approves from the dashboard.\n\n---\n\n## CLI Commands\n\n```bash\nnpx @way_marks/cli init    # Set up Waymark in current project\nnpx @way_marks/cli start   # Start dashboard + MCP server (background)\nnpx @way_marks/cli stop    # Stop the running servers\nnpx @way_marks/cli status  # Check if server is running\nnpx @way_marks/cli logs    # View recent actions in terminal\nnpx @way_marks/cli logs --pending   # Show only pending actions\nnpx @way_marks/cli logs --blocked   # Show only blocked actions\n```\n\n---\n\n## Slack Notifications\n\nGet notified when an agent action needs approval:\n\n```bash\n# Add to .env in your project\nWAYMARK_SLACK_WEBHOOK_URL=https://hooks.slack.com/...\nWAYMARK_SLACK_CHANNEL=#engineering\nWAYMARK_BASE_URL=http://localhost:47000\n```\n\nCreate a Slack webhook at:\napi.slack.com/apps → Incoming Webhooks\n\n---\n\n## Works With\n\n- **Claude Code** — native MCP integration, all features\n- **Claude Desktop** — native MCP integration, all features\n- **GitHub Copilot CLI** — now first-class, identical to Claude. `waymark init` auto-registers Waymark in `~/.copilot/mcp-config.json` and generates `COPILOT.md`. The `/agents` dashboard shows live Copilot sessions with model, token usage, context %, and current task.\n- **Any MCP-compatible agent** — register the Waymark MCP server in your agent config\n- More integrations coming (see [Platform Guide](../docs/README_PLATFORMS.md))\n\n---\n\n## Requirements\n\n- Node.js 18 or higher\n- Claude Code (for MCP integration)\n- macOS, Linux, or Windows\n\n---\n\n## Roadmap\n\n- [ ] CLI agent wrapping\n  (waymark run \u003cany-agent-command\u003e)\n- [ ] Proxy mode\n  (drop-in for any OpenAI-compatible agent)\n- [ ] REST API integration tests\n  (comprehensive endpoint coverage)\n\n---\n\n## Contributing\n\nWaymark is MIT licensed and open to contributions.\n\n1. Fork the repo\n2. Create a feature branch\n3. Open a pull request\n\nPlease open an issue before starting large changes.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\nBuilt for developers who want to use AI agents\nseriously — without giving them unsupervised\naccess to production systems.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaymarks%2Fwaymark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaymarks%2Fwaymark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaymarks%2Fwaymark/lists"}