overseer-mcp 0.1.1

package/.env.example

@@ -0,0 +1,40 @@
+# Core
+OVERSEER_PROVIDER=openai
+# OVERSEER_REPO_ROOT=/absolute/path/to/your/repo
+# OVERSEER_TEST_COMMAND=npm test
+
+# Context and validation caps
+OVERSEER_MAX_FILES=12
+# get_plan sends full bodies for this many top-relevant files; the rest go as signature-only outlines.
+OVERSEER_PLAN_FULL_FILES=3
+OVERSEER_MAX_FILE_BYTES=65536
+OVERSEER_MAX_DIFF_BYTES=262144
+OVERSEER_TEST_TIMEOUT_MS=300000
+
+# Shared API provider options
+# Either set the key directly, or point to another env var that the MCP client forwards.
+OVERSEER_API_KEY=replace-with-your-key
+# OVERSEER_API_KEY_ENV=OPENAI_API_KEY
+OVERSEER_MODEL=replace-with-model-name
+# OVERSEER_MAX_OUTPUT_TOKENS=2500
+OVERSEER_TEMPERATURE=0.2
+
+# OpenAI-compatible provider
+# OVERSEER_PROVIDER=openai
+OVERSEER_BASE_URL=https://api.openai.com/v1
+# Custom OpenAI-compatible gateways, including opencode-go style API-key plans:
+# OVERSEER_BASE_URL=https://your-gateway.example/v1
+# OVERSEER_API_KEY_ENV=OPENCODE_API_KEY
+# OVERSEER_MODEL=your-model-name
+
+# Anthropic provider
+# OVERSEER_PROVIDER=anthropic
+# OVERSEER_BASE_URL=https://api.anthropic.com
+
+# CLI provider
+# OVERSEER_PROVIDER=cli
+OVERSEER_CLI_COMMAND=codex
+# JSON array is safest for args with spaces.
+OVERSEER_CLI_ARGS=["exec"]
+OVERSEER_CLI_PROMPT_VIA=stdin
+OVERSEER_CLI_TIMEOUT_MS=120000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 digisdatadigisdata-coder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# overseer-mcp
+
+`overseer-mcp` is an MCP server for cheap executor agents that need a stronger expert only at the moments where they tend to derail: planning, mid-implementation decisions, and final review.
+
+The expert is dormant between calls. When a tool is called, the server reads ground truth from git and disk, assembles the smallest useful context, asks the configured expert provider, and returns a compact contract.
+
+## Why It Exists
+
+Executor agents can bias an expert if they summarize the code incorrectly. `overseer-mcp` avoids that failure mode: the executor chooses which tool to call and which file paths matter, but file content, diffs, status, and validation output are read by the server.
+
+The design is deliberately token-frugal:
+
+- `get_plan` sends git status, a capped tracked-file map, the executor's named files, and a server-selected set of relevant files — full bodies for the top few, signature-only outlines for the rest.
+- `consult_expert` sends named files, the real current diff, and literal error output.
+- `request_review` sends real unstaged/staged diffs and optional validation output.
+- File count, file bytes, diff bytes, temperature, and output tokens are capped.
+- System prompts are static and first in the message order for provider prefix caching.
+- Anthropic requests mark the system prompt with prompt-cache metadata.
+- The executor should call the expert at three gates only: plan, blocker, review.
+
+## Tools
+
+`get_plan`
+
+Call before writing code. Input: `task`, optional `focus_paths`, optional `mode` (`full` or `lite`). Returns a self-sufficient implementation contract.
+
+`consult_expert`
+
+Call before improvising on a non-trivial decision, unclear error, or ambiguity. Input: `question`, optional `file_paths`, `error_output`, `options_considered`. Returns `PROCEED`, `DECIDE`, `FIX`, `REDIRECT`, or `NEED_INFO`.
+
+`request_review`
+
+Call when implementation is done. Input: optional `task`, optional `run_tests` (default `true`). Returns `APPROVE` or `REQUEST_CHANGES`.
+
+## Install
+
+Use it through any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "overseer": {
+      "command": "npx",
+      "args": ["-y", "overseer-mcp"],
+      "env": {
+        "OVERSEER_PROVIDER": "openai",
+        "OVERSEER_API_KEY": "YOUR_KEY",
+        "OVERSEER_MODEL": "gpt-5.5",
+        "OVERSEER_REPO_ROOT": "/absolute/path/to/your/repo",
+        "OVERSEER_TEST_COMMAND": "npm test"
+      }
+    }
+  }
+}
+```
+
+For local development in this repo:
+
+```bash
+npm install
+npm run build
+OVERSEER_PROVIDER=cli OVERSEER_CLI_COMMAND=codex OVERSEER_CLI_ARGS='["exec"]' node dist/index.js
+```
+
+## Init Wizard
+
+Generate MCP configuration with:
+
+```bash
+overseer-mcp init
+```
+
+From this repo, use:
+
+```bash
+node dist/index.js init
+```
+
+The wizard supports:
+
+- OpenAI API (`OVERSEER_PROVIDER=openai`).
+- Anthropic API (`OVERSEER_PROVIDER=anthropic`).
+- Custom OpenAI-compatible APIs (`OVERSEER_PROVIDER=openai` plus `OVERSEER_BASE_URL`), including opencode-go style API-key subscriptions and GLM/gateway providers.
+- CLI experts (`OVERSEER_PROVIDER=cli`) for Codex, Claude, or local CLIs, with optional login.
+
+On Windows, the helper script walks through the same setup and writes both MCP config formats to `generated/`:
+
+```bat
+configure-overseer.bat
+```
+
+It builds the package, asks for the expert profile that Overseer will call, runs `init --print`, then writes:
+
+- `generated\overseer-codex.toml`
+- `generated\overseer-mcp.json`
+- `generated\OVERSEER_AGENT_INSTRUCTIONS.md`
+
+`OVERSEER_AGENT_INSTRUCTIONS.md` is for the cheap/operator agent, not for the expert model. It is generic AGENTS.md-style guidance that tells whichever executor you use (Codex, Mimo, Qoder, Cline, Roo, Trae, Claude Code, etc.) to call `get_plan`, `consult_expert`, and `request_review` at the right gates.
+
+If the operator agent is Codex, the script can append the generated MCP block to the target repo `.codex\config.toml` after creating a backup. For Qoder, Mimo, Cline, Roo, or similar clients, paste/import the generated `overseer-mcp.json` where that client keeps MCP servers. Separately, the script can append the operator instructions to the target repo `AGENTS.md` after creating a backup. It never asks for the API key value; it asks for the environment variable name, such as `OPENCODE_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY`.
+
+The Windows configurator also copies the JSON config into the target repo as `overseer-mcp.json` so the operator agent can find it from project context. Treat that file as local machine config because it contains absolute paths. Do not commit it to GitHub unless you intentionally convert it into a portable template such as `overseer-mcp.example.json`.
+
+For non-interactive generation:
+
+```bash
+node dist/index.js init --print \
+  --target codex \
+  --name overseer-opencode \
+  --expert openai-compatible \
+  --repo-root C:/Users/Usuario/automatizador-qoder- \
+  --api-key-env OPENCODE_API_KEY \
+  --base-url https://api.opencode.example/v1 \
+  --model opencode-go
+```
+
+That prints a Codex `config.toml` block. The key is not embedded. Codex forwards `OPENCODE_API_KEY`, and `overseer-mcp` reads it through `OVERSEER_API_KEY_ENV`.
+
+Generate only the operator instructions:
+
+```bash
+node dist/index.js instructions --print --mcp-name overseer-opencode > generated/OVERSEER_AGENT_INSTRUCTIONS.md
+```
+
+Put those instructions where the **operator agent** reads persistent project guidance. For most coding agents, that means appending them to the target repo `AGENTS.md`.
+
+To manage several expert profiles, generate one block per profile with a different `--name`:
+
+```bash
+node dist/index.js init --print --target codex --name overseer-gpt --expert openai --api-key-env OPENAI_API_KEY --model gpt-5.5
+node dist/index.js init --print --target codex --name overseer-claude --expert anthropic --api-key-env ANTHROPIC_API_KEY --model claude-your-model
+node dist/index.js init --print --target codex --name overseer-opencode --expert openai-compatible --api-key-env OPENCODE_API_KEY --base-url https://api.opencode.example/v1 --model opencode-go
+```
+
+For JSON-style MCP clients such as Qoder/Mimo/Cline/Roo-style configs:
+
+```bash
+node dist/index.js init --print --target json --name overseer-opencode --expert openai-compatible --api-key-env OPENCODE_API_KEY --base-url https://api.opencode.example/v1 --model opencode-go
+```
+
+For CLI plan providers:
+
+```bash
+node dist/index.js init --print --target codex --name overseer-codex-cli --expert cli --cli-command codex --cli-args '["exec"]'
+node dist/index.js init --print --target codex --name overseer-claude-cli --expert cli --cli-command claude --cli-args '["-p"]' --run-login
+```
+
+`--run-login` uses the current terminal and runs the known login command for `codex` or `claude`. For other CLIs, pass an explicit login command:
+
+```bash
+node dist/index.js init --print --expert cli --cli-command mycli --login-command '["mycli","login"]' --run-login
+```
+
+When the Windows configurator uses Codex CLI, it checks `~\.codex\config.toml` before login. If it finds an unsupported `service_tier` value such as `default`, it offers `flex`, `fast`, or removing the line, saves a backup, then continues.
+
+CLI login is owned by the selected CLI, not by `overseer-mcp`. For example, `codex login` stores Codex auth in Codex's global files. Re-running `configure-overseer.bat` does not delete that login; answer `no` to the login prompt when the CLI is already authenticated.
+
+## Configuration
+
+| Variable | Required | Provider | Default | Meaning |
+| --- | --- | --- | --- | --- |
+| `OVERSEER_PROVIDER` | yes | all | none | `openai`, `anthropic`, or `cli`. |
+| `OVERSEER_REPO_ROOT` | no | all | `process.cwd()` | Repo the server reads. |
+| `OVERSEER_TEST_COMMAND` | no | all | none | Validation command for `request_review`. |
+| `OVERSEER_MAX_FILES` | no | all | `12` | Max files read per tool call. |
+| `OVERSEER_MAX_FILE_BYTES` | no | all | `65536` | Per-file byte cap. |
+| `OVERSEER_MAX_DIFF_BYTES` | no | all | `262144` | Review diff byte cap. |
+| `OVERSEER_TEST_TIMEOUT_MS` | no | all | `300000` | Validation timeout. |
+| `OVERSEER_API_KEY` | yes | `openai`, `anthropic` | none | API key. |
+| `OVERSEER_API_KEY_ENV` | no | `openai`, `anthropic` | none | Name of an env var containing the API key. Useful for MCP clients that forward secrets. |
+| `OVERSEER_BASE_URL` | no | `openai`, `anthropic` | OpenAI/Anthropic default | API base URL. |
+| `OVERSEER_MODEL` | yes | `openai`, `anthropic` | none | Expert model name. |
+| `OVERSEER_MAX_OUTPUT_TOKENS` | no | `openai`, `anthropic` | tool-specific cap | Overrides output cap. |
+| `OVERSEER_TEMPERATURE` | no | `openai`, `anthropic` | `0.2` | Deterministic output. |
+| `OVERSEER_CLI_COMMAND` | yes | `cli` | none | CLI executable. |
+| `OVERSEER_CLI_ARGS` | no | `cli` | empty | JSON string array or whitespace list. |
+| `OVERSEER_CLI_PROMPT_VIA` | no | `cli` | `stdin` | `stdin` or `arg`. |
+| `OVERSEER_CLI_TIMEOUT_MS` | no | `cli` | `120000` | CLI completion timeout. |
+
+OpenAI-compatible endpoints include OpenAI, GLM/Zhipu gateways, opencode-style gateways, and local servers that implement chat completions.
+
+## Executor System Instructions
+
+Copy this block into the executor agent system prompt:
+
+```text
+You have an `overseer` expert advisor available via MCP tools. Use it like this:
+1. Before writing any code, call get_plan with the user's request. Follow the plan.
+2. While implementing, the moment you face a non-trivial design decision, an error you
+   don't fully understand, or an ambiguity - call consult_expert BEFORE improvising.
+   Attach the relevant file_paths and literal error_output. Do not guess on your own.
+3. When done, call request_review. If it returns REQUEST_CHANGES, apply REQUIRED_FIXES
+   and review again. Only finish on APPROVE.
+Always pass real file paths and real error text - the expert reads them from disk itself.
+```
+
+## Manual Smoke Test
+
+Build first:
+
+```bash
+npm install
+npm run build
+```
+
+Then inspect the server:
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+Use safe local env for listing tools, for example:
+
+```bash
+OVERSEER_PROVIDER=cli OVERSEER_CLI_COMMAND=node OVERSEER_CLI_ARGS='["-e","process.stdin.resume()"]' npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+The tool list should contain exactly:
+
+- `get_plan`
+- `consult_expert`
+- `request_review`
+
+## Development
+
+```bash
+npm test
+npm run build
+```
+
+The tests cover config validation, path traversal refusal, prompt payload labels, tool context assembly, diff truncation, and stdio tool listing.

