{"id":48644045,"url":"https://github.com/bookedsolidtech/reagent","last_synced_at":"2026-04-16T02:00:52.790Z","repository":{"id":350266550,"uuid":"1205519184","full_name":"bookedsolidtech/reagent","owner":"bookedsolidtech","description":"Zero-trust agentic infrastructure — safety hooks, behavioral policies, kill switches, and graduated autonomy for AI-assisted development with Claude Code and Cursor. npx @bookedsolid/reagent init","archived":false,"fork":false,"pushed_at":"2026-04-14T23:51:32.000Z","size":1170,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"staging","last_synced_at":"2026-04-15T01:42:08.931Z","etag":null,"topics":["agentic","ai-agents","ai-governance","ai-safety","anthropic","automation","booked-solid","claude","claude-code","cli","cursor","developer-tools","devops","git-hooks","husky","mcp","nodejs","secret-scanning","security","zero-trust"],"latest_commit_sha":null,"homepage":"https://bookedsolid.tech","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/bookedsolidtech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":"THREAT_MODEL.md","audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-09T03:16:00.000Z","updated_at":"2026-04-14T23:46:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bookedsolidtech/reagent","commit_stats":null,"previous_names":["bookedsolidtech/reagent"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/bookedsolidtech/reagent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Freagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Freagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Freagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Freagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bookedsolidtech","download_url":"https://codeload.github.com/bookedsolidtech/reagent/tar.gz/refs/heads/staging","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Freagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31867712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"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":["agentic","ai-agents","ai-governance","ai-safety","anthropic","automation","booked-solid","claude","claude-code","cli","cursor","developer-tools","devops","git-hooks","husky","mcp","nodejs","secret-scanning","security","zero-trust"],"created_at":"2026-04-10T00:13:03.793Z","updated_at":"2026-04-16T02:00:52.782Z","avatar_url":"https://github.com/bookedsolidtech.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @bookedsolid/reagent\n\nGovernance layer for Claude Code — policy enforcement, hook-based safety gates, and audit logging for AI-assisted projects.\n\nreagent enforces policy, prevents dangerous operations, and audits AI agent activity in Claude Code projects. One command (`reagent init`) installs 23 safety hooks and a full engineering team of AI specialists into your project. Every tool call — from every AI agent — is governed by your `policy.yaml`. It's Claude Code + accountability.\n\n## What it is\n\nreagent is an MCP server. You declare it in `.mcp.json` and Claude Code spawns it via\nstdio transport when a session starts. Every tool call — whether to reagent's own native\ntools or to any downstream MCP server you've configured — flows through a 12-layer\nmiddleware chain before it executes.\n\nreagent can also proxy tool calls to other MCP servers. Instead of listing your\nfilesystem server, GitHub server, and other tools directly in `.mcp.json`, you list them\nin `.reagent/gateway.yaml`. reagent connects to each one on startup, discovers their\ntools, and re-registers those tools on itself under namespaced names. Every proxied call\ngoes through the same middleware chain as native tool calls — policy, redaction, audit,\nrate-limiting, and the kill switch all apply.\n\n`reagent init` scaffolds a project with the full safety infrastructure: Claude Code hooks,\n`policy.yaml`, `gateway.yaml`, agent team files, cursor rules, and quality gates. Profiles\nlet you start from a base configuration (client-engagement or bst-internal) and layer in\ntech-stack-specific hooks (astro, nextjs, lit-wc, drupal).\n\nThe kill switch is a file: `.reagent/HALT`. When it exists, every hook and every tool call\nreturns an immediate denial with the reason from the file. `reagent freeze` creates it;\n`reagent unfreeze` removes it.\n\n## Quick Start\n\n```bash\nnpm install -g @bookedsolid/reagent\ncd your-project\nreagent init\n```\n\nThat's it. `reagent init` writes `.mcp.json` to your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"reagent\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"reagent\", \"serve\"]\n    }\n  }\n}\n```\n\nRestart Claude Code. It will pick up `.mcp.json` and spawn `reagent serve` automatically.\nreagent loads your `.reagent/policy.yaml` and `.reagent/gateway.yaml`, connects to any\ndownstream servers, and starts listening on stdio.\n\nTo verify the installation:\n\n```bash\nreagent check\n```\n\n## How it works\n\n```\nClaude Code ──stdio──▶ reagent serve (MCP server)\n                            │\n                            ├─ native tools: task_create, task_list, task_update, ...\n                            │\n                            └─ proxied tools from .reagent/gateway.yaml\n                                 └─ every tool call through the middleware chain\n```\n\n### The middleware chain\n\nEvery tool call — whether native or proxied — passes through this chain in order:\n\n```\naudit → session → kill-switch → tier → policy → blocked-paths →\nrate-limit → circuit-breaker → redact → injection → result-size-cap → execute\n```\n\n**audit** — Outermost layer. Records every invocation as a hash-chained JSONL entry\nin `.reagent/audit.jsonl` before anything else runs. Denials are logged too. The chain\nintegrity means no entry can be modified without invalidating all subsequent hashes.\n\n**session** — Associates the call with a session UUID. Sessions are in-memory for the\nlifetime of the `reagent serve` process.\n\n**kill-switch** — Reads `.reagent/HALT` on every call. If the file exists, the call is\nimmediately denied with the reason from the file. No exceptions.\n\n**tier** — Classifies the tool call as `read`, `write`, or `destructive` using the tool\nname and the tier map from `gateway.yaml` tool overrides. Tier determines which autonomy\nlevels can call it.\n\n**policy** — Enforces `autonomy_level` from `policy.yaml`. L0 allows reads only. L1\nallows reads and writes. L2 allows reads, writes, and PR creation. L3 allows everything.\nA tool at a tier above the configured level is denied.\n\n**blocked-paths** — Scans tool arguments for references to paths listed in\n`policy.yaml:blocked_paths`. If an argument contains a blocked path, the call is denied.\nThis protects `.reagent/`, `.github/workflows/`, `.env`, and whatever else you configure.\n\n**rate-limit** — Enforces per-server `calls_per_minute` limits from `gateway.yaml`.\nCalls that exceed the limit are denied. Legitimate calls don't burn rate budget for\ncalls already denied by earlier middleware.\n\n**circuit-breaker** — Tracks downstream server failures. After a configurable threshold\nof consecutive errors, the breaker opens and calls to that server are denied until it\nresets. Prevents cascading failures when a downstream MCP server is unhealthy.\n\n**redact** — Scans tool arguments and results for secrets: AWS keys, GitHub tokens,\nAPI keys, PEM private keys, Discord tokens, Stripe keys, generic bearer tokens, and\nmore. Matching values are replaced with `[REDACTED]` before they reach the model or\nthe downstream server.\n\n**injection** — Scans tool results from downstream servers for prompt injection patterns.\nIn `block` mode (default), detected injection attempts are denied. In `warn` mode, they\nare flagged in the audit log but allowed through.\n\n**result-size-cap** — Caps tool results at `gateway.options.max_result_size_kb` (default:\n1 MB). Oversized responses are truncated with a note. Prevents large downstream responses\nfrom bloating context.\n\n**execute** — The innermost layer. Calls the actual tool. For native tools, runs the\nhandler directly. For proxied tools, forwards the call to the downstream MCP server via\nits stdio transport.\n\n### Policy and autonomy levels\n\n`reagent init` writes `.reagent/policy.yaml` to your project:\n\n```yaml\nversion: '1'\nprofile: 'client-engagement'\ninstalled_by: 'reagent@0.10.0'\ninstalled_at: '2026-04-01T00:00:00.000Z'\n\n# Autonomy levels:\n#   L0 — Read-only; every write requires explicit user approval\n#   L1 — Writes allowed to non-blocked paths; destructive operations blocked\n#   L2 — Writes + PR creation allowed; destructive tier blocked\n#   L3 — All writes allowed; advisory on anomalous patterns\nautonomy_level: L2\nmax_autonomy_level: L3\n\n# Human must approve any autonomy level increase\npromotion_requires_human_approval: true\n\n# Block AI attribution in commits and PRs\nblock_ai_attribution: true\n\n# Paths hooks and agents must never modify\nblocked_paths:\n  - '.reagent/'\n  - '.github/workflows/'\n  - '.env'\n  - '.env.*'\n\n# Optional: Discord webhook for halt/promote notifications\nnotification_channel: ''\n\nquality_gates:\n  push_review: false\n```\n\nThe `autonomy_level` controls what tier of tools an agent can call. Raise it to give\nan agent more authority; lower it (or freeze) to restrict it. `max_autonomy_level` is a\nceiling set by a human — no agent instruction can escalate beyond it.\n\n`block_ai_attribution: true` causes the `commit-msg` hook to reject commits that contain\n`Co-Authored-By` lines with AI names, `Generated with [Tool]` footers, or similar\nstructural attribution markers. Casual mentions of AI tools in commit messages are\nstill allowed.\n\n### The kill switch\n\nCreate a HALT file to immediately block all agent operations:\n\n```bash\nreagent freeze --reason \"releasing to production — no agent changes\"\n```\n\nThis creates `.reagent/HALT` with your reason as the content. Every hook checks for this\nfile at the top of its script. Every tool call checks it at the kill-switch middleware\nlayer. Nothing gets through.\n\nRemove it when you're ready to resume:\n\n```bash\nreagent unfreeze\n```\n\nThe HALT file is a plain text file in your project. You can also create or delete it\nmanually, or add it to your release process as a safety gate.\n\n## Connecting additional MCP servers\n\nInstead of listing servers directly in `.mcp.json` (which would bypass reagent's\nmiddleware), add them to `.reagent/gateway.yaml`:\n\n```yaml\nversion: '1'\n\nservers:\n  filesystem:\n    command: npx\n    args: ['@modelcontextprotocol/server-filesystem', '/home/user/projects']\n\n  github:\n    command: npx\n    args: ['@modelcontextprotocol/server-github']\n    env:\n      GITHUB_TOKEN: '${GITHUB_PERSONAL_ACCESS_TOKEN}'\n\n  postgres:\n    command: npx\n    args: ['@modelcontextprotocol/server-postgres', '${DATABASE_URL}']\n    calls_per_minute: 60\n    max_concurrent_calls: 5\n    tool_overrides:\n      execute_query:\n        tier: destructive\n\ngateway:\n  max_result_size_kb: 512\n```\n\nWhen `reagent serve` starts, it connects to each server, discovers its tools, and\nre-registers them on the reagent MCP server with namespaced names\n(e.g., `filesystem__read_file`, `github__create_issue`). Every call to a proxied tool\ngoes through the full middleware chain before forwarding.\n\n**`tool_overrides`** let you reclassify a tool's tier or block it entirely:\n\n```yaml\ntool_overrides:\n  execute_query:\n    tier: destructive # Treat this tool as destructive regardless of its name\n  drop_table:\n    blocked: true # Always deny calls to this tool, regardless of autonomy level\n```\n\n**`calls_per_minute`** and **`max_concurrent_calls`** are per-server rate limits enforced\nby the rate-limit middleware.\n\n`${ENV_VAR}` references in `env` blocks are resolved at startup from the environment\nwhere `reagent serve` runs.\n\n## Profiles\n\n`reagent init` accepts a `--profile` flag to install a pre-built configuration:\n\n```bash\n# Base profiles (full setup — install one or the other)\nreagent init                                    # client-engagement (default)\nreagent init --profile bst-internal            # BST internal projects\n\n# Tech stack profiles (add to a base profile)\nreagent init --profile lit-wc                  # Lit/Web Components hooks\nreagent init --profile astro                   # Astro framework hooks\nreagent init --profile nextjs                  # Next.js App Router hooks\nreagent init --profile drupal                  # Drupal CMS hooks\n```\n\nTech stack profiles compose on top of the `client-engagement` base by default. You can\nspecify a different base:\n\n```bash\nreagent init --profile lit-wc --base-profile bst-internal\n```\n\nThe `client-engagement` profile installs:\n\n- Claude Code hooks for dangerous bash interception, secret scanning, env file protection,\n  dependency auditing, commit review, push review, security disclosure gates, settings\n  protection, blocked path enforcement, changeset security, and architecture review\n- Cursor rules: no-hallucination, verify-before-act, attribution\n- `block_ai_attribution: true` in `policy.yaml`\n- `blocked_paths: ['.reagent/', '.github/workflows/', '.env', '.env.*']`\n- Quality gates: commit review (trivial threshold: 20 lines, significant: 200 lines),\n  push review, architecture advisory\n- PM layer enabled with max 50 open tasks\n\n## Hooks\n\nreagent installs 23 Claude Code hooks into `.claude/hooks/`. Every hook checks for\n`.reagent/HALT` at the top — if it exists, the hook returns exit code 2 (hard block)\nimmediately.\n\n**Pre-tool-use hooks (Bash matcher):**\n\n- `dangerous-bash-interceptor` — Blocks `rm -rf` with broad targets, `curl | bash`,\n  `chmod 777`, force-push to protected branches, and other high-risk bash patterns.\n  Uses a severity tiering system: HIGH blocks outright, MEDIUM warns.\n- `env-file-protection` — Prevents reads and writes to `.env`, `.env.*`, and other\n  secret-bearing files.\n- `dependency-audit-gate` — Intercepts `npm install`, `pnpm add`, and similar commands.\n  Verifies the package exists in the npm registry before allowing installation.\n- `commit-review-gate` — Before a `git commit`, checks the diff size. Significant\n  changes trigger a structured review request that the agent must satisfy.\n- `push-review-gate` — Before `git push`, performs a final quality gate check.\n- `security-disclosure-gate` — Intercepts `gh issue create` and similar commands. Blocks\n  public disclosure of security vulnerabilities; routes to the configured disclosure mode\n  (issues, security advisories, etc.).\n- `pr-issue-link-gate` — Requires every PR to reference a GitHub issue.\n- `attribution-advisory` — When `block_ai_attribution` is enabled, blocks `git commit`\n  and `gh pr create/edit` commands that include AI attribution markers in their content.\n\n**Pre-tool-use hooks (Write|Edit matcher):**\n\n- `secret-scanner` — Scans file content being written or edited for secrets: AWS keys,\n  GitHub tokens, PEM private keys, Discord tokens, Stripe keys, and more. Blocks the\n  write if a secret is detected.\n- `settings-protection` — Prevents writes to `.claude/settings.json` that would disable\n  hooks or add risky permissions. Allows agent writes to task files and non-security\n  operational files.\n- `blocked-paths-enforcer` — Enforces `blocked_paths` from `policy.yaml` for file\n  writes and edits. The middleware chain enforces this for tool calls; this hook enforces\n  it for direct file operations.\n- `changeset-security-gate` — Validates changeset files before they are written. Prevents\n  injection of malicious content into the changeset workflow.\n\n**Post-tool-use hooks (Write|Edit matcher):**\n\n- `architecture-review-gate` — After significant file edits, checks the change against\n  the project's architecture plan and flags deviations.\n\n**Additional hooks installed by tech stack profiles:**\n\n- `commit-msg` (husky) — Enforces commit message format and rejects AI attribution\n  markers when `block_ai_attribution: true`.\n- `pre-commit` (husky) — Runs quality checks before each commit.\n- `pre-push` (husky) — Runs the full preflight before push.\n\nThe hooks in `.claude/hooks/` use a shared `_lib/` directory for common functions\nincluding HALT checking, policy loading, and output formatting.\n\n## Task management\n\nreagent includes a lightweight project management layer with native MCP tools. Tasks\nare stored as append-only JSONL in `.reagent/tasks.jsonl`. Each line is a JSON event\n(created, started, completed, blocked, cancelled) with a task ID in `T-NNN` format.\n\n**Native MCP tools:**\n\n- `task_create` — Create a task with title, description, urgency (critical/normal/low),\n  phase, milestone, assignee, and optional parent task ID.\n- `task_update` — Update a task's status (started, completed, blocked, cancelled) and\n  fields. When a task is completed and has a `github_issue` reference, the linked issue\n  is closed automatically.\n- `task_list` — List tasks with optional filters for status, urgency, and phase.\n- `task_get` — Get a single task by ID.\n- `task_delete` — Soft-delete a task (appends a `cancelled` event).\n- `task_sync_github` — Sync local tasks to GitHub issues (requires `gh` CLI).\n- `repo_scaffold` — Scaffold GitHub repo metadata: description, topics, labels\n  (`reagent:task`, `reagent:critical`, `reagent:blocked`), and milestones.\n- `project_sync` — Sync tasks with GitHub issues to a GitHub Projects v2 board.\n- `discord_notify` — Send a notification to a configured Discord channel\n  (alerts, releases, tasks, dev). Requires `discord_ops` in `gateway.yaml` and\n  `DISCORD_BOT_TOKEN` in the environment.\n\nAll native tools go through the same middleware chain as proxied tools — the kill switch,\npolicy, blocked paths, redaction, and audit all apply.\n\nThe `/tasks` slash command and the `pm-status` agent provide a product-owner view of\nthe task board from within Claude Code conversations.\n\n**Example `tasks.jsonl` entries:**\n\n```jsonl\n{\"id\":\"T-001\",\"type\":\"created\",\"title\":\"Implement login flow\",\"urgency\":\"critical\",\"timestamp\":\"2026-04-01T10:00:00.000Z\"}\n{\"id\":\"T-001\",\"type\":\"started\",\"title\":\"Implement login flow\",\"assignee\":\"frontend-specialist\",\"timestamp\":\"2026-04-01T10:05:00.000Z\"}\n{\"id\":\"T-001\",\"type\":\"completed\",\"title\":\"Implement login flow\",\"commit_refs\":[\"abc1234\"],\"pr_ref\":\"#42\",\"timestamp\":\"2026-04-01T14:30:00.000Z\"}\n```\n\n## Obsidian vault integration\n\nreagent can integrate with [Obsidian](https://obsidian.md) vaults for project knowledge\nmanagement. Session journaling, task sync, knowledge extraction before context compaction,\nand vault health monitoring — all driven by hooks and the CLI.\n\nThe integration is **opt-in by default**. Nothing Obsidian-related activates unless you\nexplicitly configure it. Every Obsidian operation is fail-silent: if the CLI is missing,\nthe vault path is wrong, or a sync target is disabled, reagent exits cleanly with no\nerrors and no blocked operations.\n\n### Prerequisites\n\n- **Obsidian CLI** installed at `/usr/local/bin/obsidian`\n- An Obsidian vault directory for each project you want to integrate\n\n### Setup\n\nEnable the integration during init:\n\n```bash\nreagent init --obsidian --vault-path /path/to/vault\n```\n\nOr set the vault path via environment variable:\n\n```bash\nexport REAGENT_OBSIDIAN_VAULT=/path/to/vault\n```\n\nBoth methods write an `obsidian_vault` block to `.reagent/gateway.yaml`:\n\n```yaml\nobsidian_vault:\n  enabled: true\n  vault_path: '/path/to/vault'\n  vault_name: 'MyProject'\n  paths:\n    root: 'Projects/Reagent'\n    kanban: 'Projects/Reagent/Kanban.md'\n    sources: 'Projects/Reagent/Sources'\n    wiki: 'Projects/Reagent/Auto'\n    tasks: 'Tasks'\n    sessions: 'Wiki/Sessions'\n  sync:\n    kanban: false\n    context_dump: false\n    wiki_refresh: false\n    journal: true # Tier 1 — on by default when integration is enabled\n    precompact: false # Tier 2 — opt-in\n    tasks: true # Tier 3 — on by default when integration is enabled\n  precompact:\n    engine: 'claude' # 'claude' or 'ollama'\n    model: null # null = use default model for the engine\n```\n\nVault path resolution order:\n\n1. `REAGENT_OBSIDIAN_VAULT` environment variable (absolute path)\n2. `obsidian_vault.vault_path` in `gateway.yaml`\n3. Not set — integration disabled\n\n### Three-tier hook architecture\n\nObsidian sync is organized into three tiers, each backed by a dedicated Claude Code hook.\nEach tier operates independently and can be enabled or disabled individually.\n\n**Tier 1 — Session Journal** (`reagent-obsidian-journal.sh`)\n\nFires when a Claude Code session ends. Appends a session summary to the daily note in\nyour vault via `obsidian daily:append`. The summary includes the project name, a session\nidentifier, timestamp, and task state counts (completed, in progress, blocked, backlog)\npulled from `.reagent/tasks.jsonl`.\n\nEnable: `sync.journal: true` (default when integration is enabled).\n\n**Tier 2 — PreCompact Knowledge Extraction** (`reagent-obsidian-precompact.sh`)\n\nFires before Claude Code compacts context. Creates a session knowledge note in\n`Wiki/Sessions/` (or your configured `paths.sessions` directory) with frontmatter\ntagging the project, date, session ID, and extraction engine.\n\nThis tier is a stub — the knowledge extraction engine is not yet fully implemented.\nThe hook creates a structured placeholder note with sections for Decisions, Discoveries,\nand Open Questions. The `precompact.engine` field (`claude` or `ollama`) determines which\nbackend will perform extraction when the implementation is complete.\n\nEnable: `sync.precompact: true` (disabled by default).\n\n**Tier 3 — Task Materialization** (`reagent-obsidian-tasks.sh`)\n\nFires after `task_create` and `task_update` MCP tool calls. Materializes each task as an\nindividual Obsidian note in the `Tasks/` directory with typed frontmatter:\n\n```yaml\n---\nreagent_managed: true\ntask_id: T-001\nproject: my-project\nstatus: started\nurgency: critical\nassignee: frontend-specialist\n---\n```\n\nSync is one-way: JSONL to Obsidian. The hook extracts the task ID from the tool result,\nreads the latest event for that task from `.reagent/tasks.jsonl`, and creates or overwrites\nthe corresponding note.\n\nEnable: `sync.tasks: true` (default when integration is enabled).\n\n### CLI commands\n\n```\nreagent obsidian sync [--target kanban|context|wiki|tasks] [--dry-run]\n  Sync enabled targets to the Obsidian vault. Without --target, syncs all\n  enabled targets. --dry-run previews what would be written.\n\nreagent obsidian status\n  Show current Obsidian configuration: vault path, CLI availability,\n  configured paths, and which sync targets are enabled or disabled.\n\nreagent obsidian health\n  Show vault health metrics: orphan notes, unresolved links, and dead ends.\n  Requires vault_name set in gateway.yaml and the Obsidian CLI installed.\n\nreagent obsidian journal\n  Manually trigger a session journal entry in the daily note. Useful for\n  ad-hoc journaling outside of the automatic session-end hook.\n```\n\n### Vault-per-project mapping\n\nEach project maps to its own Obsidian vault. The vault path is resolved per-project from\nthat project's `.reagent/gateway.yaml` or `REAGENT_OBSIDIAN_VAULT` environment variable.\nThere is no global vault registry — each project is self-contained.\n\n## CLI reference\n\n```\nreagent init [options]\n  --profile \u003cname\u003e      Profile to install (default: client-engagement)\n  --base-profile \u003cname\u003e Base profile to use with a tech stack profile\n  --dry-run             Preview what would be installed without writing files\n  --github              Configure GitHub integration in gateway.yaml\n  --discord             Configure Discord notifications in gateway.yaml\n  --guild-id \u003cid\u003e       Discord guild ID\n  --alerts-channel \u003cid\u003e Discord channel ID for security alerts\n  --tasks-channel \u003cid\u003e  Discord channel ID for task events\n  --releases-channel    Discord channel ID for release events\n  --dev-channel \u003cid\u003e    Discord channel ID for dev activity\n  --obsidian            Enable Obsidian vault integration in gateway.yaml\n  --vault-path \u003cpath\u003e   Absolute path to the Obsidian vault directory\n\nreagent serve\n  Starts the MCP server on stdio. Loaded by Claude Code via .mcp.json.\n  Reads .reagent/policy.yaml and .reagent/gateway.yaml from the current directory.\n\nreagent check\n  Checks which reagent components are installed in the current project.\n\nreagent freeze --reason \"\u003creason\u003e\"\n  Creates .reagent/HALT with the provided reason. Immediately blocks all\n  agent tool calls and hook-guarded bash commands.\n\nreagent unfreeze\n  Removes .reagent/HALT. Resumes agent operations.\n\nreagent catalyze [targetDir]\n  --plan    Analyze project stack and generate a gap analysis report (default)\n  --audit   Compare current state against the last plan and show drift\n  --dry-run Print analysis without writing files\n\nreagent upgrade [--dry-run] [--clean-blocked-paths]\n  Re-syncs installed hooks from the current package version and updates the\n  version stamp in policy.yaml. Run after upgrading the reagent package.\n  --clean-blocked-paths replaces the blanket '.reagent/' blocked path with\n  granular entries, allowing agents to write to operational files (tasks,\n  review cache) while keeping policy and audit files protected.\n\nreagent cache \u003cset|get|del\u003e \u003ckey\u003e [value]\n  Manages the review cache used by commit-review-gate and push-review-gate.\n\nreagent obsidian \u003csync|status|health|journal\u003e\n  Obsidian vault integration commands. See the Obsidian vault integration\n  section above for full documentation.\n```\n\n## Configuration\n\n### `.reagent/policy.yaml`\n\nThe primary policy file. Committed to the repo. Describes the autonomy level, blocked\npaths, and quality gate settings for this project.\n\n```yaml\nversion: '1'\nprofile: 'client-engagement'\nautonomy_level: L2 # L0 | L1 | L2 | L3\nmax_autonomy_level: L3 # ceiling — agents cannot escalate beyond this\npromotion_requires_human_approval: true\nblock_ai_attribution: true # reject AI attribution in commits and PRs\nblocked_paths:\n  - '.reagent/'\n  - '.github/workflows/'\n  - '.env'\n  - '.env.*'\nnotification_channel: '' # Discord webhook for halt/promote events\nquality_gates:\n  push_review: false\n```\n\n### `.reagent/gateway.yaml`\n\nDeclares downstream MCP servers and global gateway options.\n\n```yaml\nversion: '1'\n\nservers:\n  filesystem:\n    command: npx\n    args: ['@modelcontextprotocol/server-filesystem', '/path/to/project']\n\n  github:\n    command: npx\n    args: ['@modelcontextprotocol/server-github']\n    env:\n      GITHUB_TOKEN: '${GITHUB_PERSONAL_ACCESS_TOKEN}'\n    calls_per_minute: 120\n    tool_overrides:\n      delete_repository:\n        blocked: true\n\ngateway:\n  max_result_size_kb: 512\n```\n\nFields per server entry:\n\n| Field                  | Description                                         |\n| ---------------------- | --------------------------------------------------- |\n| `command`              | The executable to spawn                             |\n| `args`                 | Arguments passed to the command                     |\n| `env`                  | Environment variables (supports `${VAR}` expansion) |\n| `tool_overrides`       | Per-tool tier overrides or hard blocks              |\n| `calls_per_minute`     | Rate limit for this server (0 = unlimited)          |\n| `max_concurrent_calls` | Concurrency limit (0 = unlimited)                   |\n\n### `~/.reagent/daemon.yaml`\n\nRemoved. reagent no longer uses a daemon or process supervisor. Claude Code owns the\n`reagent serve` process lifecycle via stdio transport in `.mcp.json`.\n\n## Contributing / Development\n\n```bash\npnpm install\npnpm build          # compile TypeScript to dist/\npnpm tsc --noEmit   # type-check without emitting\npnpm test           # run all tests with vitest\npnpm preflight      # full quality gate (build + typecheck + test + lint + format)\n```\n\nChangesets workflow:\n\n```bash\npnpm changeset          # create a new changeset\npnpm changeset:version  # bump versions and update CHANGELOG\npnpm changeset:publish  # publish to npm\n```\n\nThere is no Rust code in this project. The `daemon/` directory has been removed. The\nproject is pure TypeScript targeting Node.js 22+, compiled to ESM.\n\nThe test suite lives in `src/__tests__/` and covers the middleware chain, all hooks,\nthe CLI init flow, config loaders, the task store, GitHub and Discord integrations,\nand an end-to-end smoke test that spawns a real `reagent serve` process.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbookedsolidtech%2Freagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbookedsolidtech%2Freagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbookedsolidtech%2Freagent/lists"}