installing.md

Installing

Back to README

./install.sh is the only entry point. It takes tool names (claudecode, codex, opencode, pi, zcode) and passes every other option through to installers/<tool>.sh. With no tool names it installs all five.

By default each installer installs the missing CLI and updates configuration in your home directory. If you already have the CLI, add --no-cli. The Pi installer uses --no-pi instead (it covers both the pi and omp binaries). ZCode is a desktop app, so its installer writes configs and warns when the app itself is missing.

The tool installers run on macOS and Linux. The optional workstation setup targets macOS and Ubuntu 24.04/26.04.

Choose What to Install

Goal	Command
Install and configure everything	./install.sh
Install one tool and all its configuration	./install.sh codex
Install several tools	./install.sh claudecode opencode
Keep an existing CLI and install all its configuration	./install.sh codex --no-cli
Install only selected configuration	./install.sh codex --skills-only --no-cli
Preview the personas available to a tool	./install.sh codex --list
Show a tool's options	./install.sh codex --help
Install configuration into one project	<setup repo>/install.sh <tool> --project, run from that project
Build the full workstation as well	./install.sh --machine (alias --env)

With no component flags, an installer installs everything for that tool. The first --*-only flag clears the default set. Add more --*-only flags to install those components together.

# Codex skills only. Keep the existing Codex CLI.
./install.sh codex --skills-only --no-cli

# Claude Code MCPs and hooks only. Keep the existing Claude CLI.
./install.sh claudecode --mcps-only --hooks-only --no-cli

# Codex skills plus the system AGENTS.md
./install.sh codex --skills-only --instructions-only --no-cli

A component is the smallest selection unit, so --skills-only installs every applicable skill shown by --list. When you name several tools, the same options go to each of them.

Per-Tool Options

Tool	Selectable components	Skip CLI install	Other choices
claudecode	--agents-only, --skills-only, --mcps-only, --hooks-only	--no-cli	--project, --list
codex	--skills-only, --agents-only, --instructions-only, --mcps-only, --hooks-only	--no-cli	--project, --list
opencode	--agents-only, --skills-only, --mcps-only, --hooks-only	--no-cli	--project, --list
pi	--skills-only, --context-only, --hooks-only, --packages-only, --mcps-only, --models-only	--no-pi	--no-packages, --no-models, --project, --list
zcode	--skills-only, --commands-only, --instructions-only, --mcps-only, --hooks-only	--no-cli (skips the app check)	--project, --list

--no-cli and --no-pi skip the binary install or upgrade. They don't remove anything. MCP registration still needs the tool's CLI on your PATH. Every installer, and install.sh itself, also takes --aws-mcp / --no-aws-mcp to opt in to or out of the AWS MCP servers. Registering MCP servers also asks once for a YouTrack URL and permanent token, blank to skip (see MCP servers).

Project-Local Configuration

Run the installer from the project that should receive the files. This example assumes the setup repo is at ~/code/macols-ai-coding-setup:

cd ~/code/my-project
~/code/macols-ai-coding-setup/install.sh codex --project

--project implies --no-cli. It leaves global MCPs, hooks, models and Oh My Pi packages alone, then writes the project files supported by that tool:

Tool	Project-local output
Claude Code	.claude/agents/, .claude/skills/
Codex	.codex/skills/, .codex/agents/, AGENTS.md
OpenCode	.opencode/agents/, .opencode/skills/
Pi (pi + omp)	.pi/skills/, .omp/skills/, AGENTS.md
ZCode	.zcode/skills/, .zcode/commands/, AGENTS.md

You can combine --project with component selection, such as install.sh codex --project --skills-only.

Caution

The installers delete and rebuild generated agents and skills directories. Move or commit any hand-written files in those directories first. JSON, TOML and YAML settings owned by the user are merged.

What Gets Installed, and Where