package/configure-overseer.bat

@@ -0,0 +1,239 @@
+@echo off
+setlocal EnableExtensions EnableDelayedExpansion
+
+cd /d "%~dp0"
+
+echo.
+echo overseer-mcp configurator
+echo =========================
+echo.
+
+where node >nul 2>nul
+if errorlevel 1 (
+  echo ERROR: node was not found in PATH.
+  exit /b 1
+)
+
+where npm >nul 2>nul
+if errorlevel 1 (
+  echo ERROR: npm was not found in PATH.
+  exit /b 1
+)
+
+if not exist "generated" mkdir "generated"
+set "OUT_CODEX=generated\overseer-codex.toml"
+set "OUT_JSON=generated\overseer-mcp.json"
+set "REPO_JSON=overseer-mcp.json"
+
+echo.
+echo This wizard generates both MCP config formats:
+echo   - Codex operator: generated\overseer-codex.toml for project .codex\config.toml
+echo   - Generic JSON operator: generated\overseer-mcp.json for Qoder / Mimo / Cline / Roo / other MCP clients
+echo The expert model is selected in the next step.
+
+echo.
+echo Expert profile:
+echo   1. opencode-go or custom OpenAI-compatible API
+echo   2. OpenAI API
+echo   3. Anthropic API
+echo   4. Codex CLI plan
+echo   5. Claude CLI plan
+set /p "EXPERT_CHOICE=Choose expert [1]: "
+if "%EXPERT_CHOICE%"=="" set "EXPERT_CHOICE=1"
+set "EXPERT_CHOICE=%EXPERT_CHOICE:~0,1%"
+
+set "REPO_ROOT=%CD%\.."
+for %%I in ("%REPO_ROOT%") do set "REPO_ROOT=%%~fI"
+set /p "INPUT_REPO_ROOT=Repo root [%REPO_ROOT%]: "
+if not "%INPUT_REPO_ROOT%"=="" set "REPO_ROOT=%INPUT_REPO_ROOT%"
+
+set "TEST_COMMAND="
+set /p "TEST_COMMAND=Validation command, empty to skip: "
+
+if "%EXPERT_CHOICE%"=="1" goto custom_api
+if "%EXPERT_CHOICE%"=="2" goto openai_api
+if "%EXPERT_CHOICE%"=="3" goto anthropic_api
+if "%EXPERT_CHOICE%"=="4" goto codex_cli
+if "%EXPERT_CHOICE%"=="5" goto claude_cli
+
+echo ERROR: invalid expert choice.
+exit /b 1
+
+:custom_api
+set "PROFILE_NAME=overseer-opencode"
+set "KEY_ENV_NAME=OPENCODE_API_KEY"
+set "BASE_URL=https://api.opencode.example/v1"
+set "MODEL_NAME=opencode-go"
+set /p "INPUT_PROFILE=MCP profile name [%PROFILE_NAME%]: "
+if not "%INPUT_PROFILE%"=="" set "PROFILE_NAME=%INPUT_PROFILE%"
+set /p "INPUT_KEY_ENV=Secret env var name [%KEY_ENV_NAME%]: "
+if not "%INPUT_KEY_ENV%"=="" set "KEY_ENV_NAME=%INPUT_KEY_ENV%"
+set /p "INPUT_BASE_URL=OpenAI-compatible base URL [%BASE_URL%]: "
+if not "%INPUT_BASE_URL%"=="" set "BASE_URL=%INPUT_BASE_URL%"
+set /p "INPUT_MODEL=Model name [%MODEL_NAME%]: "
+if not "%INPUT_MODEL%"=="" set "MODEL_NAME=%INPUT_MODEL%"
+call :run_init_api openai-compatible "%PROFILE_NAME%" "%KEY_ENV_NAME%" "%BASE_URL%" "%MODEL_NAME%"
+if errorlevel 1 goto fail
+goto install
+
+:openai_api
+set "PROFILE_NAME=overseer-gpt"
+set "KEY_ENV_NAME=OPENAI_API_KEY"
+set "MODEL_NAME=gpt-5.5"
+set /p "INPUT_PROFILE=MCP profile name [%PROFILE_NAME%]: "
+if not "%INPUT_PROFILE%"=="" set "PROFILE_NAME=%INPUT_PROFILE%"
+set /p "INPUT_KEY_ENV=Secret env var name [%KEY_ENV_NAME%]: "
+if not "%INPUT_KEY_ENV%"=="" set "KEY_ENV_NAME=%INPUT_KEY_ENV%"
+set /p "INPUT_MODEL=Model name [%MODEL_NAME%]: "
+if not "%INPUT_MODEL%"=="" set "MODEL_NAME=%INPUT_MODEL%"
+call :run_init_api openai "%PROFILE_NAME%" "%KEY_ENV_NAME%" "" "%MODEL_NAME%"
+if errorlevel 1 goto fail
+goto install
+
+:anthropic_api
+set "PROFILE_NAME=overseer-claude"
+set "KEY_ENV_NAME=ANTHROPIC_API_KEY"
+set "MODEL_NAME=claude-your-model"
+set /p "INPUT_PROFILE=MCP profile name [%PROFILE_NAME%]: "
+if not "%INPUT_PROFILE%"=="" set "PROFILE_NAME=%INPUT_PROFILE%"
+set /p "INPUT_KEY_ENV=Secret env var name [%KEY_ENV_NAME%]: "
+if not "%INPUT_KEY_ENV%"=="" set "KEY_ENV_NAME=%INPUT_KEY_ENV%"
+set /p "INPUT_MODEL=Model name [%MODEL_NAME%]: "
+if not "%INPUT_MODEL%"=="" set "MODEL_NAME=%INPUT_MODEL%"
+call :run_init_api anthropic "%PROFILE_NAME%" "%KEY_ENV_NAME%" "" "%MODEL_NAME%"
+if errorlevel 1 goto fail
+goto install
+
+:codex_cli
+set "PROFILE_NAME=overseer-codex-cli"
+set /p "INPUT_PROFILE=MCP profile name [%PROFILE_NAME%]: "
+if not "%INPUT_PROFILE%"=="" set "PROFILE_NAME=%INPUT_PROFILE%"
+call :run_init_cli "%PROFILE_NAME%" codex "[\"exec\"]"
+if errorlevel 1 goto fail
+goto install
+
+:claude_cli
+set "PROFILE_NAME=overseer-claude-cli"
+set /p "INPUT_PROFILE=MCP profile name [%PROFILE_NAME%]: "
+if not "%INPUT_PROFILE%"=="" set "PROFILE_NAME=%INPUT_PROFILE%"
+call :run_init_cli "%PROFILE_NAME%" claude "[\"-p\"]"
+if errorlevel 1 goto fail
+goto install
+
+:run_init_api
+call :ensure_build
+if errorlevel 1 goto fail
+set "EXPERT=%~1"
+set "PROFILE=%~2"
+set "ENV_NAME=%~3"
+set "URL=%~4"
+set "MODEL=%~5"
+set "BASE_ARGS=--print --name "%PROFILE%" --expert %EXPERT% --repo-root "%REPO_ROOT%" --api-key-env "%ENV_NAME%" --model "%MODEL%""
+if not "%TEST_COMMAND%"=="" set "BASE_ARGS=%BASE_ARGS% --test-command "%TEST_COMMAND%""
+if not "%URL%"=="" set "BASE_ARGS=%BASE_ARGS% --base-url "%URL%""
+node dist\index.js init %BASE_ARGS% --target codex > "%OUT_CODEX%"
+if errorlevel 1 goto fail
+node dist\index.js init %BASE_ARGS% --target json > "%OUT_JSON%"
+if errorlevel 1 goto fail
+node dist\index.js instructions --print --mcp-name "%PROFILE%" > "generated\OVERSEER_AGENT_INSTRUCTIONS.md"
+if errorlevel 1 goto fail
+exit /b 0
+
+:run_init_cli
+call :ensure_build
+if errorlevel 1 goto fail
+set "PROFILE=%~1"
+set "CLI_COMMAND=%~2"
+set "CLI_ARGS=%~3"
+set "LOGIN_FLAG="
+if /I "%CLI_COMMAND%"=="codex" (
+  echo Checking Codex CLI config...
+  node dist\index.js codex-config
+  if errorlevel 1 exit /b 1
+)
+echo Login is stored by the CLI (%CLI_COMMAND%), not by overseer-mcp.
+echo Re-running this configurator does not delete an existing CLI login.
+echo If you are already logged in, answer no.
+echo If login hangs, close this window and run "%CLI_COMMAND% login" manually in a terminal.
+set /p "RUN_LOGIN=Run CLI login now? yes/no [no]: "
+if /I "%RUN_LOGIN%"=="yes" set "LOGIN_FLAG=--run-login"
+set "BASE_ARGS=--print --name "%PROFILE%" --expert cli --repo-root "%REPO_ROOT%" --cli-command "%CLI_COMMAND%" --cli-args "%CLI_ARGS%" %LOGIN_FLAG%"
+if not "%TEST_COMMAND%"=="" set "BASE_ARGS=%BASE_ARGS% --test-command "%TEST_COMMAND%""
+node dist\index.js init %BASE_ARGS% --target codex > "%OUT_CODEX%"
+if errorlevel 1 goto fail
+node dist\index.js init %BASE_ARGS% --target json > "%OUT_JSON%"
+if errorlevel 1 goto fail
+node dist\index.js instructions --print --mcp-name "%PROFILE%" > "generated\OVERSEER_AGENT_INSTRUCTIONS.md"
+if errorlevel 1 goto fail
+exit /b 0
+
+:install
+echo.
+echo Generated MCP configs:
+echo   Codex operator: %CD%\%OUT_CODEX%
+echo   JSON operator:   %CD%\%OUT_JSON%
+echo   Local MCP JSON:  %REPO_ROOT%\%REPO_JSON%
+echo Generated operator instructions:
+echo   %CD%\generated\OVERSEER_AGENT_INSTRUCTIONS.md
+echo.
+if exist "%REPO_ROOT%\%REPO_JSON%" (
+  copy "%REPO_ROOT%\%REPO_JSON%" "%REPO_ROOT%\%REPO_JSON%.backup-%RANDOM%" >nul
+)
+copy "%OUT_JSON%" "%REPO_ROOT%\%REPO_JSON%" >nul
+echo Copied local MCP JSON to %REPO_ROOT%\%REPO_JSON%
+echo.
+echo JSON config preview:
+type "%OUT_JSON%"
+echo.
+
+echo.
+set /p "INSTALL_CODEX=If your cheap operator is Codex, append Codex MCP config to project .codex\config.toml with backup? yes/no [no]: "
+if /I not "%INSTALL_CODEX%"=="yes" goto done
+
+if not exist "%REPO_ROOT%\.codex" mkdir "%REPO_ROOT%\.codex"
+if exist "%REPO_ROOT%\.codex\config.toml" (
+  copy "%REPO_ROOT%\.codex\config.toml" "%REPO_ROOT%\.codex\config.toml.backup-%RANDOM%" >nul
+)
+echo.>> "%REPO_ROOT%\.codex\config.toml"
+type "%OUT_CODEX%" >> "%REPO_ROOT%\.codex\config.toml"
+echo Installed in %REPO_ROOT%\.codex\config.toml
+echo Restart Codex or run /mcp to verify the server appears.
+goto done
+
+:done
+echo.
+set /p "APPEND_AGENTS=Append operator instructions to repo AGENTS.md with backup? yes/no [no]: "
+if /I "%APPEND_AGENTS%"=="yes" (
+  if exist "%REPO_ROOT%\AGENTS.md" (
+    copy "%REPO_ROOT%\AGENTS.md" "%REPO_ROOT%\AGENTS.md.backup-%RANDOM%" >nul
+  )
+  echo.>> "%REPO_ROOT%\AGENTS.md"
+  type "generated\OVERSEER_AGENT_INSTRUCTIONS.md" >> "%REPO_ROOT%\AGENTS.md"
+  echo Appended instructions to %REPO_ROOT%\AGENTS.md
+)
+echo.
+echo Next checks:
+echo   1. Ensure the secret env var exists in the environment that starts your agent.
+echo   2. For Qoder / Mimo / Cline / Roo, import or paste %REPO_ROOT%\%REPO_JSON% into that client's MCP settings.
+echo   3. Restart the agent or reload MCP servers.
+echo   4. Ask the agent to list MCP tools and look for get_plan, consult_expert, request_review.
+exit /b 0
+
+:ensure_build
+echo.
+echo Installing dependencies and building overseer-mcp...
+call npm install
+if errorlevel 1 exit /b 1
+call npm run build
+if errorlevel 1 exit /b 1
+exit /b 0
+
+:fail
+echo.
+echo ERROR: configuration failed.
+echo If this happened during CLI login, run the login command manually in a normal terminal to see the full error.
+echo Example: codex login
+echo.
+echo Press any key to close this window.
+pause >nul
+exit /b 1

