Lord Claude

Use OpenAI's GPT, xAI's Grok and Google's Gemini as Claude Code agents.

Lord adds three agent types: lord:gpt, lord:grok and lord:gemini. Claude works with them the way it works with its own subagents. It can start them in the background, message them, stop them, give them a worktree, or fan them out in a Workflow. Each agent runs in its vendor's own command-line tool, on your own subscription. Claude never answers their turns, so their work costs no Claude tokens. Their descriptions add about 600 tokens to each session.

Install

claude plugin install lord --marketplace aylee1024/lord-claude

Then start a new Claude Code session. You need:

• Claude Code 2.1.302 or later
• Python 3.11 or later (Lord looks in Homebrew, /usr/local/bin and your PATH; set LORD_PYTHON to pick one)
• macOS (Linux is untested)
• at least one vendor tool, installed and signed in:

Agent	Tool	Setup
lord:gpt	OpenAI codex	brew install --cask codex, then codex login
lord:grok	xAI grok	curl -fsSL https://x.ai/cli/install.sh | bash, then run grok once
lord:gemini	Google agy	curl -fsSL https://antigravity.google/cli/install.sh | bash, then run agy once

Lord uses your subscription logins. It never reads login files, never uses API keys, and removes secret-looking environment variables before it starts a vendor tool.

Use

Ask in plain words: "have gpt fix this test in a worktree, and have grok review it read-only." Claude picks the agent and the settings.

You can also put options on their own lines at the start of a task or message:

