Skip to content
Back to search

outsourcerer

Make your AI coding tools work as one team. Orchestrate jobs across Claude, Codex, Cursor, Devin, local models, and more. Carry your setup + context, track every cost.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/alexgreensh/outsourcerer with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/alexgreensh/outsourcerer'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alexgreensh--outsourcerer/badge.svg)](/listings/alexgreensh--outsourcerer)

HTML

<a href="/listings/alexgreensh--outsourcerer"><img src="/api/listings/alexgreensh--outsourcerer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 31 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "outsourcerer",
  4. "owner": {
  5. "name": "Alex Greenshpun",
  6. "url": "https://github.com/alexgreensh"
  7. },
  8. "metadata": {
  9. "description": "The Outsourcerer marketplace: make your AI coding tools work as one team, with your current session staying the orchestrator.",
  10. "pluginRoot": "./plugins"
  11. },
  12. "plugins": [
  13. {
  14. "name": "outsourcerer",
  15. "source": "./plugins/outsourcerer",
  16. "description": "Make your AI coding tools work as one team. Route jobs across Claude Code, Codex, Cursor, Devin, Gemini, OpenRouter, and local models; carry the user's setup into delegated work; track limits and cash cost; and convene multi-model reviews.",
  17. "category": "productivity",
  18. "tags": [
  19. "delegation",
  20. "offload",
  21. "orchestration",
  22. "codex",
  23. "cursor",
  24. "devin",
  25. "gemini",
  26. "openrouter",
  27. "cost-optimization"
  28. ]
  29. }
  30. ]
  31. }
