outsrc

Good work takes a team. outsrc lets a Grok Bot hand coding tasks to Claude Code, Codex or Grok Build on your computer. Each task runs in its own git worktree, and the result comes back to an inbox.

Site: https://outsrc.ing

Install

Add the Outsrc bot from Bot Exchange. The listing is not live yet. Once installed, the bot walks you through setup on your computer.

This repository is the open-source harness the bot runs. You only need it to build your own bot, contribute, or run outsrc by hand.

Related MCP server: opencode-mcp

Security

outsrc is not a sandbox. Agents run as you, on your computer, in the repositories you allow. Review their work before you ship it. Details: https://outsrc.ing/security.md

To report a vulnerability, see SECURITY.md.

What outsrc adds over calling the CLIs directly

• Only the repositories you chose, each job in its own git worktree and branch. Your checkout stays untouched.

• No inherited secrets. Jobs get only PATH, HOME, USER, LANG, TMPDIR and TERM from your environment.

• Read-only reviews. Reviews never get the flags that skip approvals, and plugin reviews never get --write.

• Reviewing a branch does not run the branch. Hooks and MCP servers in a branch's .claude/, .codex/, .grok/, .cursor/ or .mcp.json run commands as soon as a CLI opens the folder. For reviews, outsrc keeps those files out of the worktree (git still shows them in the diff), Claude loads only your own settings and no MCP servers, and repository setup commands do not run. Tested with a branch that tried each route: called directly, Claude ran its hooks and MCP server, and Codex ran its MCP server when the repository was trusted. Through outsrc, none ran.

• Prompts stay text. outsrc passes -- before the prompt, so a message starting with -- cannot set an option.

• No chains. Jobs run with OUTSRC_JOB=1, and an outsrc server started inside a job refuses send.

• Separate callers. Each caller sees only its own threads.

• Private state. ~/.outsrc is created readable by you only.

• Bounded jobs. By default at most 4 jobs at once and 2 hours per run; the owner can change both (see Settings). stop signals a process only if it is still the job outsrc started.

• Pinned vendor engines, checked daily for upstream changes.

Running the harness yourself

It needs Node 22.12 or later (22.x, 24.x or 26+), git, and at least one of the claude, codex or grok CLIs, logged in.

npm install -g outsrc
outsrc init

Install it globally rather than running it through npx: agents launch the installed copy, and the npx cache moves. Upgrade with npm install -g outsrc@latest.

outsrc init is safe to rerun and keeps existing settings. It:

1. Checks Node and git, finds the installed CLIs and checks each is logged in.

2. Downloads the pinned Codex and Grok plugin engines into ~/.outsrc/engines/. Claude Code is not needed for this. --no-plugins calls the CLIs directly instead.

3. Asks which repositories agents may work in. Repositories are added only by running outsrc on this computer; MCP callers cannot add them.

4. Asks for the limits: how many jobs may work at once, and how long a run may take (see Settings).

5. Writes ~/.outsrc/config.toml and reports on each target.

6. Offers to register outsrc as an MCP server with each installed CLI.

For agents and scripts, outsrc init --json --repo <path> [--repo <path>] [--local claude,codex,grok] [--max-jobs <n|unlimited>] [--max-run-minutes <n|unlimited>] prints one JSON event per line and exits with code 3 when a person has to act, such as logging in to a CLI. Rerun it after that step. Without --local, nothing is registered. A settings event lists the limits, repositories and targets so the agent can review them with the owner.

outsrc doctor rechecks the configuration. OUTSRC_HOME moves the state directory away from ~/.outsrc, which outsrc keeps readable by you only.

Settings

outsrc config lists every setting with its current value, its default and what it means. outsrc config set <key> <value> changes one, and outsrc config unset <key> restores the default or removes an entry. Each change is checked against the whole configuration before the file is written, the previous file is kept as config.toml.bak, and running MCP servers pick it up on their next call. MCP callers can read settings with the settings tool but cannot change them: only someone who can run outsrc on this computer can.

Values are read as JSON when they parse (true, 14, [["npm","ci"]]) and as text otherwise. Aliases may contain dots: outsrc config set repos.outsrc.ing.auto_commit true works.

Unlimited is allowed, and outsrc config prints what it risks. With no job cap, a looping or confused bot can start many agents at once, slowing the computer and running up usage and rate limits. With no time limit, a stuck agent (waiting for input, a test runner in watch mode, a loop) runs until someone stops it.

Callers

Each client connects as a named caller: outsrc-mcp --caller grok, or --caller <id> on CLI commands. A caller sees and controls only its own threads. Another caller's thread answers exactly like one that does not exist.

Every job runs with OUTSRC_JOB=1 in its environment. An outsrc server started inside a job refuses send, so a delegated agent cannot hand work on to another agent. Only the caller that started a job can send more work.

How a conversation works

1. Call list_repos and list_targets.

2. Call send with repo, target and message. Optional: model, effort, kind (task, review or adversarial_review), ref (the branch, tag or commit to start from) and base (what a review compares against).

3. Poll inbox at its retry_after_seconds. The delay grows from 30 seconds to 5 minutes as a run ages, and working runs include recent log lines.

