Introduction and Overview
This chapter groups the shell-facing wrappers for the supported AI agents in the build environment. It covers the generic management command, the wrapper launch behaviour, and the per-agent front ends that inject project-local state and shared instructions.
Technical Details
AI wrapper management
The build environment also provides host-shell-facing wrappers for supported AI agents. The generic ai command manages startup, shared skills, and the user's personal AGENTS.md configuration, while wrapper commands such as codex, claude, gemini, qwen, and opencode start specific upstream CLIs with project-isolated state and build-environment instructions injected.
This chapter documents the command-line surface and the wrapper's filesystem-level behaviour (project-isolated state, configuration merging, and similar) for each agent. It does not cover conversational or authentication behaviour, since that depends on an interactive session and an account for the upstream service. If you depend on a detail not covered elsewhere in this book, confirm it with the agent's own --help or help subcommand.
Commands
<help> | - | Print the management command's own usage summary. |
<start> | - | Start the first installed supported agent wrapper. |
<agent> | - | Forward directly to one of the seven supported wrappers: agy, claude, codex, copilot, gemini, opencode, or qwen, passing the remaining arguments through. |
<agentsmd> | - | Manage ~/.config/ai/AGENTS.md. |
<nano> | - | Open the personal instructions file or a user skill in the terminal editor. |
<edit> | - | Open the personal instructions file or a user skill in the host editor where supported. |
<skills> | - | Manage the shared skill view and the user's own skill directories. |
<setup> | - | Populate ~/.agents/skills with links to user and system skills. |
<list> | - | List visible skills. |
<-v> | - | With ai skills list, include descriptions and indicate which skills come from the user directory. |
<less> | - | Display a skill's SKILL.md through the pager. |
<cat> | - | Display a skill's SKILL.md directly. |
<open> | - | Open a user skill directory on the host. |
<show> | - | Print the filesystem path to the selected skill directory. |
<new> | - | Create a new user skill, or copy a system skill into the user area so it can shadow the system copy. |
<delete> | - | Delete a user skill. |
<install> | - | Install a skill from a directory or a packaged .skill archive. |
<skill-name> | - | Name of the skill to inspect, edit, create, open, show, or delete. |
<directory-or-file.skill> | - | Directory to copy or .skill archive to unpack into the user skills directory. |
Starts whichever installed agent is available, forwards directly to a named wrapped agent, manages the shared skills view, and edits the user's personal ~/.config/ai/AGENTS.md file.
The command ai start checks for installed wrappers in a fixed order and starts the first available one. The skills commands manage user skills under ~/.config/ai/skills and the shared ~/.agents/skills view exposed to wrappers.
The main subcommands are:
| Subcommand | Behaviour |
|---|---|
| help | Prints the management command's own usage summary. |
| start | Starts the first installed supported agent. The current wrapper order is opencode, agy, gemini, qwen, copilot, claude, then codex. |
| <agent> | Forwards directly to one of the seven supported wrappers: agy, codex, claude, copilot, gemini, qwen, or opencode, passing any additional arguments through. |
| agentsmd | Manages the personal instructions file at ~/.config/ai/AGENTS.md. |
| skills | Lists, opens, edits, creates, installs, or removes user skills and prepares the shared skills view used by wrappers. |
The agentsmd subcommand supports:
| agentsmd mode | Behaviour |
|---|---|
| edit | Open ~/.config/ai/AGENTS.md in the host editor. |
| nano | Open the same file in the terminal editor. |
If the personal instructions file does not exist yet, the wrapper creates a stub for you before opening it.
The skills subcommand family supports:
| skills action | Behaviour |
|---|---|
| setup | Populate ~/.agents/skills with links to user and system skills so different wrappers see a consistent shared skill directory. |
| list | List the visible skills. With -v, include descriptions and indicate which entries come from the user directory. |
| edit / nano | Edit a named user skill in the host editor or the terminal editor. |
| less / cat / show | Display a named skill for inspection without editing it. |
| open | Open the skill directory or file on the host. |
| new | Create a new user skill skeleton. |
| install | Install a skill from a directory or packaged .skill bundle. |
| delete | Remove a user skill from ~/.config/ai/skills. |
<-c> | - | Short alias for --continue. |
<--continue> | - | Resume the most recent Antigravity conversation. |
<--conversation> | - | Resume a previous conversation by its ID. |
<upgrade> | - | Re-run the upstream Antigravity install script. |
<-p> | - | Short alias for --print. |
<--print> | - | Run a prompt non-interactively and print the response. |
<--prompt> | - | Alias for --print. |
<-i> | - | Short alias for --prompt-interactive. |
<--prompt-interactive> | - | Start with a prompt and remain interactive. |
<--sandbox> | - | Enable Antigravity's sandboxed execution mode, restricting terminal access. |
<--dangerously-skip-permissions> | - | Auto-approve all tool permission requests without prompting. |
<--add-dir> | - | Add an additional directory to the workspace (repeatable). |
<--log-file> | - | Override the CLI's log file path. |
<help> | - | Show upstream help. |
<install> | - | Run the upstream install management path. |
<plugin> | - | Run upstream plugin management (also accepts plugins). |
<update> | - | Run the upstream update path. |
<changelog> | - | Show upstream changelog information. |
Installs Antigravity (Google's agentic coding CLI, the product this wrapper starts) on first use if needed, stores each project's state under ~/.config/ai/agy/project.<name>/, and injects the build environment's shared skills and instruction files into that project-specific state.
With no arguments on first use, the wrapper downloads and installs Antigravity. If arguments are supplied before installation, the wrapper exits with Not installed. The wrapper-specific --continue resumes the most recent conversation, and upgrade re-runs the upstream install script.
The wrapper runs ai skills setup, exposes skills through /riscos-source/.agents/skills, and creates a project-local AGENTS.md by combining the system and user instruction files. It passes the project configuration directory to Antigravity with --gemini_dir and stores application data below an app subdirectory.
The upstream CLI runs interactively by default and commonly offers --continue, --print, --prompt-interactive, and --sandbox, plus maintenance commands such as help, install, plugin, update, and changelog.
This entry does not attempt to reproduce the full live Antigravity option set, since that continues to evolve upstream independently of this environment.
<--continue> | - | Wrapper compatibility switch mapped to resume --last. |
<upgrade> | - | Reinstall the upstream npm package with the latest Codex release. |
<prompt> | - | Initial interactive prompt when no upstream subcommand is given. |
<exec> | - | Run Codex non-interactively. |
<review> | - | Run a non-interactive code review. |
<resume> | - | Resume an earlier session. |
<fork> | - | Branch from an earlier session. |
<login> | - | Run the upstream login flow. |
<mcp> | - | Manage upstream MCP configuration. |
<plugin> | - | Manage upstream plugins. |
<doctor> | - | Run upstream diagnostics. |
<completion> | - | Generate or manage shell completion support. |
<-m> | - | Select the model. |
<--model> | - | Select the model. |
<-s> | - | Select the sandbox policy: one of read-only, workspace-write, or danger-full-access. The wrapper itself always passes --sandbox danger-full-access first (see below), so a value given here on the command line is what actually takes effect. |
<--sandbox> | - | Select the sandbox policy; see -s. |
<-a> | - | Control the approval policy: one of untrusted (ask unless the command is in a known-trusted set), on-request (the model decides when to ask), never (never ask; failures are returned to the model), or the deprecated on-failure (only ask after a command fails). |
<--ask-for-approval> | - | Control the approval policy; see -a. |
<--search> | - | Enable live web search. |
<-C> | - | Change the working root before running Codex. |
<--cd> | - | Change the working root before running Codex. |
Installs Codex on first use if needed, stores each project's state under ~/.config/ai/codex/project.<name>/, keeps authentication in the shared file ~/.config/ai/codex/auth.json via per-project auth.json symlinks, merges system, user, and project configuration, and injects the build environment's instruction files.
The wrapper maps --continue to resume --last for consistency with the other AI wrappers.
The wrapper sets CODEX_HOME, runs ai skills setup, merges configuration from the system, user, and project config.toml files, and passes explicit developer-instruction text telling Codex to read the system, user, repository, and current-directory AGENTS.md files when present. It also forces --sandbox danger-full-access because the container does not support Codex's normal sandbox implementation.
This entry identifies the wrapper behaviour and the common upstream subcommands and switches above, but it does not claim to be an exhaustive reference for the current upstream Codex CLI.
<--continue> | - | Pass through to Claude Code to continue the most recent conversation. |
<prompt> | - | Initial prompt in interactive mode. |
<-p> | - | Run non-interactively and print the response. |
<--print> | - | Run non-interactively and print the response. |
<-r> | - | Resume by session identifier or picker selection. |
<--resume> | - | Resume by session identifier or picker selection. |
<--model> | - | Select a model or alias such as sonnet. |
<--permission-mode> | - | Choose how tool approvals are handled. |
<--add-dir> | - | Extend the accessible workspace. |
<auth> | - | Run upstream authentication management. |
<mcp> | - | Manage upstream MCP configuration. |
<plugin> | - | Manage upstream plugins. |
<doctor> | - | Run upstream diagnostics. |
<install> | - | Run upstream installation management. |
<update> | - | Run upstream update management. |
<ultrareview> | - | Run the upstream ultra-review path. |
Installs Claude Code on first use if needed, stores each project's state under ~/.config/ai/claude/project.<name>/, and links the shared skills plus a CLAUDE.md view of the user's instructions into the project state.
--continue is passed through to Claude Code itself.
The wrapper sets CLAUDE_CONFIG_DIR, links ~/.agents/skills into the project as skills, links the user's personal instructions file as CLAUDE.md, and can seed new project state from the last-used Claude project while keeping shared plugins, cache, and settings outside the per-project directory.
This entry documents the wrapper integration and the main upstream options above, but it does not enumerate every current Claude Code switch, since the upstream CLI exposes considerably more (this entry deliberately covers only the most commonly used subset).
<--continue> | - | Wrapper compatibility switch mapped to resume --last. |
<prompt> | - | Initial prompt in interactive mode. |
<-p> | - | Run non-interactively and exit after the response. |
<--prompt> | - | Run non-interactively and exit after the response. |
<-i> | - | Start interactive mode and run an initial prompt. |
<--interactive> | - | Start interactive mode and run an initial prompt. |
<-r> | - | Short alias for --resume. |
<--resume> | - | Resume an earlier session. Takes an optional session ID, task ID, ID prefix, or session name; with no value, shows a session picker. |
<--model> | - | Select the model to use. |
<--allow-all-tools> | - | Permit tools without prompting. |
<--allow-all> | - | Permit tools without prompting, and also skip path and URL confirmation (equivalent to --allow-all-tools --allow-all-paths --allow-all-urls). |
<--yolo> | - | Use the upstream auto-approval mode; equivalent to --allow-all. |
<init> | - | Run upstream initialisation. |
<login> | - | Run upstream login. |
<mcp> | - | Manage upstream MCP configuration. |
<plugin> | - | Manage upstream plugins. |
<update> | - | Run upstream updates. |
<completion> | - | Generate or manage shell completion support. |
Installs GitHub Copilot CLI on first use if needed, stores each project's state under ~/.config/ai/copilot/project.<name>/, and links the shared skills and generated instruction files into that project-specific environment.
The wrapper maps --continue to resume --last. On first use with no arguments, it installs @github/copilot through npm. For new projects it can seed configuration from the last-used project or an existing default ~/.copilot directory so authentication is retained.
The wrapper sets COPILOT_HOME to the project directory, uses a shared cache under ~/.config/ai/copilot/cache/, generates $COPILOT_HOME/copilot-instructions.md from the system and user AGENTS files, and links ~/.agents/skills into $COPILOT_HOME/skills.
The upstream CLI runs interactively by default and commonly supports -p or --prompt for non-interactive use, -i or --interactive for an initial prompt in interactive mode, --continue and -r/--resume for session resumption, --model, and tool-approval options such as --allow-all-tools, --allow-all, or --yolo. Upstream subcommands include init, login, mcp, plugin, update, completion, and also help and version.
If copilot has never been run in this environment, the wrapper only attempts its npm install when invoked with no arguments at all; any other invocation, including --help, fails immediately with Not installed and exit status 127. Run a bare copilot first to trigger the install. The upstream CLI exposes considerably more switches than are listed here (for example --add-dir, --session-id, --mode, --plan, and many MCP- and permission-related options); this entry documents the wrapper integration and these common upstream paths, but it does not enumerate every current Copilot CLI option.
<--continue> | - | Wrapper compatibility switch mapped to --resume latest. |
<prompt> | - | Initial interactive query. |
<-p> | - | Run non-interactively with a prompt. |
<--prompt> | - | Run non-interactively with a prompt. |
<-i> | - | Start with a prompt and remain interactive. |
<--prompt-interactive> | - | Start with a prompt and remain interactive. |
<-r> | - | Resume a previous session. |
<--resume> | - | Resume a previous session. |
<--approval-mode> | - | Choose the approval mode: one of default (prompt for approval), auto_edit (auto-approve edit tools), yolo (auto-approve all tools), or plan (read-only planning mode). |
<-y> | - | Short alias for --yolo. |
<--yolo> | - | Automatically accept all actions without prompting. Equivalent to --approval-mode yolo. |
<-s> | - | Enable sandboxing. |
<--sandbox> | - | Enable sandboxing. |
<mcp> | - | Manage upstream MCP configuration. |
<extensions> | - | Manage upstream extensions. |
<skills> | - | Manage upstream Gemini skills. |
<hooks> | - | Manage upstream hooks. |
<gemma> | - | Run the upstream Gemma-related management path. |
Installs Gemini CLI on first use if needed, stores each project's state under ~/.config/ai/gemini/project.<name>/, links ~/.gemini there, and builds a merged GEMINI.md instructions file from the environment's guidance.
The wrapper maps --continue to --resume latest.
The wrapper sets GEMINI_CONFIG_DIR, links ~/.gemini to the current project state, runs ai skills setup, and generates GEMINI.md from the system and user AGENTS.md files. New projects can inherit settings and available authentication files from the last-used project.
This entry documents these wrapper-specific paths and the common upstream options above, but it does not enumerate every current Gemini CLI switch (omitted switches include, among others, --debug, --worktree, --output-format, and the various --policy/MCP-allowlist options).
<--continue> | - | Pass through to Qwen to continue the latest session. |
<prompt> | - | Positional query for one-shot or interactive use. |
<-i> | - | Start with a prompt and remain interactive. |
<--prompt-interactive> | - | Start with a prompt and remain interactive. |
<-r> | - | Resume a chosen session. |
<--resume> | - | Resume a chosen session. |
<--approval-mode> | - | Choose the approval mode: one of plan (planning only), default (prompt for approval), auto-edit (auto-approve edit tools), or yolo (auto-approve all tools). |
<-y> | - | Short alias for --yolo. |
<--yolo> | - | Automatically accept all actions without prompting. Equivalent to --approval-mode yolo. |
<-s> | - | Enable sandboxing. |
<--sandbox> | - | Enable sandboxing. |
<--experimental-lsp> | - | Enable Qwen's experimental LSP support. |
<mcp> | - | Manage upstream MCP configuration. |
<extensions> | - | Manage upstream extensions. |
<auth> | - | Manage upstream authentication. |
<hooks> | - | Manage upstream hooks. |
<channel> | - | Manage upstream messaging-channel integrations (Telegram, Discord, and similar), not software release channels. |
Installs Qwen Code on first use if needed, stores each project's state under ~/.config/ai/qwen/project.<name>/, links ~/.qwen there, and generates a QWEN.md file from the user's personal instructions.
--continue is passed through to Qwen itself.
The wrapper sets QWEN_CONFIG_DIR, links ~/.qwen to the current project state, runs ai skills setup, and copies the user's personal AGENTS.md into QWEN.md when present. New projects can inherit settings and OAuth credentials from the last-used project.
channel manages messaging-channel integrations such as Telegram and Discord, not release channels. The wrapper does not merge the system /etc/agents/AGENTS.md file directly into QWEN.md. This entry documents the wrapper-specific behaviour and the main upstream options above, but it does not enumerate every current Qwen switch.
<--continue> | - | Wrapper compatibility switch mapped to run -c. |
<project> | - | Project path to open in the upstream TUI mode. |
<run> | - | Run a prompt directly without starting the full TUI workflow. |
<message> | - | Prompt text passed to run. |
<attach> | - | Attach to a running OpenCode server. |
<url> | - | URL for attach. |
<serve> | - | Start the upstream headless server. |
<web> | - | Start the upstream web interface. The wrapper remaps this to the host OAuth callback port and binds to 0.0.0.0. |
<-m> | - | Select the provider or model. |
<--model> | - | Select the provider or model. |
<-c> | - | Continue the last upstream session. |
<-s> | - | Continue a specific upstream session. |
<--session> | - | Continue a specific upstream session. |
<--fork> | - | Fork the session when continuing. |
<--agent> | - | Select an agent profile. |
<mcp> | - | Manage upstream MCP configuration. |
<providers> | - | Manage upstream providers. |
<agent> | - | Manage upstream agent profiles. |
<session> | - | Manage upstream sessions. |
<plugin> | - | Manage upstream plugins. |
<models> | - | Inspect or manage upstream models. |
<stats> | - | Inspect upstream statistics. |
<export> | - | Export upstream state. |
<import> | - | Import upstream state. |
<github> | - | Run upstream GitHub-oriented helpers. |
<pr> | - | Run upstream pull-request-oriented helpers. |
Installs OpenCode on first use if needed and stores each project's config, data, state, and cache under ~/.config/ai/opencode/project.<name>/.
The wrapper runs ai skills setup, generates an opencode.json configuration containing the build environment instructions, and maps --continue to run -c.
The wrapper sets OPENCODE_CONFIG_DIR, OPENCODE_DATA_DIR, OPENCODE_STATE_DIR, and OPENCODE_CACHE_DIR to per-project directories, links ~/.agents/skills into the project config, can seed a new project from the previous project's opencode.db, and clears the terminal after a plain interactive TUI session exits.
OpenCode also offers further subcommands not covered here, such as acp, debug, upgrade, uninstall, and db; this entry documents the wrapper-specific behaviour and the main upstream commands and switches above, but it does not enumerate every current OpenCode option.
Examples
Editing personal AI instructions
This edits the user's persistent AI guidance file through the host editor.
ai agentsmd edit
Creating and editing a user skill
This creates a user skill skeleton and then opens it for editing.
ai skills new my-skill
ai skills edit my-skill