Option	Effect
@model <id>	Use a different vendor model
@effort <level>	Reasoning effort, low to ultra. The nearest level the model supports is used
@readonly	Project files stay read-only: gpt writes nothing, grok still writes temp folders and shared session/runtime storage (gpt and grok only). gpt's live web search still reaches any website unless @nosearch is set (see below)
@net	Turn on network for gpt's commands (web search is separate); grok and gemini always have it
@nosearch	Disable gpt web search, overriding codex settings; stays off on later turns
@tests	gpt's test sandbox: loopback TCP, sysctl and psutil; writes confined. No direct internet; loopback reaches every local service, so a local proxy can pass traffic on. Not with @readonly, @nosandbox, @net, @tools. Resolves working and @dir paths to real folders, shown in settings. Refuses nested symlinks in temp or Lord-folder paths and writable roots containing Lord's folder; set TMPDIR to a real folder. For cwd and @dir, use the path without /System/Volumes/Data
@nosandbox	Run gpt with no sandbox: it can run any command and write anywhere, as Claude Code's own agents can when its sandbox is off. For commands that need unrestricted access. Not with @readonly
@cwd <folder>	The folder the agent works in
@dir <folder>	An extra folder gpt may write to
@memory <GB>, @hang <s>, @wall <s>	Stop the agent if it uses too much memory, goes silent, or runs too long. Defaults: 24 GB; silent for 2,400 s (grok and gemini; gpt has none); no wall-clock limit
@nice <0 to 19>	Start the vendor at that niceness (or at Lord's own, if higher), which every command it runs inherits. Inside @tests, nice can lower its own priority; renice and taskpolicy against outside processes are denied. Raising priority is denied by the kernel. Other gpt sandbox modes cannot change their own priority

Sandboxed gpt uses Codex 0.164.0 permission profiles that deny reading files named control.header and .control.header, including another Lord home's key, with @net included. Lord's home and plugin folder stay read-only in both their logical and real spellings, even inside a writable working or @dir folder. @tests and grok also deny writes to Lord's home and plugin folder and reads of its key and temporary key. @tests blocks Unix control sockets. @nosandbox uses codex's danger-full-access, with no Seatbelt or key denial; its delegation is already unconfined. Folder pins are checked before every vendor start, for all three families. The settings line lists read-only folders when a gpt or grok working folder, or a gpt @dir folder lies inside Lord's home or plugin folder.

The delegation rule and confined modes are hardening, not a security boundary against an agent that sets out to escape. Every agent runs as your user. A confined agent can still read your files and other processes' environments when macOS exposes them; Lord does not make those files or environment values private. Lord blocks the paths it controls: widening option lines, launch types and folder grants through its tools, control key reads, false tool identity, writes to Lord's records and plugin folder, and vendor programs resolved inside a writable confined agent's working or @dir folders while it is open in this daemon, or inside temp folders. A Lord tool call needs its token and a connecting process inside that agent's current vendor or exec-server tree. Another agent's token alone gives it no tool identity; a detached caller is refused, even with its own token. A failed process lookup refuses the call so the next tool call can retry. A writable folder can still hold files that you or other programs run later, such as shell start-up files, project tool folders or Claude Code's settings. Those execution paths are outside Lord's control.

For gpt, Lord disables only the MCP servers named in your own codex config. MCP servers and hooks from a trusted project's .codex/config.toml run in codex's own process, outside the sandbox, even without @tools. This applies to workspace-write, read-only and @tests.

An option line Lord cannot read stops the launch with the line named: a misspelt option (@efort max), a repeated one (only @dir may repeat), or a known one written wrongly. A line starting with @ and followed by more than one word (@claude please look) is task text. In a later message, @dir adds a folder to the agent's list; @model, @effort, @memory, @hang, @wall and @nice change it from the next turn; @readonly, @net, @nosearch, @nosandbox, @tests and @tools can only be turned on; @cwd is fixed at the first turn. Working-folder and @dir links keep the real folders found when first added. Reusing a path whose link now points elsewhere is refused; name the folder itself or launch a fresh agent. Everything else carries over to later messages. Turning on @tests, changing @nice or adding an @dir under @tests restarts its codex and exec-server together on the same conversation.

gpt permissions measured on macOS with codex 0.164.0 (default workspace-write, without @net):

Operation	workspace-write	@tests	@nosandbox
Bind and connect loopback TCP	Denied	Allowed	Allowed
Process lookups with pgrep -fl python	Denied	Allowed	Allowed
sysctl kern.boottime	Denied	Allowed	Allowed
/bin/ps	Denied	Denied	Allowed
Lower priority with nice -n 10	Denied	Allowed	Allowed
Raise priority with nice -n -5 (non-root)	Denied	Denied	Denied
Write working folder and temp folder	Allowed	Allowed	Allowed
Write outside those folders	Denied	Denied	Allowed
Direct internet TCP and DNS	Denied	Denied	Allowed
codex web search, current pages	Allowed	Allowed (from codex's source)	Allowed (from codex's source)

codex's web search runs at OpenAI, not on your Mac, so no sandbox setting blocks it, @readonly and network off included. codex's default searches only OpenAI's stored copy of the web unless the sandbox is off; Lord asks for live pages for every gpt agent, unless your codex config.toml sets web_search (or features.web_search_cached or features.web_search_request), in which case your setting applies. With live search, the agent can have OpenAI open any public web address it chooses. The website receives that request, including anything the agent puts in the address, and the pages the agent reads are current and may contain instructions aimed at it. @readonly and network off do not stop this. To turn it off for an agent, use @nosearch; it sets web_search = "disabled" on start and resume, overriding your config. You can also set web_search = "disabled" or "cached" in your codex config.toml as your default. Each search and opened address appears in the agent's log, and the settings line says web search live, web search off or web search per codex config.

@tests loopback reaches every local TCP service on the machine. /bin/ps stays blocked because it is setuid; psutil and pgrep work; pgrep can list every process, root's included, with its arguments; @tests allows only the com.apple.sysmond Mach lookup needed by pgrep, in addition to its existing lookups. Under @tests, every Unix socket bound to a path is denied to block control sockets in temp folders such as tmux's, which could let commands act outside the sandbox; socketpair and asyncio's internal pairs still work, as do Pool with spawn or fork and ProcessPoolExecutor, while multiprocessing.Manager and forkserver fail. Writes also cover @dir folders; .git, .codex and .agents at each writable project root stay read-only, including first-time creation, as in workspace-write. Launch and turn settings say sandbox tests.

Where each agent can write: gpt in its folder, @dir folders and temp folders (anywhere with @nosandbox); grok in its folder, temp folders, ~/.grok/sessions and its own login files; gemini anywhere, because agy has no sandbox. Lord's grok agents cannot save grok memory or use grok's own git worktrees. Lord depends on neither: Claude Code supplies worktree folders, so its worktree isolation still works. Native helpers inherit grok's sandbox; separately launched Lord agents have their own settings. Use @readonly to keep project files read-only. A read-only agent cannot start or message other Lord agents.

A grok working folder may not be inside ~/.grok or contain it ($GROK_HOME if set). Every grok agent, read-only included, can change another grok agent's saved conversation, because grok keeps all sessions in one writable folder. Lord runs grok with its own sandbox off inside a Lord-written macOS Seatbelt profile. Grok can update auth.json and mcp_credentials.json, their .lock files, and top-level .<pid>.<counter>.tmp replacement files in ~/.grok ($GROK_HOME if set). Everything else there stays unwritable except sessions, including config.toml, sandbox.toml, trusted_folders.toml and other storage folders. It allows IP network access, the mDNSResponder Unix socket for DNS and Lord's own daemon socket for grok's Lord tools. All other Unix sockets, including Docker and tmux, stay blocked in both modes. Lord's control key is unreadable and its folder unwritable. Project hook configs along the repository-root-to-launch path and root .git, .codex and .agents stay read-only, including resolved targets. At each directory on that path, a .claude, .cursor or .grok folder missing at start cannot be created by the agent, including by rename or symlink. In existing folders, the named hook configs stay protected even when missing, while ordinary files remain writable where project writes are allowed. A nonregular or hard-linked hook config refuses the start.

Lord resolves codex, grok and agy from the Claude Code session's PATH to absolute paths before running them, including model-list calls, and refuses a path inside a writable confined agent's working or @dir folder while it is open in this daemon, or a temp folder. In all gpt modes codex can still start git and other programs from PATH outside the command sandbox. Start Claude Code with no folders on PATH that an agent can write, such as an activated project virtual environment or a gpt or grok agent's working folder, since a sandboxed command can replace a program there that later runs unconfined.

Launch Lord agents without a name: a named launch would start a separate Claude process instead of the vendor, so Lord refuses it. Message an agent by the id its launch returns; it keeps its working folder across messages.

A delegated launch or message may have at most 64 leading option lines and 16 KB of option text; excess returns too many option lines before resolving folders.

Through Lord's tools, a sandboxed agent (gpt without @nosandbox, or grok) can launch only lord:gpt and lord:grok, requesting no more access than its running turn's recorded folders and capabilities allow. Grok requires network access. Lord refuses @nosandbox, network, tools or @tests the sender does not have, and working or extra folders outside the sender's real working and @dir folders, including through links. Relative paths use the sender's working folder; without @cwd, a child starts there. A gpt child inherits @nosearch. Messages, including self-messages, can reach only Lord agent ids known to this daemon whose recorded access fits within the sender's. Refused calls return a tool error naming the line or type and log that reason in both logs, without the message body. Read-only agents cannot launch or message; gpt with @nosandbox and gemini keep unrestricted delegation.

An @tests sender launches only @tests gpt children and messages only @tests agents. A child's folders must already exist. Each launch gets a folder-check ticket that expires after ten minutes and applies only to that child's first successful open, including after a daemon restart. A failed open keeps the ticket and its original folders for retry. Forwarded message folders must exist at send time. No ticket is created when the target already holds every named folder; other folder messages get tickets for that receiver. Message tickets do not expire. Only an open adding a folder the receiver does not already hold checks its ticket; successful opens consume held-folder tickets without checking their paths again, and consume checked tickets once they hold all their folders, including with a warm vendor or a held result. Vendor starts and reattachments leave tickets alone; at most 64 may wait for a receiver. Pruning the receiver removes its tickets. Unrelated agents are unaffected. A changed spelling is refused: @dir <path> changed after it was checked; launch again. An expired launch check asks for a fresh agent. Pruning preserves every ticket file still named by a valid receiver manifest; invalid or unreadable manifests are logged and removed so pruning can continue.

Claude Code's agent list shows each Lord agent's model and effort before its task, for example lord:gpt Astra, xhigh · Fix the test, and its details name the vendor model. The label is set at launch; an @model or @effort sent later in a message applies but does not relabel the agent.

Select a Lord agent in Claude Code's agent list (or /tasks) to watch it work, as you would a Claude subagent: what the vendor writes appears as it writes it, each shell command as a Bash row that shows as running and then fills in with its output, and every other step (a file read, an edit, a search) as a lord - <family> row with what the vendor reported. Rows show the last 2,000 characters of a step's output, with secrets removed. They are a record of what the vendor did: nothing in them runs again, and the agent's result is still only the vendor's final answer.

Type /lord to see your agents, the model and effort each ran with, their token use, how long since a working agent's vendor last reported anything, each agent's activity log, and the file holding its latest final answer. That file lets a read-only agent's findings land on disk. /lord also shows codex's allowance (each window's percent used and reset time, as codex last reported it during a turn) any vendor quota Lord is waiting out, and live jobs with pid, command and age.

What each turn leaves you:

• At launch, one line in the launch result with the settings asked for, defaults included, for example lord: requested gpt-6.1-sol xhigh · cwd … · dirs none · sandbox workspace-write · network off · tools off · nice 0 · memory 24 GB · hang none · wall none. The agent's log repeats the settings it actually ran with at the start of every turn, resumes included.
• With the answer, one closing line naming how the turn ended and what ran: [lord: done · gpt-6.1-sol xhigh · 21:43:53Z to 23:01:10Z · 184 commands · 2 helpers (gpt-6-luna) · session …]. A footer lists at most five live or killed jobs in total, then and N more; the record keeps all. An answer that is one JSON value gets no such line.
• On disk, beside the agent's log: <agentId>.json, its settings and every turn (start, end, how it ended, commands, retries, policy continues, live jobs, killed jobs, memory warnings, helpers, usage); <agentId>.answers/<n>.md, every turn's answer, the last 100 kept; and for gpt agents <agentId>.reads.txt, each path the agent and its helpers read, listed, searched or edited in a command codex recognises as such (cat, rg, ls, an edit), plus paths named in shell read commands, best effort (cat, head, tail, sed -n, nl, wc, rg, grep, less), tagged shell and deduplicated with codex entries. Shell parsing skips commands over 64 KB, heredoc bodies and unresolved glob or variable words, and follows simple cd commands. It stops at 4 MB. A file that a program or script opens is not listed: the log shows only the command that ran it. So a missing or short list does not mean the agent read nothing.
• Codex helpers. A gpt agent can start helper agents of its own inside codex. Their commands and edits go into the parent agent's log, tagged with the helper's name (for example [/root/check]), and the record names each helper and its model. A @readonly agent starts none.
• Errors. A failed turn's answer starts with lord: error:, and its closing line names the vendor's own kind of error. Claude Code marks every Lord agent's task "completed", errors included, because it gives plugins no way to mark one failed, so read the first line. When OpenAI declines a step, Lord continues once on the same session, asking it to omit that step. A second refusal in that turn ends it: the answer says refused by vendor, names the last command that finished, and the same agent continues if you send it a reworded message. When the model is at capacity, Lord continues the same conversation up to three times, after 30 seconds, 2 minutes and 8 minutes by default. After edits it asks the agent to check completed work before repeating anything. Jobs stay alive during these waits. The closing line counts capacity retries and policy continues. Failed launches and resumes leave a turn record marked . At 85% of the memory ceiling Lord logs one warning per turn and shows it in the footer; gpt also receives it in its running turn. For grok and gemini it starts no additional turn. A spent codex allowance is refused until the reset codex reported.

Claude Code's agent list shows a launch's label only when your description does not already name the model (gpt-6.1-sol high · review stays as you wrote it).

How it works

The plugin answers each Lord agent's turn by passing it to lordd.py, a small background program on your computer, which runs from ~/.claude/lord, never from an agent's folder. That program runs one vendor tool per agent, keeps each agent's conversation for later messages, and stops the tool when you stop the agent. Jobs an agent starts survive the end of its turn: a vendor with live jobs stays open and keeps the daemon busy, with the memory ceiling still watching both trees. TaskStop stops an idle agent's jobs, including after a daemon restart, and names what stopped. Quitting Claude Code closes idle agents used by this process, including before /clear or /resume, and kills their jobs; running turns keep working and their results arrive with your next message. After those turns finish, jobs do not keep their vendors open: the normal idle close kills them. /clear and /resume keep agents running and stoppable. A later message reopens the agent normally. If Claude Code is killed without ending its session, jobs run on until the agent is messaged and stopped with TaskStop. Option changes that restart a vendor, restarts after failures, process crashes, resource guards and daemon shutdown also stop jobs. Killed pids and commands go in the log; a restart also puts them in that turn's footer and record. Once jobs end, Lord closes the vendor after its normal idle minute and exits after 10 idle minutes. A later message reopens the same conversation, including after a Claude restart: Lord restores its settings from its journal or turn record. The first successful open writes a settings record with no turns yet, so a Claude restart during the first turn still identifies and resumes the Lord agent. A Lord record that cannot be resumed ends with a visible error and never falls through to Claude's model. After you update Lord, each open Claude Code session reloads it by itself at a moment when nothing in that session is working: no reply in progress and no agent, Claude or Lord, mid-turn. Claude Code then re-reads that conversation once, at the next message. A reload you type yourself while an agent works is safe too: Lord keeps what each agent's turn needs in Claude Code's session store, so the turn carries on. A session opened before version 2.0.14 needs one /reload-plugins --force typed by hand. Each Lord version runs its own background program, so new agents start on the new one at once, while the old one finishes its agents and exits once no session uses it. An agent moves to the new program at its next message and keeps its conversation.

Lord counts commands in both vendor process trees as jobs. Lord's own tool server, code hosts, direct vendor children present before the first turn on that process, and visible tool-server processes without both matching ownership markers are excluded with their subtrees. Processes carrying both the agent's LORD_AGENT_ID and this daemon's LORD_DAEMON_SOCKET are also found after detaching; another daemon's processes are not adopted when agent ids collide. Markers are read only from the environment appended after the plain command, never from arguments. Lord sets these two values in codex's command environment policy on start and resume, preserving them even when your policy filters inherited variables. Lord also lists previously observed processes and their current children while their birth times still match, dropping gone or reborn pids. macOS hides the markers for its own programs (shells, sleep, perl), so a shell job whose parent exits before any refresh observes it is seen only through its other children.

Restored agents' marked jobs are refreshed at restore, listing, before pruning and before idle exit, even without a vendor process. Listing and turn completion reuse job lookups younger than five seconds; a new command invalidates the cache. Detached jobs are checked every five seconds, and listing stopped records creates no empty vendors. At quit, Lord closes only agents this process launched or messaged; listing an agent or staging its model with /lord model does not make it part of that cleanup.

The default models are gpt-6.1-sol, grok-4.7 and gemini-4-argon. If your account does not offer one, or the vendor retires it, Lord uses the vendor tool's own default model instead; /lord shows the model each agent ran. A model you name with @model is used as named, or refused with the list your account offers. You can change default models and limits in ~/.claude/lord/config.json, for example {"grok": {"model": "grok-4.7"}}.

Without @tools, Lord disables codex skills, plugins, tool servers and the notifier from your own codex config. Trusted project MCP servers and hooks can still run as described above.

Codex agents keep their conversations in ~/.claude/lord/codex, not in ~/.codex, so the Codex app does not list them. Codex's own helper agents keep theirs there too. That folder links to your codex login, settings, instructions, custom agents, skills, plugins and rules in ~/.codex (or CODEX_HOME), so agents run on your account and settings as before. Lord does this only when nothing in your codex setup is tied to the folder: your login is kept in auth.json (codex's default, not the keychain or auto mode), you have no codex hooks of your own (hooks in a project's .codex folder are fine), your tool servers' sign-ins are not in .credentials.json or codex's encrypted store (secret_auth_storage), and your codex settings name no sqlite_home, log_dir or file by a relative path. Otherwise, and for agents started before version 2.1.2, conversations stay in ~/.codex, as before. If your setup changes that way later, an agent already in Lord's folder stops with a message saying why, since its conversation cannot move; it resumes once the change is undone (for a sign-out, after codex login). {"gpt": {"own_home": false}} in ~/.claude/lord/config.json keeps new agents there too. Codex's databases and archived conversations in ~/.claude/lord/codex are kept, as codex keeps them in ~/.codex.

What Lord runs, sends and stores

• Sends. Your task goes only to the vendor tool you chose, which sends it to that vendor under your account. A gpt agent's live web search can also have OpenAI open any website the agent chooses (see above). Lord makes no internet requests of its own. The plugin code talks only to the background program, over a local socket at ~/.claude/lord/lordd-<version>.sock. See PRIVACY.md.
• Runs. lordd.py with Python, /usr/bin/curl to read answers from the local socket, /bin/ps every few seconds while an agent works or has jobs (for memory and job ownership; the environment listing retains only pid, the Lord agent id, daemon socket marker and whether the environment was visible, and displayed commands come from a separate listing without environments), /usr/bin/nice to start a vendor tool at an @nice level, /usr/bin/sandbox-exec for grok and for a loopback codex exec-server with @tests, the vendor tools you installed, and Claude Code's /reload-plugins --force after an update. It never starts a shell and never downloads anything. The install commands above are for you to run; Lord does not run them.
• Reads. Only the turns of Lord agents; your main conversation and other agents pass through untouched. Files: your codex config.toml (to leave out your codex tool servers, and to see whether Lord's codex folder can share your setup); its own config.json and ~/.claude/lord/config.json (default models), and Claude Code's ~/.claude/plugins/installed_plugins.json (whether a newer Lord is installed). The plugin and daemon use HOME, PATH, CODEX_HOME, LORD_PYTHON, LORD_DAEMON_SOCKET, LORD_HOME, LORD_CONFIG, GROK_HOME, TMPDIR, LORD_AGENT_ID, LORD_MCP_TOKEN and LORD_READONLY from the environment. The environment scrub and redactor also inspect inherited variable names and values.
• Hooks. It answers Lord agents' turns and draws each vendor step as a row (turn.start, turn.step), notes new Lord agents and their folders and labels them with the vendor model and effort (agent.spawn, SubagentStart), hands a Lord agent's tool results back to its vendor, refuses a named Lord agent launch or one with option lines it cannot read, sets a Lord launch's effort to the level the vendor will run and adds one line of its requested settings to the launch result, answers a message to a working Lord agent itself, saying whether it went into the turn or was queued, answers each row with the vendor's output and refuses any other Bash or step-tool call from a Lord agent (), delivers a Lord agent's answer through Claude Code's tool in auto permission mode (), shortens a long Lord agent's transcript itself instead of letting Claude Code summarize it with a Claude model (), delivers a message to a Lord agent that is mid-turn (, ), stops a vendor's turn when Claude stops the agent (), stops an idle agent's jobs with TaskStop (), closes idle agents on quit while running turns finish (), adds and the step tools , and (, ), and reloads itself after an update (, ). It changes no settings or permissions, and no tool input except a Lord launch's effort.

CONTRACT.md has the full technical details.

Uninstall

claude plugin uninstall lord@lord-claude
pkill -f lordd.py         # stops Lord's background program, if it is running
agy mcp remove lord       # only if you used Gemini agents
rm -rf ~/.claude/lord     # Lord's records and logs

Lord removes its old grok profiles from ~/.grok/sandbox.toml when no daemon of another Lord version is running.

Older version

Version 1 was a set of skills (/codex, /gemini, /grok, /composer, /review-panel). It is kept at the v1-skills tag.

Development

claude plugin validate .
claude plugin test .
python3 -m pytest tests -q

License

MIT. The vendored Codex Seatbelt policies are Apache-2.0; see their license.