4. If the status is needs_input, the agent stopped with a question. Answer with send({thread_id, message}). outsrc resumes the same vendor session in the same worktree. Finished threads accept follow-ups the same way.

Pass a stable request_id when retrying a send. The same request returns the original thread and run; the same ID with different content is an error.

Tools

The MCP tools and the CLI commands return the same JSON.

CLI only: outsrc config set and unset change settings, outsrc prune deletes finished worktrees past their retention period, outsrc migrate imports threads from earlier versions, and outsrc plugins checks the plugin engines.

Repository options

[[repos]]
alias = "example"
path = "/absolute/path/example"
setup = [["npm", "ci"]]   # runs once in a new task worktree, before the first run
auto_commit = true        # commit a successful task's changes
retention_days = 30       # let prune remove finished worktrees after 30 days

All three options are optional. A failed setup fails the run. outsrc does not copy .env files or other untracked files into worktrees. Running and waiting threads are never pruned, and saved results outlive their worktrees.

Targets

A target is one agent outsrc can start. list_targets shows what is configured, and config.example.toml has a starting point.

permissions = "auto" lets a task edit files and run commands without approval: Claude --permission-mode bypassPermissions, Codex --approve-for-me, Grok --always-approve, or --write for a plugin. permissions = "ask" leaves those flags off. Reviews always run as ask, whatever the target says, and without the branch's agent settings (see Security).

A custom target prints one JSON object with kind (completed, needs_input or failed), message, sessionId and findings. Its args may use {session_id} (required to resume), {worktree}, {model}, {effort} and {schema}. outsrc appends the prompt as the last argument.

Each finding has priority (P0 to P3), title, body, path (or null) and line (or null).

Vendor plugin engines

The codex-plugin and grok-plugin adapters drive the vendors' own Claude Code plugins, openai/codex-plugin-cc and xai-org/grok-build-plugin-cc, both Apache-2.0. The plugin launches the CLI and supplies the review prompts, output schema and, for Codex, the built-in reviewer. outsrc keeps the mailbox, worktrees, repository list and filtered environment. It runs the engine scripts directly; no Claude Code session is involved.

engines.lock.json pins each plugin to one git commit that passed the live smoke test, the way a lock file pins dependencies. init fetches exactly that commit. An upstream change reaches you only when an outsrc release moves the pin. If the pinned engine is missing, outsrc falls back to a Claude Code install of the same plugin, which is not pinned. A target's command can point at any copy of codex-companion.mjs or grok-bridge.mjs.

Each thread has its own plugin data directory, and after every Codex run outsrc stops the app-server that the plugin leaves running.

Grok and Docker Desktop on macOS: Grok's read-only sandbox refuses to start when /var/run/docker.sock is a symlink, which Docker Desktop creates by default. In Docker Desktop, turn off Settings → Advanced → "Allow the default Docker socket to be used", then run sudo rm /var/run/docker.sock in a terminal. The docker CLI keeps working. This affects Grok reviews, not Grok write tasks.

When a plugin changes

The plugin scripts are the vendors' internal CLIs, not a documented API. outsrc checks them three ways:

• outsrc plugins checks the installed engines without running a model: the subcommands and flags outsrc uses, the environment names, the Codex shutdown hook, and a JSON status call. Each engine is ok, unverified (compatible, but not the pinned version) or broken.

• doctor and list_targets include the same result, so a caller sees a warning too.

• .github/workflows/plugin-drift.yml runs the check daily against both upstream repositories and opens an issue when either drifts.

To move a pin, run outsrc engines pin <codex-plugin|grok-plugin> <commit|branch|tag>. It updates engines.lock.json only if the contract check passes. Then run npm run smoke:plugins and keep the change only if that passes too.

Limits

outsrc checks that thread and run paths stay inside its state directory, and it signals a process only if it is still the job outsrc started. By default at most 4 threads work at once and a run is stopped after 2 hours (both settings). A run log stops growing at 1 MiB, and log returns at most 8 KiB.

None of this confines a task. A worktree is not a sandbox, and the filtered environment is not a credential boundary. The prompt asks agents not to push or open pull requests, but nothing enforces that.

A task trusts the code it starts from: a task on someone else's branch (ref) runs that branch's code and settings with the task's permissions, so review such a branch first. A reviewed branch's CLAUDE.md or AGENTS.md still reaches the reviewer and can try to steer its answer, though the reviewer cannot edit or run anything. Grok skips a project's settings only while the folder is untrusted, so do not mark your home folder or ~/.outsrc as trusted in Grok.

Development

From a checkout: npm install, npm run build, then npm link to put the checkout's outsrc on your PATH.

npm run verify builds, type-checks, runs the tests, then repeats the MCP workflow against the built server. npm test runs the tests alone. Tests use real git worktrees and child processes with a fixture agent.

Two live checks use your own provider accounts and can cost money: npm run smoke:native runs a question and a follow-up through each CLI target, and npm run smoke:plugins does the same plus an adversarial review through each plugin engine.

License

MIT. See LICENSE.