{"id":51564068,"url":"https://github.com/lemberalla/the-hood","last_synced_at":"2026-07-10T13:03:15.263Z","repository":{"id":366542633,"uuid":"1273575430","full_name":"lemberalla/the-hood","owner":"lemberalla","description":"A local, provider-neutral runtime for governed software agent loops.","archived":false,"fork":false,"pushed_at":"2026-07-05T17:54:03.000Z","size":674,"stargazers_count":4,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-05T19:21:22.612Z","etag":null,"topics":["agent-runtime","agentic-ai","agentic-workflow","agents","ai-agents","chatgpt","claude-code","cli","codex","loops","mcp","public","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/thehood","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/lemberalla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","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-06-18T16:54:37.000Z","updated_at":"2026-07-05T17:51:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lemberalla/the-hood","commit_stats":null,"previous_names":["lemberalla/the-hood"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/lemberalla/the-hood","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lemberalla%2Fthe-hood","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lemberalla%2Fthe-hood/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lemberalla%2Fthe-hood/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lemberalla%2Fthe-hood/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lemberalla","download_url":"https://codeload.github.com/lemberalla/the-hood/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lemberalla%2Fthe-hood/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35331955,"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-07-10T02:00:06.465Z","response_time":60,"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-runtime","agentic-ai","agentic-workflow","agents","ai-agents","chatgpt","claude-code","cli","codex","loops","mcp","public","typescript"],"created_at":"2026-07-10T13:03:14.531Z","updated_at":"2026-07-10T13:03:15.256Z","avatar_url":"https://github.com/lemberalla.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TheHood\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/thehood-wordmark.svg\" alt=\"TheHood ASCII wordmark\" width=\"760\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eLocal runtime for governed software goal loops.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/thehood\"\u003e\u003cimg alt=\"npm next\" src=\"https://img.shields.io/npm/v/thehood/next?label=npm%40next\u0026color=f97316\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/lemberalla/the-hood/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/lemberalla/the-hood/actions/workflows/ci.yml/badge.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-blue.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"package.json\"\u003e\u003cimg alt=\"Node \u003e=22\" src=\"https://img.shields.io/badge/node-%3E%3D22-339933.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nTheHood is a local, provider-neutral agent runtime for running serious multi-agent software work from Codex, a CLI, and eventually a small macOS menubar companion.\n\nStatus: developer preview. TheHood `v0.1.0-preview.0` is published as an npm preview package for early adopters who are comfortable with local tools, explicit approval boundaries, and experimental provider wiring. It is not a hosted agent service, cloud scheduler, or polished app platform.\n\n## Install\n\n```bash\nnpm install -g thehood@next\nthehood\nthehood version\nthehood doctor --repo .\n```\n\nOr try it without installing:\n\n```bash\nnpx thehood@next doctor --repo .\n```\n\nTheHood requires Node.js 22 or newer.\n\n## Start Here\n\n\u003e [!TIP]\n\u003e **First 60 seconds**\n\u003e\n\u003e ```bash\n\u003e cd /path/to/your/project\n\u003e thehood doctor --repo .\n\u003e thehood ui --repo .\n\u003e thehood \"ask Pro to plan a small README cleanup\" --repo .\n\u003e ```\n\u003e\n\u003e `doctor` checks provider and role readiness without calling external models. `ui` opens the local terminal command center. Quoted instructions are deterministic shortcuts over existing runtime commands; they still stop at normal approval gates.\n\n\u003e [!NOTE]\n\u003e **Codex-first local loop**\n\u003e\n\u003e ```bash\n\u003e thehood teams apply codex-default --repo .\n\u003e thehood run \"Plan and implement one small safe improvement\" --repo . --loop\n\u003e ```\n\u003e\n\u003e Use this when you want TheHood's approval gates, evidence, verifier separation, and final reports without involving ChatGPT Pro.\n\n\u003e [!NOTE]\n\u003e **ChatGPT Pro as planner, Codex as builder**\n\u003e\n\u003e ```bash\n\u003e thehood teams apply pro-orchestrator --repo .\n\u003e thehood run \"Improve the README onboarding in one small safe slice\" --repo . --loop\n\u003e thehood ui approvals --repo .\n\u003e ```\n\u003e\n\u003e Prompt from Codex: \"Use TheHood to ask Pro to plan a small README cleanup, keep Codex as implementer, and stop before applying any patch until I approve.\"\n\n\u003e [!IMPORTANT]\n\u003e TheHood stops at approval gates when provider calls, repo-context transfers, patch application, protected test changes, dependency installs, or risky commands need review.\n\n## Starter Workflows\n\n\u003e [!NOTE]\n\u003e **Pro for architecture or critique**\n\u003e\n\u003e Use this when you want ChatGPT Pro to think through the direction before local coding work starts.\n\u003e\n\u003e ```bash\n\u003e thehood teams apply pro-orchestrator --repo .\n\u003e thehood plan \"Review this project and propose the next safe improvement\" --repo . --loop\n\u003e ```\n\u003e\n\u003e Example prompt: \"Use TheHood to ask Pro for an architecture plan, then keep Codex as the implementation lane.\"\n\n\u003e [!NOTE]\n\u003e **Claude as second judge**\n\u003e\n\u003e Use this when you want another model to critique or verify a Codex-produced plan or patch.\n\u003e\n\u003e ```bash\n\u003e thehood teams apply claude-second-judge --repo .\n\u003e thehood run \"Review this change for missed edge cases\" --repo . --loop\n\u003e ```\n\u003e\n\u003e Example prompt: \"Use TheHood to let Codex implement the change, then ask Claude as a second judge before verifier approval.\"\n\n\u003e [!NOTE]\n\u003e **Self-building / agentic loop**\n\u003e\n\u003e Use TheHood on TheHood itself: ask Pro to plan a small runtime or CLI improvement, let Codex implement, then route QA, verifier, and critic lanes through the runtime.\n\u003e\n\u003e ```bash\n\u003e thehood teams apply pro-orchestrator --repo .\n\u003e thehood run \"Improve TheHood's CLI harness UX in one small safe slice\" --repo . --loop\n\u003e thehood ui approvals --repo .\n\u003e ```\n\u003e\n\u003e Example prompt: \"Use TheHood to improve TheHood's CLI harness UX. Ask Pro to plan a small safe slice, use Codex as implementer, run verifier and critic lanes, and stop before applying any patch until I approve.\"\n\n\u003e [!NOTE]\n\u003e **MCP connector path**\n\u003e\n\u003e Use this when ChatGPT should act as the MCP host and pull bounded repo evidence through TheHood tools.\n\u003e\n\u003e ```bash\n\u003e thehood mcp config\n\u003e thehood mcp tunnel --tunnel-id \u003ctunnel-id\u003e --profile thehood-local\n\u003e ```\n\u003e\n\u003e Example prompt in ChatGPT: \"Use TheHood to inspect this repo, read only the files needed for a small plan, and ask me before any implementation or external transfer.\"\n\n## Important Guidelines\n\n- Treat `thehood@next` as a developer preview, not a stable production service.\n- Keep `.thehood/`, `.thehood-browser.json`, provider logs, local env files, and private run artifacts out of git.\n- Models suggest; the runtime enforces permissions, approvals, evidence capture, and final status.\n- Keep implementer and verifier roles separate. Verifier and critic roles should stay read-only.\n- Use ChatGPT Web, ChatGPT Atlas, and MCP connector paths as optional, user-configured experiments until they are promoted to stable surfaces.\n\nThe core idea is simple:\n\n- Models suggest.\n- The runtime enforces.\n- Users stay in control.\n\nTheHood lets a user assign different models or agent tools to different responsibilities. The product default is Codex-first: Codex can orchestrate, implement, QA, critique, and verify through separate runtime roles, while users can opt into GPT, ChatGPT Pro, Claude Code, future API adapters, or future local models for roles as those paths are wired. Codex becomes the governed workbench; Claude can second-judge or build; Pro can approve strategy when the stakes justify it.\n\nThe first product surface is a CLI plus an MCP server. The macOS menubar app should remain a thin trigger and status surface over the same local runtime.\n\n## Works Today\n\n- Local project setup and JSON runtime config under `.thehood/config.json`, with local git excludes for TheHood runtime state.\n- CLI and stdio MCP control surfaces over the same local runtime.\n- Codex-first role mapping with separate orchestrator, planner, implementer, QA, verifier, and critic roles.\n- Local Codex CLI and Claude Code command adapters that must return schema-bound responses.\n- Deterministic `stub` provider for local smoke tests and synthetic demonstrations.\n- Approval gates, protected test/fixture/snapshot/eval classification, isolated patch capture, and runtime-owned integration reports.\n- Runtime-owned evidence: command logs, git status/diff snapshots, provider invocation artifacts, final reports, progress packets, review lanes, revision packets, and agent board snapshots.\n- Same-run summons and bounded fan-out as read-only sidecar evidence, not acceptance votes.\n- ChatGPT Web bridge, bundled ChatGPT Atlas bridge with a local Computer Use controller protocol, and ChatGPT MCP connector guidance as experimental provider paths.\n\n## Planned Or Experimental\n\n- OpenAI API, Anthropic API, and local model adapters are represented in provider config but are not wired as production external model adapters yet.\n- Hosted execution, cloud routines, timer schedules, and overnight automation are not part of `v0.1.0-preview.0`.\n- A full web dashboard and macOS menubar app remain future control surfaces over the runtime.\n- ChatGPT MCP connector mode depends on ChatGPT custom connector/tunnel availability in the user's workspace and should be treated as optional.\n- Native Codex visual rendering beyond explicit artifact/dashboard payloads remains a later integration layer.\n\n## Current Implementation\n\nThe first implementation slice is a TypeScript CLI/runtime skeleton.\n\nIt supports:\n\n- local project initialization\n- JSON config under `.thehood/config.json`\n- Codex-first default role mapping for orchestrator, implementer, QA, verifier, and critic\n- provider and role inspection\n- provider and role health inspection\n- agent roster inspection showing role ownership, readiness, and read/edit authority\n- runtime-derived agent board snapshots and dashboard payloads for Codex card-style agent visibility\n- optional repo-local Codex plugin scaffold for TheHood workflow guidance and MCP setup\n- runtime-owned team presets for Codex default, ChatGPT Pro orchestration, Claude second-judge, Spark plus Sonnet, Claude builder, and high-assurance Pro plus Claude setups\n- read-only loop recommendation that routes a plain-language goal into a recipe, recommended stack, completion contract draft, actions, alternatives, and Codex card artifact\n- configurable budget defaults for max provider iterations and fan-out item caps\n- Codex-facing MCP tools for role assignment and guest-agent consultation\n- local-only Pro access preflight so Codex can distinguish runtime autopilot, direct bridge readiness, host-policy blocks, and ChatGPT MCP connector handoff paths\n- role mapping updates\n- run creation for `plan` and `implement`\n- approval, rejection, abort, status, and log inspection\n- bounded CLI artifact and diff inspection\n- hard enforcement that implementer and verifier cannot be the same agent\n- a real stdio MCP server exposing TheHood runtime tools\n- runtime-owned command log artifacts\n- git status/diff evidence capture with protected test-path classification\n- runtime-owned integration reports for approved isolated patch application\n- runtime-owned final reports for completed runs\n- runtime-owned progress packet artifacts for completed runs\n- runtime-owned external transfer manifests before repo context or progress packets leave the machine\n- confirmed GitHub connector-aware repo context routing for clean pushed repos in ChatGPT Web\n- user-configurable approval policy with manual, auto-low-risk, and autopilot modes\n- separate approval gates when integrated patches touch protected test, fixture, snapshot, or eval paths\n- runtime-enforced max iteration limits across resumed runs\n- runtime-captured package validation command evidence during verifier review\n- runtime-owned review routing artifacts that classify implementation risk before model QA/verifier dispatch\n- read-only model-assisted QA tester lane for missed cases and validation suggestions\n- runtime-owned critic trigger artifacts when QA, verifier, or validation evidence indicates risk\n- runtime-owned revision packet artifacts that route fixable QA, critic, or verifier findings back to the implementer\n- provider config merging that preserves newly added built-in models and future-facing model aliases in stale repo-local configs\n- deterministic `stub` provider for local loop smoke tests\n- `continue` advances runs through orchestrator, implementer, evidence capture, and verifier phases\n- `loop` keeps advancing a run until terminal state, manual gate, no progress, or a cycle cap\n- schema-bound agent directives and response validation before runtime state advances\n- provider response contracts that keep JSON mechanical while long plans, reports, and reviews live in markdown payload fields\n- guarded local CLI adapters for Codex CLI and Claude Code\n- runtime-owned local agent execution artifacts for Codex CLI and Claude Code command invocations\n- bridge-backed ChatGPT Web adapter for ChatGPT Pro orchestration\n- shipped-enabled ChatGPT Atlas adapter backed by the packaged `thehood-chatgpt-atlas-bridge` command and a user-configured local Computer Use controller\n- provider access-mode metadata for agent bridges, API agents, and MCP connectors\n- persistent TheHood Chrome profile manager for the ChatGPT Web bridge\n- ChatGPT Web auth and composer readiness checks before bridge calls are marked ready\n- branded terminal dashboard shell for runtime, role, and browser readiness\n- terminal approval inbox for pending runtime gates\n- terminal run monitor for provider wait, approval/transfer gates, and review ownership lanes\n- run status insights for latest provider output and final reports\n- run status insights for latest progress, reconciliation, repo context, remote repo context, provider execution, final report, and transfer manifest refs\n- compact MCP host responses that return refs, counts, latest summaries, and bounded lane/card previews by default instead of dumping full run evidence into the Codex session context\n- runtime-derived loop responsibility schedules showing planner, implementer, verifier, runtime QA, QA tester, critic, reconciliation, integration, approval, and completion ownership\n- bounded canonical memory refs injected into provider directives so providers rehydrate from runtime state instead of stale chat history\n- runtime-captured repo context packs when read-only orchestrators request evidence\n- refs-only GitHub connector context when the active ChatGPT Web bridge has confirmed GitHub connector access and can inspect a clean pushed GitHub repo at the current commit\n- targeted follow-up repo context packs when a provider delegates concrete new repo paths\n- schema-bound planner reconciliation from completed run progress packets\n- bounded MCP artifact reads for inspecting guest-agent responses from chat\n- read-only MCP repo gateway tools for tree, search, file reads, git status, and git diff\n\nChatGPT Web is wired through a user-configured bridge command. ChatGPT Atlas is represented as an enabled-by-default, setup-gated provider backed by the packaged `thehood-chatgpt-atlas-bridge` command; that bridge invokes a trusted local Computer Use controller command to operate the selected Atlas window, verify the requested model, and return a schema-bound `AgentResponse` inside a controller result envelope. API provider adapters are not wired to external models yet, though OpenAI and Anthropic API key env names are represented in provider config for future adapters. Local Codex CLI and Claude Code adapters can be selected by role and must return schema-bound responses. Codex CLI discovers live model slugs, while ChatGPT Web, ChatGPT Atlas, and Claude Code expose configured/custom model passthrough so users can select newly available model aliases without waiting for a TheHood release.\n\nUsers can choose model owners per role:\n\n```bash\nnode dist/cli/main.js roles set implementer claude-code:sonnet --repo .\nnode dist/cli/main.js roles set verifier codex-cli:spark --repo .\nnode dist/cli/main.js roles set critic claude-code:fable --repo .\nnode dist/cli/main.js teams apply spark-plus-sonnet --repo .\nnode dist/cli/main.js teams apply pro-claude-high-assurance --repo .\n```\n\nUsers can choose between three ChatGPT Pro routes:\n\n- `chatgpt-web`: TheHood invokes the ChatGPT Web bridge as an orchestrator or planner.\n- `chatgpt-atlas`: TheHood invokes the packaged Atlas bridge, which then calls a trusted local Computer Use controller for a visible ChatGPT Atlas session.\n- `mcp-connector`: ChatGPT connects to TheHood as an MCP connector and uses TheHood's repo/run tools directly.\n\nBoth paths keep repo access, approvals, logs, and verification gates owned by the runtime.\n`thehood pro-route` controls the default route for ChatGPT Pro only. It does not make every TheHood task use Pro or Atlas; normal roles remain Codex-first unless the user asks for Pro or changes role assignments.\nFor connector mode, generate the local setup guide with `thehood mcp tunnel --tunnel-id \u003ctunnel-id\u003e --profile thehood-local`, keep Secure MCP Tunnel running, and validate from a fresh ChatGPT conversation with `thehood_doctor` plus a read-only repo gateway tool. This is separate from the `chatgpt-web` agent bridge and does not use Chrome/CDP bridge environment variables.\nFor Atlas mode, `thehood pro-route set atlas --repo .` saves Atlas as the preferred Pro route and uses `thehood-chatgpt-atlas-bridge` by default. Atlas ships enabled, and `thehood mcp config --chatgpt-atlas` wires the packaged `thehood-chatgpt-atlas-controller`; real desktop use still requires selecting the intended Atlas window and setting `THEHOOD_CHATGPT_ATLAS_TARGET_CONFIRMED=1`. The controller receives the requested model plus selector labels in the bridge request, must select or verify Pro before posting the prompt, and must return a verified controller result envelope containing the normalized `AgentResponse`. CI and local bridge smoke tests can use `THEHOOD_CHATGPT_ATLAS_TRANSPORT=fake` with `THEHOOD_CHATGPT_ATLAS_FAKE_RESPONSE` or `THEHOOD_CHATGPT_ATLAS_FAKE_RESPONSE_FILE`; fake transport is for deterministic tests only.\nWhen Codex or a tenant policy blocks a direct external disclosure to ChatGPT Web, that is outside TheHood autopilot. Use `thehood_pro_access` to get the local bridge status and a connector-mode handoff instead of repeating approval prompts.\nFor broader Claude/Codex/GPT fan-outs, call `thehood_model_access` before the model-backed request. It does not call providers or send repo context; it returns provider readiness, repo visibility, the data boundary, a compact approval packet, and fallback paths. Dirty or unpushed repos ask the user to choose between committing and pushing a checkpoint, approving bounded local context/diff transfer, using no-repo-context strategy, or cancelling. Clean pushed GitHub repos can use remote refs only when the target provider route is verified. For `chatgpt-web`, TheHood treats remote refs as the default only when the active bridge GitHub connector surface is confirmed; otherwise it presents connector setup, explicit local context approval, no-repo-context, or cancel paths.\n\n## Quick Start\n\n```bash\nnpm install\nnpm run build\nnpm run smoke:runtime\nnpm run smoke:mcp\nnode dist/cli/main.js setup --repo .\nnode dist/cli/main.js doctor --repo .\nnode dist/cli/main.js roster --repo .\nnode dist/cli/main.js agent-board --repo . --artifact --json\n```\n\nThe full local CLI surface includes:\n\n```bash\nnode dist/cli/main.js init --repo .\nnode dist/cli/main.js setup --repo .\nnode dist/cli/main.js doctor --repo .\nnode dist/cli/main.js roster --repo .\nnode dist/cli/main.js agent-board --repo .\nnode dist/cli/main.js agent-board --repo . --artifact --json\nnode dist/cli/main.js teams --repo .\nnode dist/cli/main.js config set fanout-max-items 4 --repo .\nnode dist/cli/main.js pro-route --repo .\nnode dist/cli/main.js pro-route set atlas --repo .\nnode dist/cli/main.js roles --repo .\nnode dist/cli/main.js recommend-loop \"Fix flaky checkout tests\" --repo . --max-iterations 5\nnode dist/cli/main.js goal \"Prepare release metadata\" --repo . --max-iterations 5\nnode dist/cli/main.js run \"Implement the first provider adapter\" --repo .\nnode dist/cli/main.js run \"Exercise the full loop\" --repo . --loop\nnode dist/cli/main.js status --repo .\nnode dist/cli/main.js agent-board \u003crun-id\u003e --repo .\nnode dist/cli/main.js artifact \u003crun-id\u003e \u003cartifact-ref\u003e --repo .\nnode dist/cli/main.js evidence \u003crun-id\u003e --repo .\nnode dist/cli/main.js continue \u003crun-id\u003e --repo .\nnode dist/cli/main.js loop \u003crun-id\u003e --repo .\nnode dist/cli/main.js transfer preview \u003crun-id\u003e --repo .\nnode dist/cli/main.js approvals policy set mode autopilot --repo .\nnode dist/cli/main.js ui approvals --repo .\nnode dist/cli/main.js ui settings --repo .\nnode dist/cli/main.js ui settings crew --repo .\nnode dist/cli/main.js ui settings commands --repo .\nnode dist/cli/main.js config set max-iterations 8 --repo .\nnode dist/cli/main.js browser status\nnode dist/cli/main.js ui --repo .\nnode dist/cli/main.js mcp tunnel --tunnel-id \u003ctunnel-id\u003e\n```\n\nTheHood stores local run history and evidence in `.thehood/`, including run records, logs, provider responses, approval evidence, final reports, and progress packets. This is useful local state, not source code. When TheHood creates repo-local state inside a git checkout, it automatically adds `.thehood/` and `.thehood-browser.json` to `.git/info/exclude` so normal `git status` stays clean without changing the repo's committed `.gitignore`. Do not commit `.thehood/`; delete it when you want to clear local run history.\n\nThe optional Codex plugin lives at `plugins/thehood-codex` and is listed by the repo marketplace at `.agents/plugins/marketplace.json`. It is not installed by default because repo-root Codex custom agents and plugin-provided surfaces should appear only when a user opts into them.\n\n```bash\ncodex plugin marketplace add /path/to/the-hood\ncodex plugin add thehood-codex@thehood\n```\n\nThe plugin expects the `thehood` binary to be available on `PATH` for MCP startup. During local development, use `node dist/cli/main.js mcp config` when you want an absolute-path MCP snippet instead.\n\n## Product Shape\n\n```text\nCodex / CLI / macOS menubar\n  trigger runs, approvals, status, and configuration\n\nMCP server\n  exposes TheHood tools to Codex\n\nLocal runtime\n  owns state, permissions, logs, worktrees, approvals, and test gates\n\nProvider adapters\n  connect to ChatGPT Pro, ChatGPT Atlas via Computer Use, OpenAI API, Anthropic API, Codex, Claude Code, and local models\n\nMCP connector mode\n  lets ChatGPT, Codex, or another MCP host call TheHood's runtime and repo tools\n\nAgents\n  orchestrator, planner, researcher, implementer, qa tester, verifier, critic, integrator\n```\n\nCodex-native Subagents are owned by Codex, not by TheHood MCP tool output. TheHood does not ship repo-root custom agents by default; users can opt into the Codex plugin for TheHood workflow guidance and MCP wiring. TheHood runtime-owned provider calls surface through run status, artifacts, MCP, CLI, TUI, and the agent board.\n\n## Foundation Rules\n\n- The implementer and verifier must not be the same agent.\n- The verifier does not get edit tools.\n- The QA tester does not get edit tools and cannot satisfy runtime validation gates.\n- Runtime-captured logs are the source of truth, not model summaries.\n- Model session context is disposable; TheHood preserves exact artifacts and rehydrates providers from runtime state.\n- Fixable reviewer findings become runtime revision packets before the implementer gets another pass.\n- Test changes require separate classification and review.\n- The frontend never owns orchestration logic. It triggers runtime actions.\n- Provider choice is user-controlled per role.\n- The runtime should be useful headless before it gets a polished UI.\n\n## Documentation\n\n- [Architecture](docs/ARCHITECTURE.md)\n- [Codex Setup](docs/CODEX_SETUP.md)\n- [Runtime Loop](docs/RUNTIME_LOOP.md)\n- [Role Contracts](docs/ROLE_CONTRACTS.md)\n- [Trust Model](docs/TRUST_MODEL.md)\n- [Provider Matrix](docs/PROVIDER_MATRIX.md)\n- [Known Limitations](docs/KNOWN_LIMITATIONS.md)\n- [Goal, Loop, Schedule](docs/GOAL_LOOP_SCHEDULE.md)\n- [Loop Selection UX](docs/LOOP_SELECTION_UX.md)\n- [Completion Contract](docs/COMPLETION_CONTRACT.md)\n- [Loop Recipes](docs/LOOP_RECIPES.md)\n- [Synthetic Stub Demo](docs/DEMO.md)\n- [Prompt Schemas](docs/PROMPT_SCHEMAS.md)\n- [Memory And Reconciliation](docs/MEMORY_AND_RECONCILIATION.md)\n- [CLI Spec](docs/CLI_SPEC.md)\n- [MCP Spec](docs/MCP_SPEC.md)\n- [Provider Adapters](docs/PROVIDER_ADAPTERS.md)\n- [Testing And Verification](docs/TESTING_AND_VERIFICATION.md)\n- [Security And Privacy](docs/SECURITY_AND_PRIVACY.md)\n- [Product Strategy](docs/product/README.md)\n- [Model Selection](docs/product/model-selection.md)\n- [Research Notes](docs/RESEARCH_NOTES.md)\n- [Roadmap](docs/ROADMAP.md)\n- [Glossary](docs/GLOSSARY.md)\n- [Licensing](docs/LICENSING.md)\n- [Open Decisions](docs/OPEN_DECISIONS.md)\n- [Public Repo Readiness](docs/PUBLIC_REPO_READINESS.md)\n- [v0.1.0-preview.0 Release Notes](docs/release/v0.1.0-preview.0.md)\n- [Static Preview Site](site/README.md)\n\n## Public Repo Docs\n\n- [Contributing](CONTRIBUTING.md)\n- [Security Policy](SECURITY.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Agent Instructions](AGENTS.md)\n\n## Maintainer\n\nBuilt and maintained by [Oncel Cebeci](https://www.oncelcebeci.com).\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n\n## Decisions\n\n- [0001: Runtime First With CLI And MCP](docs/decisions/0001-runtime-first-cli-and-mcp.md)\n- [0002: Provider Neutral Role Mapping](docs/decisions/0002-provider-neutral-role-mapping.md)\n- [0003: Separate Implementation And Verification](docs/decisions/0003-separate-implementation-and-verification.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flemberalla%2Fthe-hood","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flemberalla%2Fthe-hood","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flemberalla%2Fthe-hood/lists"}