README.md · README · 432 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="readme-assets/hero.png" alt="Outsourcerer, delegate the grind, keep the glory" width="900">
  3. [![Version](https://img.shields.io/github/v/release/alexgreensh/outsourcerer?color=8A5CF6&label=version)](https://github.com/alexgreensh/outsourcerer/releases)
  4. [![Security: repo-forensics](https://img.shields.io/badge/security-repo--forensics%20·%20500%2B%20patterns-2ea44f)](https://github.com/alexgreensh/repo-forensics)
  5. [![License: PolyForm Noncommercial 1.0.0](https://img.shields.io/badge/license-PolyForm--Noncommercial--1.0.0-blue)](LICENSE)
  6. ![Works across](https://img.shields.io/badge/works%20across-Claude%20Code%20·%20Codex%20·%20Cursor%20·%20Droid%20·%20Antigravity%20·%20Devin%20·%20Hermes%20·%20Warp%20·%20Cline%20·%20Pi%20·%20Grok%20Bot-8A5CF6)
  7. ![macOS](https://img.shields.io/badge/macOS-supported-000000?logo=apple&logoColor=white)
  8. ![Linux](https://img.shields.io/badge/Linux-supported-FCC624?logo=linux&logoColor=black)
  9. ![Windows](https://img.shields.io/badge/Windows-Git%20Bash%2C%20no%20WSL-0078D6?logo=windows&logoColor=white)
  10. ![Copilot](https://img.shields.io/badge/🚗%20copilot-auto%20·%20manual%20·%20hybrid-2ea44f)
  11. ![Model advisory](https://img.shields.io/badge/model%20advisory-benchmark--scored-2ea44f)
  12. ### Your AIs, working as one team.
  13. Outsourcerer is the orchestrator for every AI you already have. It splits the work, hands each piece to the right model in the right harness, keeps long jobs running, checks the results, and shows you the receipt.
  14. </div>
  15. ---
  16. You already have a fleet: Claude Code, Codex, Gemini, maybe Cursor or Devin, a stack of OpenRouter credits. Each is brilliant at something the others aren't, and they sit in separate rooms. **Outsourcerer gets them working as one team, with you as the boss.**
  17. The session you're talking to becomes the lead. It hands the grind to a budget model, the hard calls to a frontier one, the private stuff to a model on your own machine, and brings your own skills along to whichever engine does the job. No server, no framework to learn. You just talk to it.
  18. ## Three things a router can't do
  19. **It orchestrates.** One crew across Claude Code, Codex, Cursor, Droid, Antigravity, Devin, Hermes, Warp, Cline, Pi and even your Grok Bot. Specialists run side by side, advisors argue out a plan before anyone builds, and every job is watched until it ends with a clear result.
  20. **It runs long.** A big job lives on disk as a plan, not in a chat. Close the laptop, lose the session, come back tomorrow: the plan picks up where it stopped. Decisions that are yours wait for you, and a watcher can wake you when something needs you.
  21. **It proves the work.** Nothing grades its own homework. "Done" means your tests passed and the proof is saved. Reviews are tied to the exact build they approved, and merges land one at a time and get tested again.
  22. And it saves you money and limits along the way. That's what happens when the grind stops running on your most expensive model. *(The [Tab](#the-tab-a-receipt-you-can-actually-believe) shows exactly how much.)*
  23. ---
  24. ## You talk. The sorcerer handles it.
  25. No flags to memorize, no routing tables. You say what you want; it checks what you actually have installed, picks the right engine for each piece, and offers the cheap path before spending a cent it didn't have to.
  26. <img src="readme-assets/convo-offload.svg" alt="Terminal: you ask to map auth; Outsourcerer offloads it to GLM-5.2 on OpenRouter and logs a real saving to your Tab" width="100%">
  27. If something isn't installed, it tells you the one command to fix it. You just say yes.
  28. ---
  29. ## What you can ask it to do
  30. - **Run a whole build as a plan.** Advisors plan it, a worker builds it, another model reviews it, and it merges only after your tests pass on the result. Survives crashes and restarts. *(Its own section below.)*
  31. - **Run agents in parallel.** Fan out a whole multi-agent gauntlet (a QA sweep, a per-module review, N reviewers) across any backend at once with `fanout`, watch them live, and collect every finding into one file. No 16-session bootstrap tax.
  32. - **Convene advisors.** Have several stronger models review a plan or a diff in parallel, improve it, and only proceed on consensus.
  33. - **Bring your setup along.** Hand the job your skills (`--with skills=x`, or `all`) and the delegate works with the whole skill - docs, references, scripts - on tool-capable harnesses; text-only lanes get the complete docs with executables honestly marked NOT TRANSFERRED. MCP servers on request (`--with mcp=`), on the Claude lanes, verified present before launch.
  34. - **Loop it until it's green.** Try, check, try again on a cheap model, with *your* tests deciding when it's done. *(Its own section below.)*
  35. - **Offload the grind.** Repo mapping, mechanical refactors, running the test suite, big searches. Cheap model does it; your main agent stays the boss.
  36. - **Generate images.** **GPT-image first** on your Codex plan (keyless, no API credits), then nano-banana or an OpenRouter image model. *(Every illustration in this README was rendered exactly this way, by Outsourcerer, keyless, `$0` cash.)*
  37. - **Review anything visual.** Screenshots, UI, design, handed to Gemini, keyless on your Antigravity login.
  38. - **Run it on your own machine.** A local model on Ollama or LM Studio runs the job on your hardware: `$0`, no tokens burned, fully private. *(Its own section below.)*
  39. - **Find the cheap seats.** Ask what's free or cheap right now across your platforms (`suggest`). It reads each catalog live, so it keeps up as new models drop (a fresh free model on Devin or OpenRouter shows up on its own).
  40. - **See what you're saving.** The **Tab** shows real spend vs your frontier model, per lane.
  41. - **Ban a model for good.** `exclude add fable` and it is never picked again, by you or by the router. (It can't see a model an engine picks silently on its own.)
  42. All of it in plain language. The commands underneath are the sorcerer's, not yours.
  43. ---
  44. ## It doesn't just call another model. It brings your whole workshop.
  45. When Outsourcerer hands a job to a different engine or harness, that engine doesn't show up empty-handed. Grant a skill and the delegate gets the skill's **whole bundle** - SKILL.md plus its references, scripts, and assets - staged on disk next to the job on tool-capable harnesses, and synced into the harness's skills home on Devin. Text-only lanes can't run scripts, so they get the skill's complete documentation serialized into the prompt, with every script and asset explicitly listed as NOT TRANSFERRED - and a grant that can't fit or resolve refuses the dispatch instead of arriving half-loaded. MCP servers come along when you ask for them (`--with mcp=`), on the Claude lanes today; anywhere a grant can't make the trip, Outsourcerer says so up front instead of letting the delegate pretend. It's the difference between borrowing a stranger's bare laptop and having your own, fully set up, wherever the work happens to run.
  46. ---
  47. ## Advisors: bring the big brains in, several at once
  48. <img src="readme-assets/section-advisors.png" alt="The sorcerer presenting work to a council of glowing advisor models that confer and reach consensus" width="100%">
  49. Delegation runs both directions. Push work *down* to a cheaper model to save money, or pull the **strongest** models *up* as advisors to make the work better, and not just one:
  50. - **Convene a panel.** Spin up **several strong models in parallel**, one from each subscription if you like (say Sol on Codex, Fable on Claude, Hy3 on OpenRouter), to review a plan or a diff at the same time.
  51. - **Act only on consensus.** Outsourcerer greenlights the work when the panel agrees; a split is the signal to bring the decision back to you.
  52. - **Improve, don't just grade.** Ask the advisors to rewrite the weak parts and fold in each other's fixes, not merely flag them.
  53. <img src="readme-assets/convo-advisor.svg" alt="Terminal: you ask if the plan is sound; Outsourcerer convenes Sol, Fable and Hy3 in parallel across your subscriptions and greenlights on 3/3 consensus" width="100%">
  54. A second, differently-wired head at the right moment is where the real leverage is. Three of them, agreeing, is even better.
  55. ---
  56. ## Run a whole crew at once
  57. <img src="readme-assets/section-orchestrator.png" alt="The ink-drop sorcerer directing a circle of neon constellation creatures on gold connecting lines" width="100%">
  58. Outsourcerer runs the whole summoning itself. It decides what to delegate, picks the lane and model on live benchmarks, keeps every delegate interactive and steerable, supervises the fleet, and refuses to end a turn while work is live and waiting on you. The orchestrator contract lives in the skill, so the session you talk to owns the plan and the outcome rather than handing choices back to you.
  59. **It also works underneath an orchestrator you already have.** Point yours at Outsourcerer and keep it: your orchestrator decides what to delegate and how results get approved, and Outsourcerer runs the assignments. It dispatches each specialist across any provider, then watchdog-supervises every job through to a **classified** end (done / blocked / timed-out) instead of a silent exit, salvages the recoverable ones with a bounded verify→retry loop, tracks the spend, and hands the results back as parsable state. Not just a router: a layer that dispatches, verifies, and accounts for every delegate, whoever is casting.
  60. **OpenCode models ask before paid use.** Use `--provider opencode -m <model>`; a terminal asks for consent and scripts need `--spend-ok`. OpenCode Go also asks when its billing cannot be proven.
  61. **Your Grok Bot can join the crew (beta).** Grok Bot has no chat API, but its routines take a webhook. Give Outsourcerer the webhook and `--provider grokbot` hands the bot a task. The bot works on its own cloud computer, pushes a branch to your repo, and Outsourcerer brings the result back. Nothing merges until you say so. The repo also ships a Cursor plugin manifest, so a bot can install Outsourcerer and hand work to the lanes set up on its computer. This direction is new and not yet proven on a live bot.
  62. **Point it at any agent library and it just works.** A folder of role definitions, your own or a library like [agency-agents](https://github.com/msitarzewski/agency-agents), runs as a squad with `fanout --agents ./crew`, one supervised job per specialist. You never have to edit those files. The whole crew runs on a sensible cheap lane by default, and you add routing only if you want it, three ways, editing files last:
  63. - **Nothing.** Any library runs unmodified on the default lane, one receipt, one `status --json`.
  64. - **A one-line name map.** `--route 'security-*=glm-5.2, *architect*=sol, *=haiku'` sends each specialist to its own engine by name, no file edits.
  65. - **Frontmatter**, if you own the files: `model:` / `effort:` / `lane:` per agent.
  66. Precedence is unambiguous: global `-m` wins, then `--route`, then frontmatter, then the default. `--task "..."` drops your task into every role, so a pure library of personalities runs against your repo with zero edits.
  67. ```bash
  68. outsourcerer fanout --agents ./engineering --route 'security-*=glm-5.2, *=haiku' --task "audit auth" --worktree
  69. outsourcerer fanout status <id> --json # squad state as a stable JSON envelope your code parses
  70. outsourcerer fanout collect <id> # every result in one place, then: outsourcerer cleanup <id>
  71. ```
  72. `--worktree` runs each editing specialist in its **own disposable git worktree** so parallel edits never collide; worktrees are preserved after the run (never auto-deleted), and `cleanup` refuses to bin one that has unmerged work unless you `--force`. Every job is watchdog-supervised so it ends **classified** (done / blocked / timed-out), carries your skills via `--with` (MCP on the Claude lanes), and lands on the **Tab**. You keep the persona, the decomposition, the merge policy; the sorcerer runs the fleet.
  73. For sandboxed worktree lanes, opt in to `outsourcerer session approve-policy safe --all` to approve eligible prompts once and log each decision. The default remains off. Sealed test runs can be approved automatically only with an OS isolation tool and a root-owned runner whose path is not writable by the delegate. Without isolation, a manual run requires `--allow-unisolated`.
  74. `outsourcerer handover --check-context` prepares a handover when the current orchestrator reaches 150,000 input tokens. Set `OSRC_ORCH_CTX_MAX` to change the threshold; keep the current orchestrator supervising until its replacement has adopted the work and armed supervision.
  75. Supervision refreshes a project-and-limits snapshot every 10 minutes. Change the interval with `OSRC_SUPERVISE_TICK_SECS`; the snapshot lives in `$OSRC_HOME/supervise/<owner-id>/hub.json`.
  76. `supervise --auto done,limits` can dispatch a verified READY queue item to the reviewer automatically. Verdicts and other judgment calls still wake the orchestrator.
  77. Reviewer rotation defaults to two reviews or 35% context, configurable with `OSRC_REVIEW_ROTATE_K` and `OSRC_REVIEW_CTX_MAX`. An idle managed reviewer with an empty queue is retired after 50 minutes (`OSRC_REVIEW_IDLE_MIN`).
  78. Set `OSRC_LEAN_LAUNCH=1` for Claude sessions and delegates to retain `CLAUDE.md` while using strict MCP configuration without `--bare`. Interactive sessions start with no MCP servers unless `OSRC_LEAN_MCP_CONFIG` names a JSON config containing the required servers. Installed skills and plugins are still inherited.
  79. Re-review briefs use the previous reviewed commit and findings. Use `review next --final` for the full base-to-head merge review; per-round reports use `## Round <number>` sections.
  80. **It wakes you when a job ends.** Every launch prints a `wait` line. Start it as a background command and Claude Code or Codex gets a turn the moment the work finishes, with the result in hand. **On the roadmap:** pushed completion events for chat bots, and a richer receipt (cost + branch/SHA) in that same JSON.
  81. ---
  82. ## Big jobs that outlive the chat
  83. Big jobs are a chain of steps: map the code, decide the approach, build it, review it, merge it. Keep that chain in one chat and it's gone the moment the session ends. Outsourcerer keeps it on disk as a **plan**, so the work survives crashes, restarts, and tomorrow morning.
  84. One run, start to finish:
  85. > *"Add per-user rate limiting. Plan it out and build it."*
  86. - Two advisors on different models (say Sol on Codex and Opus on Claude) work out an approach **at the same time**, and a third folds the best of both into one plan.
  87. - A budget model builds it in its own git worktree, and it isn't done until your tests pass.
  88. - A different model checks the build against the plan. FAIL sends it back with the reason, PASS moves on.
  89. - The change merges, your tests run again on the merged result, and you get the receipt.
  90. That's `council-build`, one of the ready-made shapes. A real plan is wider than one line of steps: anything that doesn't wait on something else runs **side by side**, each on its own engine, in its own worktree. Three features at once, a reviewer per feature, a scout mapping the next one. What makes it hold up:
  91. - **Every worker starts briefed.** It gets the spec, what the steps before it found, and the calls you made along the way.
  92. - **"Done" means proven.** A worker saying it's finished doesn't count. Code needs real commits, your tests passing and a clean secret scan, and the proof is saved.
  93. - **Your decisions are part of the plan.** "Pick the winner" or "approve this migration" becomes a step that waits for you, then passes your answer downstream. Give it a default and a deadline, and a plan left running goes ahead with the default if you're away.
  94. - **Retries fit the failure.** A network blip retries the same model, a broken model moves to the next one on the list, and a run that was too big is retried as a smaller piece. The same failure twice comes to you for a re-plan.
  95. - **Merges wait their turn.** Work lands one change at a time, your tests run again on the merged result, and your uncommitted edits are never touched.
  96. - **More shapes.** `spec-build` writes a spec, plans it, builds it and checks it against the spec. `best-of-n` has several models build the same thing side by side, compares them, and lets you pick the winner.
  97. ```bash
  98. outsourcerer plan new rate-limit --repo .
  99. outsourcerer flow run council-build --plan rate-limit --var goal="Add per-user rate limiting" --var check="make test"
  100. outsourcerer plan run --plan rate-limit # run it again any time to pick up where it stopped
  101. ```
  102. You will rarely type these. Say "plan this out and build it" and the sorcerer sets it up. The full guide is in [`references/factory.md`](plugins/outsourcerer/skills/outsourcerer/references/factory.md).
  103. **Worktrees are not a security sandbox.** They keep files apart, but a worker on a lane without an OS sandbox runs with your user's rights, including outside its worktree. Use sandboxed verbs and lanes for untrusted work.
  104. ---
  105. ## Loops: send the laps somewhere cheaper
  106. <img src="readme-assets/section-loops.png" alt="The sorcerer on a glowing ring track, passing a task orb to a constellation creature that hands it back, past a checkpoint gate, an hourglass beside it" width="100%">
  107. Loops are not new. Claude Code has them and they work. What is expensive is **who runs the laps**.
  108. A loop is the same few moves over and over: try it, check it, try again. That is the least interesting work in software and the most repetitive, and if your frontier model is doing it, you are paying archmage rates for someone to re-run your test suite.
  109. So the sorcerer sends the laps somewhere cheap and keeps the judgment. A budget model does the trying. **Your** tests do the checking. The archmage decides what "done" means and reads the result when it lands.
  110. Nothing grades its own homework. The check is a real command, your suite, your build, your linter, because a model asked whether it succeeded will say yes.
  111. And "loop" is not one shape. Build-until-the-tests-pass is the one everybody knows. It is not the only one worth sending away:
  112. - a machine can settle it, so it runs until the check goes green
  113. - you do not know how much work is in there, so it sweeps until nothing is left
  114. - nothing can check it, but you can tell good from bad, so it tries several ways and keeps the best
  115. - quality is a matter of degree, so one model drafts and another critiques until it stops improving
  116. - the *plan* is the risky part, so two advisors argue it out before a cheap model touches a file
  117. You will not type any of it. Describe the problem and the sorcerer picks the shape and offers it:
  118. > *"That's a build-until-the-tests-pass job. Want me to hand it to GLM and keep re-running your suite until it's green? I'll stop if it stalls, or after twenty minutes."*
  119. Yes is the whole interface. And it will talk you *out* of a loop when there is nothing that can verify the result, because at that point a loop is just a model marking its own homework in a circle.
  120. While it runs, you can watch it: which attempt it is on, how long it has been going, and what is still failing. A loop you cannot see inside is a bet, not a tool.
  121. It stops when the check goes green. It stops when the same failures come back twice, because a loop that is not converging is an expensive way to be wrong. It stops when the time you gave it runs out. It even stops when the *check itself* hangs, which used to be the one way a bounded loop could quietly run forever.
  122. And stopping early is not a dead end. It keeps the task, the check, and the exact thing that broke last, so you can send it back around from where it stopped instead of paying twice for ground it already covered.
  123. ---
  124. ## See your whole fleet in one honest view
  125. <img src="readme-assets/section-fleet.png" alt="The little wizard reviewing rows of his hat-tipped helper sprites, each holding a glowing gold name-card, one topped with a gold bell because it is waiting on him, with constellation creatures working at desks in the corners" width="100%">
  126. **Your AI sessions work in separate rooms.** A Claude Code tab here, three jobs you handed to cheaper engines there, one of them quietly waiting on your approval. Every tool shows you its own sessions. None of them show you all of them at once. `fleet` does.
  127. ```bash
  128. outsourcerer fleet ls # every session you're running, one honest list
  129. outsourcerer fleet name # real names from real work, not "session-a3f2"
  130. outsourcerer fleet show <id>
  131. ```
  132. **One list, and it tells the truth.** Every Claude Code session plus every job Outsourcerer ran for you, each with a status read from the live process and its own transcript, never a spinner that lies. A session is **Working**, **Waiting on you**, **Done**, or **Stopped mid-task**, so you walk straight to the one that needs you instead of hunting through tabs.
  133. **Real names, not hashes.** `fleet name` reads what each session is actually working on and names it, so `session-71` reads as `Refactor the auth retry path`, cached so the list stays instant.
  134. **It catches the stuck ones, and it reaches you.** Turn on supervision and a background heartbeat watches the fleet, spots a delegate that stalled, never started, or drifted off its pinned model, and either bounds it or **wakes you** through a notifier you set (`OSRC_HEARTBEAT_WAKE`) instead of letting it sit silent for half an hour. The heartbeat verifies its own liveness: it reports itself **armed** only when a real watcher is proven running by pid and start-time, and says so loudly when it is not, so "supervised" never quietly means "unwatched".
  135. Today it covers your Claude Code sessions and the jobs Outsourcerer runs. Seeing sessions other tools launched on their own is next.
  136. ---
  137. ## You decide how much you drive
  138. The first time it wakes up in a session, Outsourcerer shows you what's ready, how much of your token budget is left, and asks one question: how do you want to drive?
  139. - **Auto-pilot.** It takes the wheel. Picks the engine, offloads the grind, conserves your limits, and just tells you what it did. For when you want the work done, not the decisions.
  140. - **You-drive.** Nothing moves without your say-so. It proposes, shows you the cost, and waits. For when the call is yours to own.
  141. - **Hybrid.** You agree once on what it can handle alone (tests, repo-mapping, the mechanical stuff), and it asks about everything else. The sweet spot most people settle into.
  142. Pick once and it remembers. Change your mind in plain language any time ("take the wheel", "ask me first"). And no mode is a trap: safety, cloud consent, and your sign-off on anything risky hold in all three. Beginners aren't dropped at a command line, they're handed a steering wheel and told what each pedal does.
  143. ---
  144. ## Smart about every pick, and every penny
  145. You're already smart about this. Even inside Claude Code you hand the small stuff to Sonnet instead of Opus. Outsourcerer takes that instinct across every engine you have: the right model for each job, prompted the way that model likes, without burning through the limits you need for the hard calls.
  146. ### It knows which model is actually worth it
  147. You shouldn't have to memorize which model is best at what, or keep up with a leaderboard that shuffles every week. Ask Outsourcerer to pick, and it does the homework for you: it reads what the task really is (code? reasoning? a quick errand?), pulls **live benchmark scores** for every model you can reach, weighs quality against what each one actually costs you, and recommends the best *value* for this job, not just the most famous name.
  148. That means a frontier-grade answer on a budget lane when the cheap model genuinely clears the bar, and a premium model only when the task truly earns it. It shows you the score and the reason it chose what it chose, so the pick is never a black box, and you can always overrule it. When it can't reach the live boards, it falls back to a built-in capability map, so the recommendation is never worse than a good default.
  149. This is the same brain your **copilot** uses to choose. In auto-pilot it scores the models, takes the best value, and just proceeds (telling you which and why). In you-drive or hybrid it scores them the same way, then shows you the pick and waits for your nod. The benchmarks drive the choice in every mode; the mode only decides whether it asks first.
  150. ### One spell, tailored to each model
  151. <img src="readme-assets/section-model-aware.png" alt="The sorcerer casting a differently-shaped spell at each of three different model-creatures" width="100%">
  152. The models don't think alike, so Outsourcerer doesn't prompt them alike. The right prompting techniques are **baked in per capability tier**: it frames a task for GPT-5.6 one way, for Fable another, for a genuinely small model a third, each to its strengths. And cheap does not mean dumb: **GLM-5.2, Hy3 and DeepSeek are `capable` tier, frontier capability at a budget price (~Opus-4.8 class)**, so they get the same high-autonomy prompting as the flagships, not a hand-holding work order. You ask in plain language; the sorcerer translates it into the dialect each engine actually responds to. You get better output from the cheap lane than you'd get by sending it the prompt you'd send Claude. Dial thinking depth per task with `--effort`.
  153. ### It watches your fuel gauge, so you never hit empty
  154. You know the feeling: 2pm, deep in a build, and your 5-hour limit taps out. Work stops.
  155. Outsourcerer reads your live usage and, the moment you cross into the danger zone, quietly shifts the heavy lifting off your main model onto a cheaper lane that's still full, and tells you why it did. Your best model stays sharp for the judgment calls instead of getting spent on grep. The wall stops being a surprise you slam into and becomes a corner the sorcerer already saw coming. Different setup, same care: No Devin, and it leans on Codex. Only local models, and it keeps everything on your machine. It conserves with whatever *you* actually have.
  156. ### Run it on your own machine
  157. <img src="readme-assets/section-local.png" alt="The ink-drop sorcerer beside his own glowing wireframe machine, a gold padlock and a gold zero-coin" width="100%">
  158. Point the sorcerer at a local model on Ollama or LM Studio and the whole job runs on your hardware: **`$0`, no tokens burned, nothing leaves the building.** Three reasons people reach for it, all good ones: you just prefer running your own models, you'd rather not spend the tokens, or the code is too sensitive to hand any cloud model. Outsourcerer's `doctor` spots a running local server on its own and offers the private lane, so `run` streams text with zero setup. And when you want the model to actually read your repo and use tools, the agentic path drives it right inside the harness, still local, still keyless. *(The harness plumbing is certified end to end; how much it can chew depends on your local model's own tool-calling.)*
  159. ### The Tab: a receipt you can actually believe
  160. <img src="readme-assets/section-tab.png" alt="The sorcerer writing carefully in a glowing ledger beside a balance scale weighing coins against an hourglass" width="100%">
  161. Most "cost saver" tools show you a number they made up. This one keeps two honest columns, because they aren't the same kind of cost. **Cash** is real money on OpenRouter/API lanes. **Plan limits** are your Codex / Claude / Antigravity / Devin subscription windows: no cash, but finite, so we show what you actually burned of them, never a fake "free."
  162. ```
  163. == The Tab == (real output, 2026-07-10)
  164. runs recorded : 12
  165. cash billed (measured) : $0.002245 REAL per-generation OpenRouter cost, captured on bg runs
  166. cash lanes, est-only : 5 run(s) foreground; run in bg to capture measured $
  167. on your subscription : 3 run(s) $0 cash, spent your ChatGPT / Claude / Antigravity plan limits
  168. ChatGPT plan usage, 5h window: 6% (resets in 4h 32m) · weekly: 1%
  169. note: a $0 cash line is NOT "free", subscription lanes spend finite plan rate limits.
  170. ```
  171. A number on the Tab is only as fresh as its last reading. A subscription window comes from whatever your CLI recorded the last time it ran, which can be hours old if you have been elsewhere, and usage only ever climbs, so an old number quietly reads as headroom you do not have. The sorcerer says how old it is, and won't send work down a lane the reading only *thinks* has room left.
  172. That `$0.002245` is not an estimate. For OpenRouter lanes the Tab reads the **exact per-generation cost** back from the provider after the run, because the harness's own built-in cost number runs roughly **28× high** on cheap lanes. For the subscription lanes it reads the real 5-hour and weekly rate-limit numbers the CLI records after each call. The archmage only gets billed for archmage work, and a no-cash line never pretends a plan lane was free.
  173. ---
  174. ## No wands, just plumbing
  175. Under the robe it's deliberately boring: a self-contained bash script you can read in one sitting. No server, no proxy, no telemetry, nothing resident. It shells out to the CLIs you already have (`claude`, `codex`, `devin`, `agy`), reads **exactly one** key from `~/.env` when a paid lane needs it, and keeps the ledger in a local JSONL on your machine. The magic is in the orchestration decisions, not the machinery, which is exactly where you want it.
  176. **When it goes sideways:** a stalled delegate gets killed by a watchdog and reported with its last progress line, never silently retried against a half-edited tree. Exit codes distinguish *done* / *done-but-unverified* / *blocked*, and "done-but-unverified" is treated as unverified. Before it dispatches, `doctor` preflights your machine, so if a lane's helper is missing it warns you up front instead of letting a delegated model discover it mid-run.
  177. ---
  178. ## How it compares
  179. | | Claude's own subagents | Router / proxy (claude-code-router, LiteLLM) | 🧙 Outsourcerer |
  180. |---|:---:|:---:|:---:|
  181. | Crosses *agents*, not just models | Claude only | model-swap inside one harness | **Codex · Antigravity · Claude Code · Devin · Pi · Grok Bot** |
  182. | Multi-step plans that outlive the session | ✗ | ✗ | ✅ task graph on disk, context hand-off, evidence-checked merge gate |
  183. | Carries your skills to the delegate | ✗ | ✗ | ✅ whole skill bundles on tool lanes; complete docs on text lanes (executables marked NOT TRANSFERRED); MCP on request (Claude lanes) |
  184. | Advisor panel + consensus | ✗ | ✗ | ✅ several top-tier models, act only when they agree |
  185. | Per-model prompting built in | ✗ | ✗ | ✅ tier-aware wrappers |
  186. | Keyless on what you already pay for | Claude sub only | API keys | ✅ your existing subscriptions, or the API key of your choice |
  187. | Shows you the money saved | ✗ | ✗ | ✅ the **Tab**, per lane, vs your frontier model |
  188. | Setup | zero | proxy + routing config | none, you just talk to it |
  189. | Server-side routing at scale | ✗ | ✅ | ✗ this is a local tool, on purpose |
  190. ---
  191. ## Handled with gloves (security)
  192. <img src="readme-assets/section-security.png" alt="The sorcerer in protective gloves guarding a single glowing key behind a ward, keeping it away from open lanes" width="100%">
  193. Audited by [repo-forensics](https://github.com/alexgreensh/repo-forensics) on every release, **every finding triaged by name, no suppressions** ([SECURITY.md](SECURITY.md)). The tool you install and run scans with **zero critical findings**; its flags are background-job supervision, self-locating shell, and one scoped key read. The only "critical" flags belong to the experimental, opt-in local-inference proxy forwarding your prompt to *your own* model on `127.0.0.1` (and its test). No remote exfiltration anywhere, and the [local lane](#run-it-on-your-own-machine) leaves your machine untouched entirely.
  194. - **Keyless by default** where your subscription allows, Gemini/Antigravity, GPT-image, and the native Claude / Codex / Devin lanes. Keyless means **no API key and no cash**, not free: these lanes spend your subscription's finite 5-hour and weekly limits, and the Tab shows how much. Keys are only for the paid OpenRouter lanes.
  195. - **Single-key sourcing.** Only the one key a lane needs is read from `~/.env`, never your whole environment. A budget model never sees a secret it wasn't handed.
  196. - **Tells you the lane and tier on every dispatch** (and the sandbox posture, read-only / can-write), and asks before anything destructive.
  197. - **`:free` models may train on your prompts.** Outsourcerer flags `:free` lanes as may-train and defaults them to least-privilege, so you decide before sensitive context goes down one.
  198. - **Your credentials can't ride along to the cloud.** Before any cloud delegation, a hard-block refuses the route if a real credential file (`.env`, `id_rsa`, `credentials`, …) is anywhere in the working tree, root or nested, and it runs on every call, fails closed, and tells you exactly what left the machine. A local, gitignored `.env.local` does not stop your work: the job runs in a clean copy of your checkout that leaves it behind. Prefer nothing leaves at all? The **local lane** routes to a model on your own machine: no key, no network. See [SECURITY.md](SECURITY.md#your-repo--what-leaves-the-machine).
  199. You can trust one lane in one repo, and nothing wider. Name a lane and the repos you trust it in, and the credential-file block stands down *there* and nowhere else, never for a secret you pasted into a prompt, which is a different decision you did not make. Empty out of the box, so an untouched install is as strict as it ever was, and the disclosure always tells you when the gate stood down. Not an env var: that would leak into every background job you spawn. A file, scoped to the one repo you meant.
  200. ---
  201. ## Get it (30 seconds, per host)
  202. | Your agent | One-time install |
  203. |---|---|
  204. | **Claude Code** | `/plugin marketplace add alexgreensh/outsourcerer` then `/plugin install outsourcerer@outsourcerer` |
  205. | **Antigravity** | `agy plugin import claude-code` (or let Outsourcerer's `parity` mirror it in) |
  206. | **Codex** | `outsourcerer parity-codex` (adds the entry point Codex reads) |
  207. | **Devin** | `outsourcerer parity` (mirrors the skill + your local tools) |
  208. | **Hermes** | `outsourcerer parity-hermes` (symlinks the skill into `~/.hermes/skills`) |
  209. | **Cursor** and **Grok Bot** (beta) | the repo ships a `.cursor-plugin` manifest; a team admin can import the repo into your team plugin marketplace |
  210. Then just talk to it. On first use it runs its own health check and tells you if anything needs installing, with the exact command.
  211. ---
  212. ## Pairs well with
  213. - **[repo-forensics](https://github.com/alexgreensh/repo-forensics).** The security auditor (27 scanners, 500+ patterns) that vets this plugin, and anything else, before you install it. That green badge up top is its verdict.
  214. - **[Token Optimizer](https://github.com/alexgreensh/token-optimizer).** Keeps your main agent's *context* lean while Outsourcerer moves the *work* off it. Two halves of "spend less, do more." (Its calibrated token math is what the Tab uses to price a run.)
  215. <details>
  216. <summary><b>Under the hood</b>, the commands the sorcerer drives for you (you rarely type these)</summary>
  217. <br>
  218. The model alias picks the lane automatically; `--provider` selects a different backend when needed.
  219. | Verb | Does |
  220. |---|---|
  221. | `run` / `research` / `edit` / `yolo` | offload a read / sandboxed investigation / code change / approvals-off change |
  222. | `continue` / `session` | multi-turn follow-ups (Devin) |
  223. | `bg` / `status` / `watch` / `result` / `logs` / `cancel` | background jobs + the liveness watchdog |
  224. | `second-opinion` | consensus-gated re-check |
  225. | `image` | text-to-image (GPT-image preferred → nano-banana → OpenRouter) |
  226. | `tab` / `estimate` | cost ledger + pre-flight quote |
  227. | `suggest` / `deals` | live cheap & free models available per platform right now |
  228. | `doctor` / `models` | health check + live model list |
  229. | `parity` / `parity-codex` / `parity-hermes` | mirror into Devin/Antigravity/Hermes; reverse-bridge into Codex/Droid/Cursor |
  230. | `plan` / `task` / `flow` / `land` | the software factory: durable plans, task hand-off, ready-made flows, the merge gate |
  231. | `exclude` | ban a model or a whole family from every pick |
  232. **Lanes:** `hy3`/`glm-5.2`/`deepseek-*` (OpenRouter, via `cc` or `codex`) ·
  233. `sol`/`terra`/`luna` (Codex native) · `fable`/`opus`/`sonnet`/`haiku` (Claude native) ·
  234. `gemini-pro`/`gemini-flash` (Antigravity, keyless) · `hermes` / `-m <any>` (your Hermes setup, whatever model + provider keys you've configured) · `ollama:<model>`/`local` (your own machine, keyless, `$0`, private) · `gpt-image`/`nano-banana` (images).
  235. Add capability to one offload with `--with skills=<name>` / `--with mcp=<name>`.
  236. </details>
  237. ## Roadmap
  238. <img src="readme-assets/section-roadmap.png" alt="The sorcerer facing a row of magic portals, two open and two still forming in the distance" width="100%">
  239. **Today it drives like a copilot.** It greets you each session, shows your live token budget, and hands you the wheel: **auto-pilot**, **you-drive**, or **hybrid**, then conserves your limits on its own when the session runs hot. And it works across **Claude Code · Codex · Antigravity · Devin · Cursor · Droid · Hermes**, on Mac, Linux, and Windows (Git Bash, no WSL). Next up:
  240. - More harnesses as the frontier expands.
  241. - An OpenRouter server-side subagent lane, and pushed completion events for chat-bot orchestrators.
  242. - *Already shipped:* one `supervise` watcher for every job, session and remote lane, a single-reviewer queue, the Mission Control page (`hub serve`), paid lanes that always ask first, and Claude multi-account lanes in v0.16.0; cloud jobs that run in a clean copy when your secrets are gitignored, plus Codex writes on Windows, in v0.15.3; steadier time limits and launch checks in v0.15.2; default answers for held decisions and retries that fit the failure in v0.15.1; the **Pi** and **Grok Bot** lanes plus Cursor plugin packaging in v0.15.0; the **software factory** (durable plans, automatic context hand-off, a done contract, a serialized merge gate, and ready-made flows) plus a saved model exclude list in v0.14.0; the **`fleet`** view (one honest list of every session you're running, with real names and honest states) in v0.7.0; the **Cline** engine lane in v0.6.4, fully supervised, running on your own Cline setup (your API keys, or a ClinePass subscription for discounted open-weight models like GLM, DeepSeek, and Kimi); **loops** (a bounded try→check→retry cycle run on a cheap external model, verified by your own tests) and per-repo lane trust in v0.4.13; the interactive copilot (auto/manual/hybrid modes + live-limit auto-conservation) and **Cursor**, **Droid**, and the `claudex` lane (your ChatGPT model inside the Claude Code harness) in v0.4.8; reverse bridges so you can drive Outsourcerer *from* Codex, Droid, Cursor, or Hermes too (Hermes goes both ways: delegate to it with `-m <any>`, or drive Outsourcerer from inside a Hermes session via `parity-hermes`); parallel `fanout` (v0.2.0); the local Ollama/LM-Studio lane (v0.3.0); git-worktree isolation, agent-library routing, and machine-readable `status --json` (v0.3.1).
  243. Issues and PRs welcome.
  244. ## Claude accounts
  245. `outsourcerer accounts` lists Claude config directories and their weekly and five-hour headroom. Add one with `outsourcerer accounts add work`, or supply an absolute directory as the third argument. Shared settings, instructions, skills, agents, hooks, plugins, and memory are linked from `~/.claude`; login and live session state remain separate. Follow the printed login instruction yourself. `outsourcerer accounts check work` reports changed or missing links. `outsourcerer accounts rm work` removes the registry entry and links it created, leaving real files and the config directory intact. The `default` account is `~/.claude`.
  246. New Claude lanes prefer subscription accounts with the most known weekly headroom below configured lane caps. Use `--account work` to select one explicitly. Unreadable usage is shown as unknown; an account with unknown usage cannot satisfy a configured cap. Without a cap, the default account can still launch. Each new process keeps its chosen account; running lanes do not move. Console and other per-use accounts require spend consent.
  247. Release note: Anthropic's terms on one person using several personal subscriptions have not been confirmed by us.
  248. ## License
  249. **PolyForm Noncommercial 1.0.0**, plus a written [small business permission](LICENSE-SMALL-BUSINESS.md). Personal, research, education: free. Companies with fewer than 5 people and under $20k/month revenue (whole company, not seats): free. Commercial: [reach out](mailto:me@alexgreenshpun.com).
  250. <details>
  251. <summary>License FAQ</summary>
  252. **Personal / hobby / research / education?** Go for it. No license purchase needed, including your own open-source side projects. What counts is who the work is for, not where it runs: work for your employer is your employer's use, even from home.
  253. **Small business?** If your **whole company** has fewer than 5 people **and** under $20k/month revenue, you get a no-cost commercial license, in writing: [LICENSE-SMALL-BUSINESS.md](LICENSE-SMALL-BUSINESS.md). Both limits apply to the entire organization (including any parent or sister companies), not to how many people install it, so a larger company does not qualify by limiting it to a handful of users. It covers use inside your own business, not reselling it or running it as a service for others.
  254. **Growing into a business?** You get 32 days after you stop qualifying to sort out a commercial license. Past use is fine.
  255. **Larger company?** Contact [Alex Greenshpun](https://linkedin.com/in/alexgreensh) or [me@alexgreenshpun.com](mailto:me@alexgreenshpun.com).
  256. </details>
  257. ---
  258. <div align="center">
  259. Built by [Alex Greenshpun](https://github.com/alexgreensh)
  260. [![LinkedIn](https://img.shields.io/badge/LinkedIn-alexgreensh-0A66C2?logo=linkedin&logoColor=white)](https://linkedin.com/in/alexgreensh)
  261. [![X](https://img.shields.io/badge/X-@alexgreensh-000000?logo=x&logoColor=white)](https://x.com/alexgreensh)
  262. *Delegate the grind. Keep the glory.*
  263. </div>
  264. ## Mission Control
  265. Mission Control shows your projects, running work, decisions, and lane limits in one place. Open it with `outsourcerer mc`.
plugins/outsourcerer/skills/outsourcerer/scripts/lib/perm.sh · Bundled script · 626 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # perm.sh — `--perm safe|default` permission profiles for interactive `session start`,
  3. # plus the session-launch helpers moved here from outsourcerer.sh (file-size ratchet:
  4. # outsourcerer.sh is legacy and may only shrink; new code lives in scripts/lib/).
  5. #
  6. # Loaded by the byte-identical CONTRACT line in outsourcerer.sh directly after
  7. # `OSRC_JOBS="$OSRC_HOME/jobs"`, and again from the real script dir after the factory
  8. # loader (see briefs/LOADER.md — the second line covers sourced mode and symlinked
  9. # invocation, where $SCRIPT_DIR does not point at this file's folder).
  10. #
  11. # osrc_perm_flags <engine> <profile> <workdir>
  12. # Prints the EXTRA launch flags for the profile, one argv element per line.
  13. # profile=default (or an engine with no faithful safe rung) prints NOTHING, so the
  14. # launch is byte-identical to before. Every flag below was verified against the
  15. # engine's own --help / bundled docs — see sessions/2026-11-13-autonomy/out/L5-AUDIT.md.
  16. # ---- moved verbatim from outsourcerer.sh (session-launch helpers) ---------------
  17. _session_launch_error() {
  18. local provider="$1" reason="$2"
  19. die "session start: $provider interactive launch unavailable ($reason). Use '$0 --provider $provider run \"task\"' for one-shot work or '$0 --provider $provider bg run \"task\"' for supervised background work."
  20. }
  21. _session_probe_help() {
  22. local probe_file rc=0 _tmp_base="${TMPDIR:-/tmp}"
  23. probe_file="$(mktemp "${_tmp_base%/}/osrc-session-probe.XXXXXX" 2>/dev/null)" || return 1
  24. _timeout 3 "$@" > "$probe_file" 2>&1 || rc=$?
  25. if [ "$rc" -ne 0 ] || [ ! -s "$probe_file" ]; then
  26. rm -f "$probe_file"
  27. [ "$rc" -ne 0 ] && return "$rc"
  28. return 1
  29. fi
  30. cat "$probe_file"
  31. rm -f "$probe_file"
  32. }
  33. _session_shell_command() {
  34. local arg quoted out=""
  35. for arg in "$@"; do
  36. printf -v quoted '%q' "$arg"
  37. [ -n "$out" ] && out="$out "
  38. out="$out$quoted"
  39. done
  40. printf '%s\n' "$out"
  41. }
  42. # _session_help_has_model_flag <help-text> -> 0 if a model override flag is documented in the FULL
  43. # help text, 1 otherwise. Matches both long (--model <id> / --model=<id>) and short (-m <id> /
  44. # -m, --model <id>) forms, delimited so a flag like --mode or -mode cannot false-positive. This is
  45. # the evidence-based proof behind the general model-pin guard: a lane may only append a model flag
  46. # to an interactive launch when its own CLI documents that flag at the level being invoked. The
  47. # droid bug was an unverified COMMENT asserting "interactive droid accepts --model too" — the flag
  48. # was never in `droid --help`, fell through into the prompt, and the run billed Claude quota on the
  49. # DEFAULT model (claude-opus-5). Verifying the real --help (never truncated) is the only proof.
  50. _session_help_has_model_flag() {
  51. # Here-string, not a pipeline: help text is never truncated, so it can outgrow the pipe buffer
  52. # and `printf | grep -q` would take grep's early-exit SIGPIPE (141) under pipefail as a miss.
  53. grep -Eq -- '--model([ =]|$)|(^|[[:space:],])-m([[:space:],]|$)' <<<"$1"
  54. }
  55. # _session_assert_model_pinnable <provider> <cli> [help-args...] -> probe the real CLI help and
  56. # REFUSE (via _session_launch_error) if no model override flag is documented at the level being
  57. # invoked. Returns 0 silently when the flag is proven present. This is the general guard: a lane
  58. # that cannot PROVE it honors an explicit model must fail loudly, never start on the lane default
  59. # and bill silently. A failed/timed-out probe is also a refusal — "could not prove it" is not "it
  60. # is supported". <help-args> are the subcommand/help args to probe (e.g. `hermes chat --help`).
  61. #
  62. # Uses a GENEROUS timeout (OSRC_SESSION_MODEL_PROBE_SECS, default 8) rather than the 3s
  63. # _session_probe_help cap: this is a once-per-session safety check, and heavy node CLIs (e.g.
  64. # gemini-cli) can take ~5s to print --help on a cold start. A 3s cap falsely refused a lane that
  65. # DOES document -m/--model, which is its own kind of silent breakage. The cost is paid only when a
  66. # model is explicitly pinned (MODEL_EXPLICIT=1), not on every session start.
  67. _session_assert_model_pinnable() {
  68. local provider="$1" cli="$2"; shift 2
  69. local help_text probe_file rc=0 _tmp_base="${TMPDIR:-/tmp}"
  70. probe_file="$(mktemp "${_tmp_base%/}/osrc-mpg.XXXXXX" 2>/dev/null)" || _session_launch_error "$provider" "model-flag probe: could not create a temp file"
  71. _timeout "${OSRC_SESSION_MODEL_PROBE_SECS:-8}" "$cli" "$@" > "$probe_file" 2>&1 || rc=$?
  72. if [ "$rc" -ne 0 ] || [ ! -s "$probe_file" ]; then
  73. rm -f "$probe_file"
  74. _session_launch_error "$provider" "the model-flag help probe for \`$cli $*\` failed or timed out (rc=$rc) — cannot prove interactive model pinning, refusing rather than billing on the lane default"
  75. fi
  76. help_text="$(cat "$probe_file")"; rm -f "$probe_file"
  77. _session_help_has_model_flag "$help_text" \
  78. || _session_launch_error "$provider" "interactive $provider has no model override in \`$cli $*\` (verified against the real CLI --help). A --model/-m token would not be honored and the run would proceed on the lane DEFAULT model, billing silently. Drop -m to use the lane's configured model, or use the lane's exec/delegate path (e.g. '$0 --provider $provider run -m <model> \"task\"') where the flag is documented."
  79. }
  80. # ---- --perm safe|default ---------------------------------------------------------
  81. # Canonical "safe" shell-command prefixes: read-only commands, git read commands, and
  82. # test/lint/build commands. One prefix per line; emitters turn each into the engine's
  83. # native allow syntax. Everything not matching still prompts — the list only removes
  84. # prompts for routine dev work.
  85. #
  86. # Deliberately EXCLUDED (they prompt): env/xargs/parallel/watch/nice/nohup/time/command
  87. # (exec wrappers), awk/perl/ruby/python/node (arbitrary code — only the `-m pytest|unittest`
  88. # forms are listed), make/just/task/tox/nox (task runners), npm exec/npx/bunx/uv/poetry run
  89. # (fetch+exec), curl/wget/ssh/scp/rsync/sftp, docker/kubectl/aws/gcloud/az/terraform/
  90. # vercel/firebase/netlify, psql/mysql/sqlite3/redis-cli/mongosh, tmux/screen/osascript/
  91. # automator/open/launchctl/crontab/at/batch, sudo/doas, git mutating verbs (push/pull/
  92. # fetch/commit/checkout/restore/reset/clean/rebase/merge/am/apply/cherry-pick/revert/
  93. # stash-mutations/worktree add|remove|prune/submodule update|init/bisect/gc/prune/
  94. # update-ref/read-tree/write-tree/commit-tree/mktree/hash-object), tar/unzip/zip/patch/
  95. # cp/mv/ln/install/dd/tee/touch/mkdir/rmdir/chmod/chown/xattr/chflags, less/more/vim/
  96. # nano/emacs/bat/man (interactive — would stall a turn), sed/yq (in-place write forms
  97. # can't be prefix-excluded), sips (--out writes), npm install/i/ci/add/remove/update/
  98. # publish/link, pip install/download, brew install/uninstall, gem install, apt/yum/
  99. # dnf/pacman/zypper entirely, jq kept (no write flags).
  100. #
  101. # Also excluded after review (L5 round 2): printenv (dumps every secret in the
  102. # environment into the delegate's context), defaults read / nvram -p (can print stored
  103. # tokens), mount (bare form lists, but `mount <dev> <dir>` mutates — the prefix emitter
  104. # cannot exclude the arg form), gh api (a later -X DELETE on the same line is not
  105. # excluded by a GET prefix), and commands that never return on their own — ping,
  106. # traceroute, nettop, fs_usage, log stream, syslog, gh run watch, sleep, tail -f (via
  107. # ask rules), log show (unbounded dump) — for the same reason interactive pagers are
  108. # excluded: they would stall the delegate's turn. black/isort write in place by
  109. # default (no read-only form to allow); prettier/eslint/ruff keep their read-only
  110. # defaults and their write flags are ask-listed instead.
  111. #
  112. # Prefix-write holes verified live in a scratch repo and removed: `git remote -v`
  113. # (its ` *` tail accepts `git remote -v prune|update` — prune RAN, verified), bare
  114. # `git reflog` (`git reflog expire|drop` mutate), and both `git symbolic-ref` forms
  115. # (`git symbolic-ref [--short] HEAD <ref>` WRITES HEAD — verified rc=0). git's own
  116. # action-conflict guard rejects the smuggled combos on the kept entries
  117. # (`branch -a -d`, `tag -l -d`, `config -l --add`, `worktree list prune` all error).
  118. _osrc_perm_safe_cmds() {
  119. cat <<'EOF'
  120. ls
  121. cat
  122. head
  123. tail
  124. grep
  125. egrep
  126. fgrep
  127. rg
  128. ag
  129. fd
  130. eza
  131. exa
  132. wc
  133. file
  134. stat
  135. readlink
  136. realpath
  137. basename
  138. dirname
  139. pwd
  140. echo
  141. printf
  142. which
  143. whereis
  144. type
  145. date
  146. uname
  147. hostname
  148. whoami
  149. id
  150. arch
  151. nproc
  152. locale
  153. tree
  154. du
  155. df
  156. ps
  157. lsof
  158. netstat
  159. jq
  160. sort
  161. uniq
  162. cut
  163. tr
  164. column
  165. diff
  166. cmp
  167. md5
  168. shasum
  169. cksum
  170. true
  171. false
  172. sw_vers
  173. find
  174. git status
  175. git diff
  176. git log
  177. git show
  178. git blame
  179. git grep
  180. git ls-files
  181. git ls-tree
  182. git ls-remote
  183. git rev-parse
  184. git rev-list
  185. git describe
  186. git shortlog
  187. git merge-base
  188. git name-rev
  189. git cherry
  190. git show-branch
  191. git count-objects
  192. git fsck
  193. git cat-file
  194. git verify-commit
  195. git verify-tag
  196. git stash list
  197. git stash show
  198. git worktree list
  199. git submodule status
  200. git remote show
  201. git remote get-url
  202. git branch --show-current
  203. git branch --list
  204. git branch -a
  205. git tag -l
  206. git tag --list
  207. git reflog show
  208. git config --get
  209. git config --get-all
  210. git config --list
  211. git config -l
  212. git var
  213. git version
  214. gh pr view
  215. gh pr list
  216. gh pr checks
  217. gh pr diff
  218. gh issue view
  219. gh issue list
  220. gh run list
  221. gh run view
  222. gh release view
  223. gh release list
  224. gh repo view
  225. npm test
  226. npm run test
  227. npm run lint
  228. npm run build
  229. npm run typecheck
  230. npm run check
  231. npm ls
  232. npm list
  233. npm outdated
  234. npm explain
  235. npm why
  236. npm view
  237. npm fund
  238. npm search
  239. yarn test
  240. yarn lint
  241. yarn build
  242. yarn typecheck
  243. yarn run test
  244. yarn run lint
  245. yarn run build
  246. yarn run typecheck
  247. yarn list
  248. yarn info
  249. yarn why
  250. pnpm test
  251. pnpm lint
  252. pnpm build
  253. pnpm typecheck
  254. pnpm run test
  255. pnpm run lint
  256. pnpm run build
  257. pnpm run typecheck
  258. pnpm run check
  259. pnpm ls
  260. pnpm list
  261. pnpm why
  262. pytest
  263. py.test
  264. python -m pytest
  265. python3 -m pytest
  266. python -m unittest
  267. python3 -m unittest
  268. cargo test
  269. cargo build
  270. cargo check
  271. cargo clippy
  272. go test
  273. go build
  274. go vet
  275. go list
  276. dotnet test
  277. dotnet build
  278. mvn test
  279. mvn verify
  280. mvn compile
  281. mvn package
  282. ./mvnw test
  283. ./mvnw verify
  284. ./mvnw compile
  285. ./mvnw package
  286. gradle test
  287. gradle build
  288. gradle check
  289. ./gradlew test
  290. ./gradlew build
  291. ./gradlew check
  292. mix test
  293. swift test
  294. swift build
  295. deno test
  296. deno check
  297. deno lint
  298. bun test
  299. rspec
  300. phpunit
  301. php artisan test
  302. jest
  303. vitest
  304. mocha
  305. ava
  306. cypress run
  307. playwright test
  308. eslint
  309. prettier
  310. ruff check
  311. mypy
  312. pyright
  313. tsc --noEmit
  314. pip list
  315. pip show
  316. pip freeze
  317. pip3 list
  318. pip3 show
  319. pip3 freeze
  320. gem list
  321. gem contents
  322. brew list
  323. brew info
  324. brew search
  325. brew leaves
  326. brew deps
  327. brew cat
  328. plutil -p
  329. plutil -lint
  330. codesign -dv
  331. xcodebuild -list
  332. system_profiler
  333. ioreg
  334. kextstat
  335. vm_stat
  336. log stats
  337. diskutil list
  338. diskutil info
  339. diskutil apfs list
  340. hdiutil info
  341. hdiutil imageinfo
  342. qlmanage -m
  343. spctl --status
  344. spctl -a -vv
  345. csrutil status
  346. fdesetup status
  347. pmset -g
  348. EOF
  349. }
  350. # Ask-listed patterns: matched commands PROMPT (not allow, not deny) even when an allow
  351. # prefix would cover them. Covers the dangerous corners INSIDE allowed families:
  352. # find -delete/-exec/-ok/-fprint/-fls, output-file writers (--out*, sort -o is left to
  353. # Claude's own path guard), exec-via-flag commands (fd -x/-X/--exec, rg/ag --pre/
  354. # --pager/--hostname-bin, git grep -O / --open-files-in-pager, sort
  355. # --compress-program), formatter/test-runner write+stall flags (prettier --write,
  356. # eslint --fix/-o, ruff --fix, go/dotnet/cargo output-dir flags, --watch/--ui/--debug/
  357. # --pdb interactive modes, tail -f, lsof +r, gh --watch, playwright --ui/--debug),
  358. # secret exposure (ps env forms), and .git writers (git fsck --lost-found).
  359. #
  360. # Claude Code rule order is deny -> ask -> allow and a matching ask rule prompts even
  361. # when a MORE SPECIFIC allow rule also matches — there is no specificity tiebreak
  362. # (code.claude.com/docs/en/permissions). Verified live on Claude Code 2.1.323
  363. # (claude-haiku-5-5, -p): `ls && rm -rf dir`, `ls && touch f`, `echo $(touch f)`,
  364. # `cat f | sh`, and `echo x > f` were all stopped by Claude's OWN command parser
  365. # before the allow rules mattered — it splits compounds, refuses unverifiable nested
  366. # commands, and asks before any file creation even inside the workdir. The `>`/`<`
  367. # ask rules were therefore redundant and are dropped: they cost the commonest
  368. # delegate command (`2>&1 | tail`, `2>/dev/null`) a prompt for no added safety.
  369. # What remains asks on flags the parser does not model as separate operations.
  370. _osrc_perm_ask_patterns() {
  371. printf '%s\n' \
  372. 'Bash(*-delete*)' 'Bash(*-exec*)' 'Bash(*-ok*)' 'Bash(*-fprint*)' 'Bash(*-fls*)' 'Bash(*--out*)' \
  373. 'Bash(*--ext-diff*)' 'Bash(*--textconv*)' \
  374. 'Bash(fd *-x*)' 'Bash(fd *-X*)' 'Bash(fd *--exec*)' \
  375. 'Bash(rg *--pre*)' 'Bash(rg *--hostname-bin*)' 'Bash(rg *--pager*)' 'Bash(ag *--pager*)' \
  376. 'Bash(sort *--compress-program*)' \
  377. 'Bash(git grep *-O*)' 'Bash(git grep *--open-files-in-pager*)' 'Bash(git fsck *--lost-found*)' \
  378. 'Bash(tail *-f*)' 'Bash(tail *-F*)' 'Bash(tail *--follow*)' \
  379. 'Bash(ps e*)' 'Bash(ps * e*)' 'Bash(ps *-E*)' \
  380. 'Bash(lsof *+r*)' \
  381. 'Bash(*--watch*)' 'Bash(*--pdb*)' \
  382. 'Bash(playwright *--ui*)' 'Bash(playwright *--debug*)' 'Bash(vitest *--ui*)' \
  383. 'Bash(go build *-o*)' 'Bash(go test *-o*)' 'Bash(dotnet *-o *)' 'Bash(cargo *--target-dir*)' \
  384. 'Bash(eslint *--fix*)' 'Bash(eslint *-o *)' \
  385. 'Bash(prettier *--write*)' 'Bash(ruff *--fix*)'
  386. }
  387. # Script-name families that also appear in colon form (`npm run test:unit`, `yarn build:prod`).
  388. # The ` *` space form misses the colon, so emitters add the `:*` trailing-wildcard variant.
  389. _osrc_perm_colon_families() {
  390. printf '%s\n' \
  391. 'npm run test' 'npm run lint' 'npm run build' 'npm run typecheck' 'npm run check' \
  392. 'yarn test' 'yarn lint' 'yarn build' 'yarn typecheck' \
  393. 'yarn run test' 'yarn run lint' 'yarn run build' 'yarn run typecheck' \
  394. 'pnpm test' 'pnpm lint' 'pnpm build' 'pnpm typecheck' \
  395. 'pnpm run test' 'pnpm run lint' 'pnpm run build' 'pnpm run typecheck' 'pnpm run check'
  396. }
  397. # _osrc_perm_claude_args -> --allowedTools rules + --settings ask-list for `claude` safe mode.
  398. # Rule syntax per code.claude.com/docs/en/permissions: `Bash(<prefix>)` exact,
  399. # `Bash(<prefix> *)` prefix+args; `Edit(./**)`/`Write(./**)` scope file edits to the
  400. # session workdir (cwd). Read/Grep/Glob are always-safe tool names.
  401. _osrc_perm_claude_args() {
  402. local p s a asks=''
  403. printf '%s\n' '--allowedTools' 'Read' 'Grep' 'Glob' 'Edit(./**)' 'Write(./**)'
  404. while IFS= read -r p; do
  405. [ -n "$p" ] || continue
  406. printf 'Bash(%s)\n' "$p"
  407. printf 'Bash(%s *)\n' "$p"
  408. done < <(_osrc_perm_safe_cmds)
  409. while IFS= read -r s; do
  410. [ -n "$s" ] || continue
  411. printf 'Bash(%s:*)\n' "$s"
  412. done < <(_osrc_perm_colon_families)
  413. printf '%s\n' '--settings'
  414. while IFS= read -r a; do asks="$asks\"$a\","; done < <(_osrc_perm_ask_patterns)
  415. asks="${asks%,}"
  416. printf '{"permissions":{"ask":[%s]}}\n' "$asks"
  417. }
  418. # _osrc_perm_gemini_args <workdir> -> --approval-mode auto_edit only: gemini-cli's edit
  419. # tools auto-approve while shell commands keep the default approval behavior.
  420. #
  421. # A generated [[rule]] policy file was tried and WITHDRAWN (L5 round 2, review finding
  422. # 3): commandRegex is tested against the tool-call JSON args, and the round-1 regexes
  423. # both stopped at the first quoted string (`[^\"]*`) and anchored only the first word,
  424. # so `echo "hi" > ~/.zshrc`, `find . -delete`, `ls && rm -rf ~`, `cat a | sh` and
    • Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
    • Line 436 on GitHub
  425. # `sort -o /tmp/x` all evaluated as allow. gemini-cli refuses OAuth on this machine,
  426. # so no live session can prove a corrected policy — per the review, emit only
  427. # auto_edit until one does.
  428. _osrc_perm_gemini_args() {
  429. printf '%s\n' '--approval-mode' 'auto_edit'
  430. }
  431. # osrc_perm_apply_launch <provider> <lane> — append the safe-profile flags to the
  432. # SESSION_LAUNCH array built by a _session_launch_* adapter. Called from
  433. # _session_launch_adapter after the lane fn returns. Engines whose safe rung is a
  434. # SUBSTITUTION rather than an append (cx: --approve-for-me replaces -s) handle
  435. # PERM_PROFILE inside their own adapter; everything else lands here.
  436. # A flag-generation failure is fatal: silently launching with default permissions
  437. # under a "safe" banner is exactly the lie the banner exists to prevent.
  438. osrc_perm_apply_launch() {
  439. local provider="$1" lane="$2" eng _pa _flags
  440. eng="${SESSION_LAUNCH_ENGINE:-$lane}" # separate stmt: `local a= b=$a` expands before assign
  441. [ "${PERM_PROFILE:-default}" = "default" ] && return 0
  442. type osrc_perm_flags >/dev/null 2>&1 \
  443. || _session_launch_error "$provider" "--perm $PERM_PROFILE needs scripts/lib/perm.sh, which is missing from this install"
  444. _flags="$(osrc_perm_flags "$eng" "$PERM_PROFILE" "$PWD")" \
  445. || _session_launch_error "$provider" "--perm safe flag generation failed for engine '$eng'"
  446. while IFS= read -r _pa; do [ -n "$_pa" ] && SESSION_LAUNCH+=("$_pa"); done <<< "$_flags"
  447. # Explicit rc0: a no-rung engine yields empty _flags, and the while/read above
  448. # returns 1 at EOF — without this the ADAPTER reports failure for exactly the
  449. # engines safe mode is supposed to launch unchanged (droid/hermes/cline/pi).
  450. return 0
  451. }
  452. # osrc_perm_desc <engine> -> one-line honest description of what `safe` actually does
  453. # for that engine, or rc 1 when the engine has no faithful safe rung. "safe" is NOT
  454. # one thing across engines (review finding 4): Claude gets an explicit allow-list;
  455. # devin/codex/cursor get the engine's OWN auto-approval rung, where a model or server
  456. # classifier judges each action — not a list; agy gets the vendor's auto mode;
  457. # gemini-cli gets edit-tools-only auto-approval. The launch banner prints this so the
  458. # receipt never claims an allow-list the engine does not have.
  459. osrc_perm_desc() {
  460. case "$1" in
  461. devin|dv) printf '%s' "devin --permission-mode smart (MODEL-JUDGED: a fast model auto-runs what it judges safe; installs, mutating git, rm/sudo, dotenv/keys still prompt)" ;;
  462. cx|codex) printf '%s' "codex --approve-for-me (MODEL-JUDGED: approval requests route through automatic review; replaces -s workspace-write)" ;;
  463. cc|claude) printf '%s' "claude --allowedTools allow-list + ask rules (EXPLICIT LIST: read-only/git-read/test-build commands + workspace edits; deletes, exec-flags, redirects and everything else still prompt)" ;;
  464. cursor) printf '%s' "cursor --auto-review (CLASSIFIER-JUDGED: a server classifier auto-runs safe tool calls)" ;;
  465. agy|antigravity) printf '%s' "agy --mode auto (engine auto mode per vendor docs — not an allow-list)" ;;
  466. gemini|gmnative|gm) printf '%s' "gemini-cli --approval-mode auto_edit (edit tools auto-approve; shell commands still ask)" ;;
  467. *) return 1 ;;
  468. esac
  469. }
  470. # _osrc_perm_banner <provider> — print the honest [perm] line after a safe-profile
  471. # launch is built. No-op unless PERM_PROFILE=safe. Engines with no faithful rung get
  472. # an explicit "launched default" line instead of a false success banner.
  473. _osrc_perm_banner() {
  474. [ "${PERM_PROFILE:-default}" = "safe" ] || return 0
  475. local _pb_eng="${SESSION_LAUNCH_ENGINE:-$1}" _pb_desc
  476. if _pb_desc="$(osrc_perm_desc "$_pb_eng" 2>/dev/null)"; then
  477. printf '>>> [perm] safe — %s. Anything outside still prompts.\n' "$_pb_desc" >&2
  478. else
  479. printf '>>> [perm] safe: no faithful safe rung for %s; launched with DEFAULT permissions (everything prompts).\n' "$1" >&2
  480. fi
  481. }
  482. # osrc_perm_string_suffix <engine> <profile> -> prints " <flag> <flag>..." with each
  483. # flag %q-quoted, for launch vectors carried as ONE shell string (tmux send-keys,
  484. # winpty launch.bash is an array and does NOT use this, respawn-pane). default or a
  485. # no-rung engine prints nothing; rc 1 when safe was requested but osrc_perm_flags is
  486. # unavailable, so callers can die loudly instead of launching unprotected.
  487. osrc_perm_string_suffix() {
  488. local eng="$1" prof="${2:-default}" _pa out=""
  489. [ "$prof" = "safe" ] || return 0
  490. type osrc_perm_flags >/dev/null 2>&1 || return 1
  491. while IFS= read -r _pa; do [ -n "$_pa" ] && out="$out $(printf '%q' "$_pa")"; done < <(osrc_perm_flags "$eng" "$prof" "$PWD")
  492. printf '%s' "$out"
  493. }
  494. # _osrc_perm_restore_profile <session-id> — set the global PERM_PROFILE from the
  495. # session's latest start record (registry field 5, written by _session_registry_append
  496. # at launch). Relaunch/effort-relaunch rebuild the command from scratch, so without
  497. # this a `--perm safe` session silently comes back with default permissions. Records
  498. # written before L5 lack the field -> env/default. Not local: the relaunch_fn lanes
  499. # and the registry append read the global.
  500. _osrc_perm_restore_profile() {
  501. local _ps_saved
  502. _ps_saved="$(_session_record "$1" 2>/dev/null | cut -f5)"
  503. case "$_ps_saved" in safe|default) PERM_PROFILE="$_ps_saved" ;; *) PERM_PROFILE="${PERM_PROFILE:-${OSRC_PERM_PROFILE:-default}}" ;; esac
  504. case "$PERM_PROFILE" in safe|default) ;; *) PERM_PROFILE=default ;; esac
  505. }
  506. # ---- session relaunch vectors (moved from outsourcerer.sh for the size ratchet) ---
  507. # Both read the global PERM_PROFILE, which _session_control_relaunch restores from
  508. # the session's registry record before calling _session_relaunch_command.
  509. # _session_cc_uuid_valid <id> -> 0 only for a real claude sessionId shape (a
  510. # UUID). --resume takes the value verbatim, so the check must be strict: the
  511. # looser _external_session_id_valid charset accepts a leading-dash id like
  512. # --dangerously-skip-permissions, which claude would read as a flag, and any
  513. # process the delegate starts can plant a matching ~/.claude/sessions file.
  514. _session_cc_uuid_valid() {
  515. printf '%s\n' "${1:-}" | grep -qE '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
  516. }
  517. # _session_cc_resume_id <tmux-pane> -> the pane claude's sessionId for
  518. # `claude --resume <id>`, or nothing (= the caller falls back to --continue).
  519. # Live proof first: ~/.claude/sessions/*.json maps the running claude pid to its
  520. # sessionId via _fleet_cc_session_for_pane; the registry start record's
  521. # cc_session_id is the fallback for a pane whose session file is already gone.
  522. # --resume beats --continue because --continue picks the newest conversation in
  523. # the folder, which may be a DIFFERENT session's when two claude panes share a
  524. # cwd; the id pins this pane's own conversation.
  525. _session_cc_resume_id() {
  526. local pane="$1" pid cwd match sid
  527. pid="$(tmux display-message -p -t "$pane" '#{pane_pid}' 2>/dev/null)"
  528. cwd="$(tmux display-message -p -t "$pane" '#{pane_current_path}' 2>/dev/null)"
  529. if [ -n "$cwd" ]; then cwd="$(cd "$cwd" 2>/dev/null && pwd -P)" || cwd=""; fi
  530. if [ -n "$pid" ] && [ -n "$cwd" ]; then
  531. match="$(_fleet_cc_session_for_pane "$pid" "$cwd" 2>/dev/null)" || match=""
  532. sid="${match%%$'\t'*}"
  533. if _session_cc_uuid_valid "$sid"; then printf '%s\n' "$sid"; return 0
  534. elif [ -n "$sid" ]; then echo "session resume: ignoring live claude session id '$sid' (not a UUID; the id shape may have changed)" >&2; fi
  535. fi
  536. sid="$(_state_jsonl_read "$OSRC_SESSION_REGISTRY" 2>/dev/null | jq -r --arg id "$pane" 'select(.event=="start" and .session_id==$id) | .cc_session_id // empty' | tail -1)"
  537. if _session_cc_uuid_valid "$sid"; then printf '%s\n' "$sid"
  538. elif [ -n "$sid" ]; then echo "session resume: ignoring registry cc_session_id '$sid' (not a UUID; the id shape may have changed)" >&2; fi
  539. }
  540. # _session_cc_resume_for <prov> <pane> -> the resume id for cc/claude panes,
  541. # empty for every other provider (and whenever no id can be proven).
  542. _session_cc_resume_for() {
  543. case "$1" in cc|claude) _session_cc_resume_id "$2" 2>/dev/null ;; esac
  544. }
  545. # Relaunch command for `session effort` on a cc session (claude honors effort via
  546. # MAX_THINKING_TOKENS plus the session-scoped --effort flag). $3 is the pane's
  547. # claude sessionId when known: --resume <id> pins THIS conversation, --continue
  548. # (the fallback) picks the newest in the folder and can grab a sibling pane's.
  549. # --perm safe adds the same allow-list/ask-rules suffix session start emits
  550. # (default -> empty suffix). No effort -> rc1 (the caller leaves it intact).
  551. _session_relaunch_cc() {
  552. local tokens suffix flag resume="${3:-}"
  553. tokens="$(_effort_thinking_tokens "$2")"
  554. [ -n "$tokens" ] || return 1
  555. suffix="$(osrc_perm_string_suffix cc "${PERM_PROFILE:-default}")" || return 1
  556. flag="$(_cc_effort_flag "$2")"
  557. printf 'env MAX_THINKING_TOKENS=%q -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT -u CLAUDE_CODE_SESSION_ID -u CLAUDE_CODE_CHILD_SESSION -u CLAUDE_CODE_EXECPATH claude --model %q' "$tokens" "$1"
  558. if _session_cc_uuid_valid "$resume"; then printf ' --resume %q' "$resume"
  559. elif [ -n "$resume" ]; then printf ' --continue'; echo "session relaunch: resume id '$resume' is not a UUID; falling back to --continue" >&2
  560. else printf ' --continue'; fi
  561. printf '%s' "$suffix"
  562. if [ -n "$flag" ] && _session_cc_effort_supported; then printf ' --effort %q' "$flag"; fi
  563. }
  564. # Relaunch command for codex/cx. --perm safe applies the SAME substitution as
  565. # session start: --approve-for-me replaces `-s workspace-write` (the two conflict).
  566. _session_relaunch_cx() { # <model> <effort> -> relaunch command string
  567. local cid code_mode_host sbx
  568. cid="$(resolve_model_row "$1")"; cid="${cid%%|*}"; [ -n "$cid" ] || cid="$1"
  569. _validate_model_token "$cid"
  570. code_mode_host="$(_codex_code_mode_host_flag)" || return 1
  571. sbx="-s workspace-write"
  572. [ "${PERM_PROFILE:-default}" = "safe" ] && sbx="--approve-for-me"
  573. printf 'codex -m %q %s -c features.code_mode_host=%q -c model_reasoning_effort=%q' "$cid" "$sbx" "$code_mode_host" "$2"
  574. }
  575. # osrc_perm_flags <engine> <profile> <workdir> — see header. Engine keys accept both
  576. # provider tokens and lane names; gm resolves to its vehicle via OSRC_GEMINI_VEHICLE
  577. # or a PATH probe when called directly.
  578. osrc_perm_flags() {
  579. local engine="$1" profile="$2" workdir="${3:-$PWD}"
  580. [ "$profile" = "safe" ] || return 0
  581. case "$engine" in
  582. devin|dv) printf '%s\n' '--permission-mode' 'smart' ;;
  583. cx|codex) printf '%s\n' '--approve-for-me' ;;
  584. cc|claude) _osrc_perm_claude_args ;;
  585. cursor) printf '%s\n' '--auto-review' ;;
  586. agy|antigravity) printf '%s\n' '--mode' 'auto' ;;
  587. gemini|gmnative|gm)
  588. # The gm lane's safe flags depend on its VEHICLE: agy has --mode auto; gemini-cli
  589. # gets --approval-mode auto_edit (edit tools auto-approve, shell commands still
  590. # ask). SESSION_LAUNCH_ENGINE normally carries the resolved vehicle; direct calls
  591. # resolve it the same way _session_launch_gm does.
  592. local veh="${SESSION_LAUNCH_ENGINE:-${OSRC_GEMINI_VEHICLE:-}}"
  593. [ -n "$veh" ] || { command -v agy >/dev/null 2>&1 && veh=agy; }
  594. [ -n "$veh" ] || { command -v gemini >/dev/null 2>&1 && veh=gemini; }
  595. [ -n "$veh" ] || veh=gemini
  596. case "$veh" in
  597. agy) printf '%s\n' '--mode' 'auto' ;;
  598. *) _osrc_perm_gemini_args "$workdir" ;;
  599. esac ;;
  600. *) : ;; # droid/hermes/cline/pi/warp/etc: no faithful per-launch safe rung
  601. esac
  602. }
plugins/outsourcerer/skills/outsourcerer/scripts/run-or-codex.sh · Bundled script · 65 lines · 1 finding marked
  1. #!/bin/bash
  2. # Run Codex CLI against ANY OpenRouter model, NATIVE OpenAI Responses API, no shim.
  3. # Inline -c overrides only: your normal Codex (ChatGPT-sub) sessions are untouched;
  4. # config.toml is never modified.
  5. #
  6. # Usage:
  7. # run-or-codex.sh [model] tui # interactive TUI (attach in tmux)
  8. # run-or-codex.sh [model] exec "the task" # headless one-shot, clean stdout (offload)
  9. #
  10. # model OpenRouter model id (default: tencent/hy3:free)
  11. #
  12. # Key is sourced from ~/.env (OPENROUTER_API_KEY), never inline.
  13. MODEL="${1:-tencent/hy3:free}"
  14. MODE="${2:-tui}"
  15. export PATH="$HOME/.local/bin:$PATH"
  16. # Guard: this script routes through OpenRouter ONLY. The BARE ChatGPT-subscription aliases/ids
  17. # (sol/terra/luna and bare gpt-5.x) are NOT served by OpenRouter and 400 here. Match only bare tokens
  18. # -- NOT provider-qualified slugs like `openai/gpt-5.6-sol`, which ARE valid OpenRouter models (no
  19. # leading-`*` glob, so a slug containing a `/` is never matched). Point the caller at the native path.
  20. case "$MODEL" in
  21. */*) : ;; # provider-qualified slug (e.g. openai/gpt-5.6-sol) -> a real OpenRouter id, allow it through
  22. sol|terra|luna|gpt-5|gpt-5.*)
  23. echo "ERROR: '$MODEL' is a bare ChatGPT-subscription model; it 400s on OpenRouter." >&2
  24. echo " For an interactive NATIVE-codex session (your ChatGPT auth) use:" >&2
  25. echo " outsourcerer --provider codex session start -m $MODEL" >&2
  26. echo " (--provider must precede the subcommand. This script is only for OpenRouter model ids.)" >&2
  27. exit 2 ;;
  28. esac
  29. # Extract ONLY the OpenRouter key, never allexport the whole ~/.env into Codex's env.
  30. _l="$(grep -E '^[[:space:]]*(export[[:space:]]+)?OPENROUTER_API_KEY=' "$HOME/.env" 2>/dev/null | tail -n1)"
  31. OPENROUTER_API_KEY="${_l#*OPENROUTER_API_KEY=}"; OPENROUTER_API_KEY="${OPENROUTER_API_KEY%\"}"; OPENROUTER_API_KEY="${OPENROUTER_API_KEY#\"}"; OPENROUTER_API_KEY="${OPENROUTER_API_KEY%\'}"; OPENROUTER_API_KEY="${OPENROUTER_API_KEY#\'}"; export OPENROUTER_API_KEY
  32. if [ -z "$OPENROUTER_API_KEY" ]; then
  33. echo "ERROR: OPENROUTER_API_KEY not found in ~/.env" >&2
  34. exit 1
  35. fi
  36. # OpenRouter provider, passed per-invocation (NOT persisted to config.toml).
  37. # wire_api MUST be "responses", Codex 0.144+ dropped Chat Completions;
  38. # OpenRouter serves a Responses-compatible endpoint at /api/v1/responses.
  39. # ISOLATION: --ignore-user-config so this OpenRouter run does not LOAD your live ~/.codex config
  40. # (above all its mcp_servers, which can wedge a headless run demanding interactive OAuth). The OR
  41. # provider below fully defines the lane; auth is the env key, not config. Opt out: OSRC_CODEX_USER_CONFIG=1.
  42. IUC=(); [ "${OSRC_CODEX_USER_CONFIG:-0}" = "1" ] || IUC=(--ignore-user-config)
  43. OR=(
  44. -c model_provider=openrouter
  45. -c 'model_providers.openrouter.name="OpenRouter"'
  46. -c 'model_providers.openrouter.base_url="https://openrouter.ai/api/v1"'
  47. -c 'model_providers.openrouter.env_key="OPENROUTER_API_KEY"'
  48. -c 'model_providers.openrouter.wire_api="responses"'
  49. )
  50. if [ "$MODE" = "exec" ]; then
  51. shift 2 2>/dev/null
  52. echo "==> Codex (headless) on OpenRouter model: $MODEL" >&2
  53. exec codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox \
  54. ${IUC[@]+"${IUC[@]}"} "${OR[@]}" -m "$MODEL" "$@"
  55. else
  56. # NOTE: --ignore-user-config is an `exec`-only flag; the interactive TUI is human-driven (a human
  57. # can answer an MCP OAuth prompt), so the headless-only wedge doesn't apply here. Don't pass IUC.
  58. echo "==> Codex (interactive TUI) on OpenRouter model: $MODEL"
  59. exec codex "${OR[@]}" -m "$MODEL"
  60. fi

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.