Make the opencode agent shell load your zsh aliases and functions.
The shell tool runs /bin/zsh -c … in a non-interactive shell, which never reads ~/.zshrc, so an alias like gp='git push' fails in agent shells. This plugin points every zsh the agent spawns at a .zshenv shim that sources the aliases and functions your interactive shell defines — without paying for oh-my-zsh, compinit, autosuggestions or syntax-highlighting on every command.
Add it to the plugins array in ~/.config/opencode/opencode.json and restart (or /reload) opencode:
{
"plugins": ["@jeffreyjyz/opencode-shell-rc"]
}For local development point at the checkout instead (an absolute path is treated as a local plugin):
{
"plugins": ["/Users/you/dev/cmdcode-tools/opencode-shell-rc"]
}After bun run build the root index.js shim loads dist/.
Nothing to call — once installed, every non-interactive zsh the agent spawns sources your aliases and functions. Alias and function edits are picked up on the next command with no restart; a PATH change needs an opencode restart.
Drop agent-only zsh into ~/.config/opencode/shell.zsh, sourced alongside the generated state.
The plugin registers a shell.create.before hook. When the shell about to run is zsh it:
- lays down
$XDG_STATE_HOME/opencode/shell-rc/(default~/.local/state/opencode/shell-rc/) containing:.zshenv— the tiny shim zsh reads first;state.zsh— the generated aliases and functions;.zshrc/.zprofile/.zlogin— symlinks to your real files so nested interactive/login shells still find them;
- regenerates
state.zshonly when the rc changed (~/.zshrc,~/.zshenvor oh-my-zsh), by runningzsh -ic 'alias -L; typeset -f'once — zsh's own serializer, so every alias and function is captured exactly — thenzcompiles it so sourcing costs ~0.5ms instead of ~10ms; - sets
ZDOTDIRfor that command.
Per-command cost is ~0ms: the generated state is sourced from .zshenv, and the rc is re-read only on a change.
| kept | skipped |
|---|---|
| every alias (incl. oh-my-zsh's) | oh-my-zsh startup / theme |
| every shell function | compinit, completions |
an optional ~/.config/opencode/shell.zsh |
autosuggestions, syntax-highlighting |
PATH and environment variables are not snapshot — the agent shell inherits the environment opencode was started with. If you add a PATH entry to .zshrc, restart opencode for the agent to see it; alias and function edits are picked up on the next command with no restart.
Non-zsh shells are left completely untouched. If zsh is missing or generation fails, ZDOTDIR is not set and the agent shell behaves exactly as before.
The agent shell has your aliases, but the model does not know their names — so it types bun where b would do. The plugin therefore mirrors the aliases you wrote in ~/.zshrc into the bottom of the global ~/.config/opencode/AGENTS.md, between <!-- shell-rc-aliases-begin --> and <!-- shell-rc-aliases-end -->:
<!-- shell-rc-aliases-begin -->
## Shell aliases (auto-generated from ~/.zshrc)
- `b` = `bun`
- `gs` = `git status`
- `ls` = `eza --icons=always`
<!-- shell-rc-aliases-end -->Only alias … statements in ~/.zshrc itself are indexed — the hundreds of aliases oh-my-zsh adds stay out, and so do zsh's two built-in defaults (run-help, which-command). The values are still zsh's own: the extracted lines are replayed in a clean zsh -f and read back with alias -L, so quoting comes out canonical.
Behaviour worth knowing:
- Idempotent. The block is rewritten only when its content changes, so an unchanged rc leaves
AGENTS.md's mtime alone — opencode watches that file and would otherwise inject an instruction update for nothing. - Yours stays yours. Everything outside the markers is preserved byte for byte; the block is appended when the markers are absent.
- Not exhaustive by design. An alias defined inside a conditional, a loop, a function, or a sourced file is not indexed — the rc is read as text for where, zsh is asked only for what.
- Always present. If the block is deleted by hand, the next shell puts it back.
An agent that learned grep on another machine will keep typing it no matter what its instructions say. The plugin can shadow a list of habit commands with a function that fails and names the right tool:
$ grep -r TODO src
grep is blocked in agent shells — use rg
$ echo $?
127Nothing is blocked by default — an agent shell that silently refuses a command you never configured is a surprise, so the list starts empty and no guard file is written at all. Opt in per command in ~/.config/opencode/shell-rc.json:
{
"blocked": {
"grep": "rg",
"find": "fd",
"sed": "sd (or read for line ranges)",
"ack": "rg"
}
}The value is the tool named in the error message. sed's names read too, since sed -n 'a,bp' is a range read with no sd equivalent.
cat is deliberately never worth adding to that list: it emits raw bytes, while bat reformats (headers, line numbers, decoration), so the output a pipeline or an agent reads would no longer be the file.
Three properties are deliberate:
- Opt-in. No
blockedentry means no guard, so the shim's-ftest skips the file entirely — and a config you empty removes the file. - Agent shells only. zsh functions are not exported, so a
githook, a Makefile, a binary or a/bin/shscript that shells out still runs the realgrep. What changes is only what the model types into the shell tool. A#!/bin/zshscript is the one exception — it inherits the shim'sZDOTDIR, so it is guarded exactly like the shell tool itself. - Skipped when the replacement is missing. Blocking
findon a machine withoutfdwould leave the agent with no way to search, so a guard whose replacement is not onPATHis not written at all. - Not a jail.
command grepand/usr/bin/grepstill work — the guard is a speed bump long enough for the model to reconsider, not a security boundary.
The user's escape hatch still wins: ~/.config/opencode/shell.zsh is sourced after the guards, so a single machine can undo one.
bun install
bun test
bun run typecheck
bun run build