{"id":50655292,"url":"https://github.com/ra-yavuz/vigil","last_synced_at":"2026-06-07T23:30:38.032Z","repository":{"id":360173315,"uuid":"1249000330","full_name":"ra-yavuz/vigil","owner":"ra-yavuz","description":"How to build an always-on, autonomous AI operations assistant, and the doctrine + hooks pattern that keeps an auto-approved agent diligent unattended.","archived":false,"fork":false,"pushed_at":"2026-05-25T09:28:06.000Z","size":90,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T11:13:54.251Z","etag":null,"topics":["agent-architecture","agent-guardrails","ai-agent","ai-operations","autonomous-agents","claude-code","claude-code-hooks","llm-ops","mcp","reference-architecture"],"latest_commit_sha":null,"homepage":"https://ra-yavuz.github.io/vigil/","language":null,"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/ra-yavuz.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-05-25T08:51:15.000Z","updated_at":"2026-05-25T09:28:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ra-yavuz/vigil","commit_stats":null,"previous_names":["ra-yavuz/vigil"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ra-yavuz/vigil","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ra-yavuz%2Fvigil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ra-yavuz%2Fvigil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ra-yavuz%2Fvigil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ra-yavuz%2Fvigil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ra-yavuz","download_url":"https://codeload.github.com/ra-yavuz/vigil/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ra-yavuz%2Fvigil/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34042554,"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-07T02:00:07.652Z","response_time":124,"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-architecture","agent-guardrails","ai-agent","ai-operations","autonomous-agents","claude-code","claude-code-hooks","llm-ops","mcp","reference-architecture"],"created_at":"2026-06-07T23:30:37.088Z","updated_at":"2026-06-07T23:30:38.013Z","avatar_url":"https://github.com/ra-yavuz.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# vigil\n\n**How to build an always-on, autonomous AI operations assistant - and how to make it\ndiligent enough to leave running unattended.**\n\n`vigil` is a documentation project. It describes, in enough depth to recreate from scratch,\nthe architecture of a persistent \"operator\" AI: one that lives in a container, talks to its\nowner over normal chat channels (WhatsApp, Signal, email), and can autonomously write and\nrun code, install packages, schedule tasks, and host the things it builds.\n\nThe part most write-ups skip - and the part `vigil` puts front and centre - is **how an\nagent that acts without a human approving each step stays honest.** That is the\n**autonomous-diligence pattern**: a doctrine file plus two Claude Code hooks that re-assert\nan engineering standard on every single turn, at near-zero cost, with no human present.\n\nThere is no daemon to install here and no `.deb` to ship. This repo is the spec and the\nexample files. Read it, adapt it, build your own.\n\n## What's inside\n\n| Document | What it covers |\n|---|---|\n| **[docs/AUTONOMOUS-DILIGENCE.md](docs/AUTONOMOUS-DILIGENCE.md)** | The doctrine + hooks pattern that makes autonomy safe to leave running. **Start here.** |\n| **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** | The full operator architecture: persistent agent subprocess, supervisor, transport split, channel multiplexers, voice/media (free local speech-to-text), encrypted searchable email DB, cost monitoring + dashboard, MCP tools, persistence, scheduling, resilience. Ends with a concrete **[implementation plan](docs/ARCHITECTURE.md#9-implementation-plan-prerequisites-and-a-path-to-running)** (prerequisites and bring-up order). |\n| **[examples/](examples/)** | Drop-in starting points: a generic `doctrine.md`, the two hook scripts, and a `settings.json` fragment. |\n\n### Before you build the WhatsApp channel, read this\n\nLinking a headless WhatsApp Web session hands the running agent full read and send access to\nthat account. **Use a dedicated phone number you provision for the assistant, never your\npersonal WhatsApp.** WhatsApp does not sanction unofficial automation and can ban the\naccount; a dedicated number means a ban costs you the assistant, not your personal messaging.\nThe multiplexer enforces *who the agent may talk to* in code, both directions: an\n**allowlist** drops inbound messages from anyone not explicitly permitted (so strangers\ncannot even prompt the agent), and an **outreach-thread** rule stops the agent cold-messaging\narbitrary or model-invented numbers. Both gates and the QR-linking page are detailed in the\n[architecture doc](docs/ARCHITECTURE.md#34-the-whatsapp-multiplexer-separate-container).\n\n## The idea in one paragraph\n\nRun a coding-agent CLI (the reference uses the Claude CLI) as a long-lived subprocess in a\ncontainer, piping messages in and responses out as JSON. Wrap it in a **supervisor** that\nhandles persistence, health, scheduling, and session rotation, and split all the I/O into a\nseparate **transport** process so the chat layer can restart without killing the brain.\nGive the AI a real Linux box with tools rather than a fixed API, and expose extra\ncapabilities as small MCP servers. Then - and this is the load-bearing part - hold the agent\nto an **operating doctrine** it reads at session start, kept fresh by a minimal per-turn\n`UserPromptSubmit` reminder that points back at it, so an auto-approved agent keeps verifying\nbefore it acts, refuses workarounds, and never claims \"done\" without a real run. The\narchitecture makes it reliable; the doctrine makes it diligent.\n\n## The autonomous-diligence pattern, in brief\n\nThree pieces, a few kilobytes total:\n\n1. **`doctrine.md`** - the full operating rules, written once (verify before acting, no\n   workarounds, respect specs, don't claim completion you haven't verified, push back when\n   the request is wrong, minimise blast radius, when unsure ask or stop).\n2. **A `SessionStart` hook** - fires once per session, tells the agent to read the doctrine\n   in full. Cost: a few hundred characters once.\n3. **A `UserPromptSubmit` hook** - fires on *every* turn, re-states the non-negotiables and\n   asks the agent to print a **pre-response check** before any consequential reply. Cost:\n   ~1.5 KB per turn, negligible.\n\nWhy on every turn? Because over a long autonomous run, rules buried in a one-time system\nprompt drift, and the dangerous moments are individual actions. Re-asserting the discipline\nright before the agent acts - deterministically, with no model call - is what keeps a\ncapable, auto-approved agent reasoning like a diligent engineer instead of an eager one.\n\nFull write-up, including why a system prompt is not enough and how to adapt it:\n**[docs/AUTONOMOUS-DILIGENCE.md](docs/AUTONOMOUS-DILIGENCE.md)**.\n\n## What is verified vs. described\n\n- The **diligence layer** (doctrine + hooks) is documented from a working, verified setup;\n  the files in [`examples/`](examples/) are real, redacted copies that emit valid hook JSON.\n- The **operator architecture** in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) is presented\n  as a **reference architecture**: a design known to work in this shape, written so you can\n  build your own. Verify every flag, path, and API against current upstream docs before you\n  rely on it.\n\n## Who this is for\n\nDevelopers building their own always-on assistant, or anyone curious how such a system is\nput together and kept from going off the rails. It assumes comfort with containers, a shell,\nand a coding-agent CLI.\n\n## Disclaimer / no warranty\n\nThis repository is **documentation and example configuration**, provided **as is, without\nwarranty of any kind**, express or implied, including but not limited to merchantability,\nfitness for a particular purpose, and noninfringement.\n\nIt describes how to build a system that runs an AI agent with **auto-approved tool calls**\nand **broad shell, file, and network access**. Building or running such a system is\ninherently risky. By using anything in this repository you accept that:\n\n- **You alone are responsible** for anything an autonomous agent you build does, including\n  destructive, irreversible, or costly actions - up to and including data loss, leaked\n  credentials, unintended spending, and damage to systems you do not own.\n- The doctrine and hooks described here are a **behavioural guardrail, not a security\n  boundary.** They reduce careless mistakes; they do **not** sandbox the agent or prevent a\n  confused or adversarially-prompted agent from taking a bad action. Real containment is the\n  container/VM boundary and tightly scoped credentials - use those, and treat the doctrine\n  as defence in depth on top.\n- The author(s) and contributors are **not liable** for any harm, loss, or damages, however\n  caused, arising from following this documentation or running anything built from it.\n- Auto-approved permission modes remove the human from the loop on every action. Only run\n  such a configuration inside an isolated environment you fully control and can afford to\n  lose, on accounts and data you own.\n\nRead [docs/ARCHITECTURE.md, section 7 (Security)](docs/ARCHITECTURE.md#7-security-this-is-the-part-to-read-twice)\nbefore building anything. If you do not accept these terms, do not use this repository.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n## Author\n\n[Ramazan Yavuz](https://ra-yavuz.github.io/). Part of the public, open-source projects at\n[github.com/ra-yavuz](https://github.com/ra-yavuz), independent of any business work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fra-yavuz%2Fvigil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fra-yavuz%2Fvigil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fra-yavuz%2Fvigil/lists"}