{"id":50908007,"url":"https://github.com/nickzren/four-eyes","last_synced_at":"2026-06-16T07:02:30.828Z","repository":{"id":359387354,"uuid":"1245853673","full_name":"nickzren/four-eyes","owner":"nickzren","description":"Autonomous AI agents, independent AI review, human only when needed.","archived":false,"fork":false,"pushed_at":"2026-06-11T16:20:24.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T17:25:38.879Z","etag":null,"topics":["agent-orchestration","ai-agents","ai-safety","code-review","dual-control","four-eyes","human-in-the-loop","llm","multi-agent","workflow"],"latest_commit_sha":null,"homepage":"","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/nickzren.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-21T16:11:21.000Z","updated_at":"2026-06-11T16:20:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nickzren/four-eyes","commit_stats":null,"previous_names":["nickzren/four-eyes"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nickzren/four-eyes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzren%2Ffour-eyes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzren%2Ffour-eyes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzren%2Ffour-eyes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzren%2Ffour-eyes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickzren","download_url":"https://codeload.github.com/nickzren/four-eyes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzren%2Ffour-eyes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34393305,"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-16T02:00:06.860Z","response_time":126,"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-orchestration","ai-agents","ai-safety","code-review","dual-control","four-eyes","human-in-the-loop","llm","multi-agent","workflow"],"created_at":"2026-06-16T07:02:30.001Z","updated_at":"2026-06-16T07:02:30.821Z","avatar_url":"https://github.com/nickzren.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Four Eyes\n\nHuman-approved multi-agent review workflow.\n\nFour Eyes uses the four-eyes principle: high-stakes work should not proceed on one agent's judgment alone.\n\nFour Eyes helps you use AI agents without pretending they are fully autonomous. Agents can plan, review, and execute, but a human approves risky actions.\n\nUnlike role-heavy agent frameworks, Four Eyes asks AI reviewers to judge the same plan independently.\n\n## Shape\n\n- one orchestrator agent owns the plan and execution\n- two reviewer agents give independent feedback\n- one human approves risky actions\n- one issue or parent/child issue set tracks gates, decisions, and verification\n\nThe core policy is tool-agnostic and manual-first. Codex can orchestrate while separate reviewer agents judge independently.\n\nLinear or another issue tracker is the audit and status record, not the reviewer message bus. Reviewers return verdicts to the orchestrator or human relay; the orchestrator decides what status, synthesis, gate, and required-action updates belong in the tracker.\n\n## Default Workflow\n\n1. If the task input is not clear enough to execute, the orchestrator writes a temporary local executable plan.\n2. If the plan is big and has no phases, the orchestrator infers practical phases and creates a Linear parent issue plus phase child issues.\n3. Reviewers confirm the plan before implementation starts when the plan defines the work, using the same reviewer handoff as later reviews.\n4. For each phase, the orchestrator creates a phase branch from the base branch.\n5. The orchestrator implements the whole phase, commits to the phase branch, pushes only that branch, runs verification, and moves the phase issue to Review.\n6. The orchestrator prepares the review transport and reviewer handoff.\n7. When available, the orchestrator runs Reviewer 1 as a named isolated subagent and reuses it for the phase or parent workflow. The human relays only the external reviewer prompt, usually Reviewer 2.\n8. Reviewers review the PR or packet independently and return verdicts outside the tracker.\n9. In manual relay, the human pastes external review replies back to the orchestrator; in PR transport, the orchestrator reads the PR reviews.\n10. If blocked, the orchestrator fixes the phase branch and requests delta review.\n11. When reviewers approve, the human approves merge to `main` or another protected branch.\n12. The orchestrator merges, verifies, updates or closes the tracker item, deletes the phase branch if approved, and removes the temporary local plan.\n\nThis default shows the Full review path. Light uses one opposite-family reviewer. Skip uses no reviewer.\n\nTask input can be a user prompt, tracker issue, local note, or existing plan. Temporary local executable plans are coordination artifacts. They should stay uncommitted, be reviewed when they define unclear work, and be removed after closeout.\n\n```mermaid\nflowchart LR\n    Plan[\"Local plan\"] --\u003e Issue[\"Issue tracker gate\"]\n    Issue --\u003e Work[\"Orchestrator executes phase branch\"]\n    Work --\u003e Verify[\"Verify phase branch\"]\n    Verify --\u003e R1[\"Reviewer 1 subagent\"]\n    Verify --\u003e Relay[\"Human relay\"]\n    Relay --\u003e R2[\"Reviewer 2\"]\n    R1 --\u003e Synth\n    R2 --\u003e Relay\n    Relay --\u003e Synth[\"Orchestrator synthesis\"]\n    Synth --\u003e Decision{\"Any blocker?\"}\n    Decision --\u003e|Yes| Fix[\"Fix phase branch\"]\n    Fix --\u003e Verify\n    Decision --\u003e|No| Approve[\"Human merge approval\"]\n    Approve --\u003e Merge[\"Merge, verify, close, cleanup\"]\n    Merge --\u003e Done[\"Done\"]\n```\n\n## Use It For\n\n- new app, service, or system builds\n- production changes\n- infrastructure or cloud changes\n- security fixes\n- schema, data, or platform migrations\n- bulk data cleanup\n\nSkip it for one-line fixes, tiny docs, and simple queue/admin work.\n\n## Manual Operating Mode\n\nManual mode is the supported workflow:\n\n1. Codex App or another primary agent acts as orchestrator.\n2. If available, the orchestrator creates or reuses a named isolated Reviewer 1 subagent for the phase or parent workflow.\n3. The human sends prompts only to reviewers the orchestrator cannot launch directly, usually Reviewer 2.\n4. External reviewers reply to the human with independent verdicts.\n5. The human pastes the external review replies back to the orchestrator.\n6. The orchestrator synthesizes, updates Linear when useful, fixes blockers, and asks for human approval at real gates.\n\nManual mode preserves independent judgment and keeps the workflow simple. It relies on the orchestrator to isolate any internal reviewer subagent and on the human to relay only external reviewer messages.\n\nFor a Codex-led workflow, Reviewer 1 may be a reusable named Codex subagent. That gives isolated reviewer context and continuity, not model-family independence. Reviewer 2 should be the opposite-family reviewer when the tier requires independent judgment across model families.\n\n## Phase Branch Mode\n\nFor high-throughput work, use one branch per phase.\n\nPhase branch mode is the default high-throughput path for repo implementation phases when branch pushes are safe. The orchestrator may create the phase branch, implement the whole phase, commit to it, and push updates to that branch without asking the human for every commit or push. Reviewers review the phase branch diff and verification evidence after the phase is implemented, not after every bug.\n\nHuman approval is still required before merging into `main` or another protected branch. The merge approval can also authorize post-merge verification, tracker closeout, and deleting the phase branch after the merge.\n\nPhase branch mode is allowed only when branch pushes do not deploy, mutate live systems, publish releases, or trigger other hard-to-reverse external actions. If a branch push has those effects, treat push as a human gate.\n\n## Review Transport\n\nUse `Review transport: pr | manual-relay`.\n\nDefault to `pr` when the repo has a remote and CI or branch protection. The PR is the review artifact; Linear stays the gate and status record.\n\nUse `manual-relay` for local, no-remote, or simple work where a PR adds overhead.\n\n## Review Tiers\n\n- Skip: tiny docs, typos, formatting, and simple queue/admin work; run verification and keep the configured branch or merge gate.\n- Light: default for routine low-risk, reversible repo work; one opposite-family reviewer, one round, no auto-fix loop. This is a single-review shortcut, not full Four Eyes.\n- Full: high-risk or broad changes; two independent reviewers and bounded fix/re-review. Use Full for security, infrastructure, data/schema, production, deploy, destructive, costly, or irreversible work.\n\nThe human or local plan sets the review tier. The orchestrator may escalate the tier, but must not downgrade its own work without explicit human instruction.\n\nReview phases, not every bug. One phase may contain many related small fixes when they share scope, risk, verification, and rollback. Split only when gates, rollback, owners, repos, deploy windows, or risk class differ.\n\nIf a big local executable plan has no phases yet, the orchestrator should infer practical phases from scope, files, verification, risk, and rollback, then create the parent issue and phase child issues in the tracker. It should ask the human only when the split changes risk, ownership, merge target, deploy behavior, or there are multiple materially different valid decompositions.\n\n## Start\n\n- [Playbook](docs/playbook.md)\n- [Templates](docs/templates.md)\n- [Linear setup](docs/linear-setup.md)\n- [Issue tracker setup](docs/issue-tracker-setup.md)\n- [Examples](examples/)\n\n## Linear Quick Setup\n\n[Linear](https://linear.app/) works well as the issue tracker for Four Eyes.\n\nPrerequisite: you already have a Linear workspace and your agent has Linear access.\n\nCopy this into Codex, Claude Code, or another agent:\n\n```text\nSet up Four Eyes in Linear.\n\nSource repo: https://github.com/nickzren/four-eyes\n\nIf the repo is not available locally, clone or read the source repo first. Then use:\n- README.md\n- docs/playbook.md\n- docs/templates.md\n- docs/issue-tracker-setup.md\n- docs/linear-setup.md\n\nCreate or update Linear docs for the default workflow, playbook, templates, issue tracker setup, and Linear setup. Make phase branch mode with implementation-first flow the default high-throughput path. Make review transport default to `pr` when the repo has a remote and CI or branch protection, otherwise `manual-relay`. Make the Codex-led default use a named isolated Reviewer 1 subagent when available, reused across review rounds for the same phase or parent workflow, with the human relaying only the external Reviewer 2 prompt. If the task input is not clear enough to execute safely, have the orchestrator write a temporary local executable plan, have reviewers confirm it when it defines the work, keep it uncommitted, and remove it after closeout. Create a standing workflow-doc review issue. Keep it brief, public-safe, and generic. Do not add company names, secrets, internal links, or real task history. If repo or Linear access is missing, stop and say exactly what access is needed.\n```\n\n## Run Your First Review\n\nPrerequisite: Linear Quick Setup is already complete.\n\n```text\nUse the Four Eyes workflow in Linear for this task.\n\nRead the existing Four Eyes Default Workflow, Playbook, Templates, and Issue Tracker Setup in Linear first.\n\nRepo path: \u003crepo path\u003e\nPlan path: \u003clocal plan path\u003e\nLinear team/workspace or routing source: \u003cteam, workspace, or mapping doc\u003e\n\nAct as orchestrator.\n\nUse phase branch mode with implementation-first flow unless the plan says otherwise.\nUse review transport `pr` when the repo has a remote and CI or branch protection; otherwise use `manual-relay`.\nIf you can create or reuse a named isolated Reviewer 1 subagent, run Reviewer 1 internally and return only the external Reviewer 2 prompt for human relay. If you cannot create an isolated subagent, return prompts for all expected reviewer slots.\n\nIf the plan is large and has no phases, infer practical phases from scope, files, verification, risk, branch target, and rollback. Create a Linear parent issue plus phase child issues.\n\nBefore pushing a phase branch, confirm branch pushes do not deploy, mutate live systems, publish releases, or trigger hard-to-reverse external effects. If they do, stop and ask for human approval before pushing.\n\nFor the first ready phase:\n1. Create a phase branch from the base branch.\n2. Implement the whole phase.\n3. Commit and push only the named phase branch.\n4. Run verification.\n5. If review transport is `pr`, open or update the PR from phase branch to merge target. Public PRs should use the tracker issue ID only unless the tracker is accessible to the PR audience.\n6. Update Linear to Review.\n7. Run or reuse internal Reviewer 1 if available, then return filled Reviewer Prompt templates only for external reviewer slots, including the issue ID or safe link, review transport, PR link or phase branch, diff summary, verification evidence, and reviewer slot number.\n\nDo not merge to main or another protected branch. End with the current gate plus my exact next action.\n```\n\n## Example Agent Mix\n\nCurrent default:\n\n- Orchestrator: Codex App\n- Reviewer 1: named Codex subagent `reviewer1`, reused by the orchestrator for the phase or parent workflow\n- Reviewer 2: Claude Code, prompted by the human\n\nThese roles are not fixed. Use the strongest current agent for orchestration. For non-skip work, require at least one reviewer from a different model family than the agent that wrote or orchestrated the change unless the human explicitly overrides the review panel.\n\n## Source Of Truth\n\nUse this repo as the version-controlled source.\n\nKeep synced Linear docs updated from this repo.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickzren%2Ffour-eyes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickzren%2Ffour-eyes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickzren%2Ffour-eyes/lists"}