Tool	Personas as	Steering	MCP	Hooks
Claude Code	agents ~/.claude/agents/, skills ~/.claude/skills/	~/.claude/CLAUDE.md	claude mcp add-json into ~/.claude.json	~/.claude/settings.json
Codex	skills ~/.codex/skills/, agents ~/.codex/agents/*.toml	~/.codex/AGENTS.md	codex mcp add into ~/.codex/config.toml	~/.codex/hooks.json
OpenCode	agents ~/.config/opencode/agents/, skills .../skills/	~/.config/opencode/AGENTS.md	mcp key in ~/.config/opencode/opencode.json	plugin in .../plugins/
Pi (pi + omp)	Agent Skills in ~/.pi/agent/skills/ and ~/.omp/agent/skills/ (/skill:<name>)	both .../agent/AGENTS.md	mcpServers key in ~/.omp/agent/mcp.json (omp) and ~/.pi/agent/mcp.json (pi, built-in MCP)	pi-checks extension in both agent dirs, plus pi-yaml-hooks for your own YAML hooks
ZCode	skills ~/.zcode/skills/, commands ~/.zcode/commands/	~/.zcode/AGENTS.md	mcp.servers in ~/.zcode/cli/config.json	hooks.events in ~/.zcode/cli/config.json

The two Pi agents share no config directories: plain pi reads ~/.pi/agent and Oh My Pi (omp) reads ~/.omp/agent. The installer writes skills, steering and the pi-checks extension into both, and installs the Bun runtime omp needs. It also writes model providers for both agents and omp's model roles (see Models).

Each agent also gets its packages. Both get ponytail and pi-yaml-hooks. Plain pi also gets the capabilities omp ships natively:

• pi-subagents, which the steering delegates parallel and chained work to
• pi-web-search, a web_search tool that uses the current model's own search (Gemini, xAI, OpenAI, Anthropic, OpenCode). On a local model such as the vllm-lan default it errors unless ~/.pi/agent/web-search.json names a supported provider and model; brave-search still works there.
• pi-lens, LSP diagnostics and linters after every edit plus a guard that blocks editing a file the agent hasn't read. It overlaps with pi-checks' post-edit check, so some findings show up twice, and it installs its own tools per project without pi-checks' trusted-project gate. pi remove npm:pi-lens if you'd rather not have it.

Codex removed custom prompts (~/.codex/prompts/) upstream in favour of Agent Skills. The installer cleans up prompts left by earlier versions of this repo. Codex still loads user skills from ~/.codex/skills/ (upstream now marks it deprecated in favour of ~/.agents/skills/). The installer stays there because pi and OpenCode also scan ~/.agents/skills/ and would warn about a duplicate of every persona.

Hooks are referenced in place from this repo's hooks/ directory, so keep the clone where it is after installing. See Hooks.

hunk

hunk is a review-first terminal diff viewer. You open it in a second terminal (hunk diff, hunk diff --watch, hunk show) and the agent steers that live window: it moves you to the hunk that matters, adds inline notes beside the code and highlights the expression it is explaining. The agent does this with hunk session ... commands, taught by the hunk-review skill that ships with hunk.

The installers add the binary with brew install hunk (it is also in machine/Brewfile), or npm install -g hunkdiff without Homebrew. They then copy the bundled skill (hunk skill path) into each agent's skills dir as hunk-review/SKILL.md, so every tool gets it the same way, ZCode included. Re-run the installer after hunk update to refresh the copy. Project installs don't get the skill.

Ask for a review with something like "review my changes in hunk", or name the skill (/hunk-review, /skill:hunk-review in pi and omp). If the agent reports no live session while hunk is open, its sandbox is probably blocking loopback; allow it for that command.

hunk replaced revdiff. Re-running an installer removes the revdiff integrations earlier versions added: the revdiff@revdiff plugin and marketplace (Claude Code, Codex), the copied tool, command and auto-loaded plan-review plugin (OpenCode), and the pi and omp packages. The revdiff binary itself is left alone (brew uninstall revdiff if you no longer want it).

Machine Setup

./install.sh --machine            # picks the right setup for your OS, then installs all tools
# or directly:
./machine/install_macos.sh        # macOS
./machine/install_ubuntu26.sh     # Ubuntu 24/26 / WSL2

machine/README.md lists everything the setup installs. The Ubuntu script includes herdr and its auto-title and sidebar plugins. On macOS, install those separately with machine/install_brew_herdr_yazi_lazygit_nvim.sh.

The herdr setup maps prefix+f to the herdr-sidebar explorer and prefix+ctrl+p to its quick-open, and herdr-auto-title names tabs after the work in them. The herdr and yazi guide covers the workflow.

Running With --dangerously-skip-permissions

Claude Code ignores bypass-permissions mode under root or sudo. The installer adds ~/.claude/bin/claude-launch (from bin/claude-launch.sh) to handle that case:

~/.claude/bin/claude-launch            # or: alias cc=~/.claude/bin/claude-launch

• As a normal user, it runs claude --dangerously-skip-permissions directly.
• As root, it switches to $CLAUDE_USER, $SUDO_USER or the owner of $HOME. Claude needs to be installed for that user or system-wide.

For a root-owned sandbox, use IS_SANDBOX=1 claude --dangerously-skip-permissions. Otherwise use the launcher.

Post-Installation

aws configure                                   # AWS credentials (only with --aws-mcp)
podman machine init && podman machine start     # containers (macOS)
claude --version && codex --version             # sanity check
pi --version && omp --version                   # pi agents
pi list                                         # pi packages, incl. pi-yaml-hooks
ls -d /Applications/ZCode.app                   # ZCode (desktop app)
openspec --version                              # spec-driven dev CLI (auto-installed)
openspec init                                   # opt a project into OpenSpec (per repo)
ast-grep --version                              # structural search CLI (auto-installed)

Codex only runs hooks you have trusted, so approve them in Codex after installing (and again after they change).

Troubleshooting

# MCPs not loading
claude mcp list                                 # Claude
codex mcp list                                  # Codex
jq .mcp ~/.config/opencode/opencode.json        # OpenCode (mcp key, not mcp.json)
jq .mcpServers ~/.omp/agent/mcp.json            # Oh My Pi
pi mcp list                                     # plain pi (built-in MCP)

# PATH not updated
source ~/.zshrc   # or ~/.bashrc

Run ./tests/verify_install.sh <tool> to check the generated files for one tool (see Testing).