package/dist/config.js

@@ -0,0 +1,150 @@
+import path from "node:path";
+import { findGitRoot } from "./repo/findRoot.js";
+import { AnthropicProvider } from "./providers/anthropic.js";
+import { CliProvider } from "./providers/cli.js";
+import { OpenAICompatibleProvider } from "./providers/openaiCompatible.js";
+/** Returns a copy of `config` with `repoRoot` overridden to `newRoot`. */
+export function withRepoRoot(config, newRoot) {
+    const resolved = findGitRoot(newRoot) ?? path.resolve(newRoot);
+    if (resolved === config.repoRoot)
+        return config;
+    return { ...config, repoRoot: resolved };
+}
+function required(env, name) {
+    const value = env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+function apiKey(env) {
+    if (env.OVERSEER_API_KEY) {
+        return env.OVERSEER_API_KEY;
+    }
+    const keyEnvName = env.OVERSEER_API_KEY_ENV;
+    if (!keyEnvName) {
+        throw new Error("Missing required environment variable: OVERSEER_API_KEY");
+    }
+    const value = env[keyEnvName];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${keyEnvName} (from OVERSEER_API_KEY_ENV)`);
+    }
+    return value;
+}
+function optionalNumber(env, name, fallback) {
+    const raw = env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid ${name}: expected a positive number`);
+    }
+    return parsed;
+}
+function optionalNumberAllowZero(env, name, fallback) {
+    const raw = env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`Invalid ${name}: expected a non-negative number`);
+    }
+    return parsed;
+}
+function optionalPositiveNumber(env, name) {
+    const raw = env[name];
+    if (!raw)
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid ${name}: expected a positive number`);
+    }
+    return parsed;
+}
+function optionalTemperature(env) {
+    const raw = env.OVERSEER_TEMPERATURE;
+    if (!raw)
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 2) {
+        throw new Error("Invalid OVERSEER_TEMPERATURE: expected a number between 0 and 2");
+    }
+    return parsed;
+}
+function parseCliArgs(raw) {
+    if (!raw)
+        return [];
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return [];
+    if (trimmed.startsWith("[")) {
+        const parsed = JSON.parse(trimmed);
+        if (!Array.isArray(parsed) || !parsed.every((item) => typeof item === "string")) {
+            throw new Error("Invalid OVERSEER_CLI_ARGS: expected a JSON string array");
+        }
+        return parsed;
+    }
+    return trimmed.split(/\s+/);
+}
+function buildProvider(env, repoRoot) {
+    const provider = required(env, "OVERSEER_PROVIDER");
+    const maxTokens = optionalPositiveNumber(env, "OVERSEER_MAX_OUTPUT_TOKENS");
+    const temperature = optionalTemperature(env);
+    if (provider === "openai") {
+        return new OpenAICompatibleProvider({
+            apiKey: apiKey(env),
+            baseUrl: env.OVERSEER_BASE_URL ?? "https://api.openai.com/v1",
+            model: required(env, "OVERSEER_MODEL"),
+            maxTokens,
+            temperature,
+        });
+    }
+    if (provider === "anthropic") {
+        return new AnthropicProvider({
+            apiKey: apiKey(env),
+            baseUrl: env.OVERSEER_BASE_URL,
+            model: required(env, "OVERSEER_MODEL"),
+            maxTokens,
+            temperature,
+        });
+    }
+    if (provider === "cli") {
+        const promptVia = env.OVERSEER_CLI_PROMPT_VIA ?? "stdin";
+        if (promptVia !== "stdin" && promptVia !== "arg") {
+            throw new Error("Invalid OVERSEER_CLI_PROMPT_VIA: expected stdin or arg");
+        }
+        return new CliProvider({
+            command: required(env, "OVERSEER_CLI_COMMAND"),
+            args: parseCliArgs(env.OVERSEER_CLI_ARGS),
+            promptVia,
+            timeoutMs: optionalNumber(env, "OVERSEER_CLI_TIMEOUT_MS", 120000),
+            cwd: repoRoot,
+        });
+    }
+    throw new Error("Invalid OVERSEER_PROVIDER: expected openai, anthropic, or cli");
+}
+export function loadConfig(env = process.env, cwd = process.cwd()) {
+    // Prefer the first candidate that actually sits inside a git repo. VSCODE_CWD
+    // can point at the IDE install directory (e.g. ...\Programs\Trae) rather than
+    // the open project, which would root the expert at the wrong/empty repo.
+    const candidates = [env.OVERSEER_REPO_ROOT, env.VSCODE_CWD, cwd].filter((value) => Boolean(value));
+    let repoRoot;
+    for (const candidate of candidates) {
+        const root = findGitRoot(candidate);
+        if (root) {
+            repoRoot = root;
+            break;
+        }
+    }
+    repoRoot ??= path.resolve(env.OVERSEER_REPO_ROOT ?? cwd);
+    return {
+        provider: buildProvider(env, repoRoot),
+        repoRoot,
+        testCommand: env.OVERSEER_TEST_COMMAND,
+        maxFiles: optionalNumber(env, "OVERSEER_MAX_FILES", 12),
+        planFullFiles: optionalNumberAllowZero(env, "OVERSEER_PLAN_FULL_FILES", 0),
+        maxFileBytes: optionalNumber(env, "OVERSEER_MAX_FILE_BYTES", 65536),
+        maxDiffBytes: optionalNumber(env, "OVERSEER_MAX_DIFF_BYTES", 262144),
+        testTimeoutMs: optionalNumber(env, "OVERSEER_TEST_TIMEOUT_MS", 300000),
+    };
+}