Setup and customization

Choose your client below to install AgenticAle. This page is the canonical installation guide; the getting started page is the short reader entry point. Live runtime behavior is tracked separately in runtime compatibility, and is not tested until live evidence is recorded.

The package exposes three public workflows, all explicit-only skills:

• /work [task] (optionally /work --pr <task>) for a reviewed everyday task;
• /review [base or criteria] (optionally /review --deep and /review --profile NAME) for an independent review of the current branch's net changes up to the working-tree result;
• /autonomous [budget] [goal] for a durable, multi-round project.

The other two skills, source-code-lookup and pull-request-description, are supporting and are loaded by the workflows when their tasks arise. There is no coordinator to select and no commands/ entry: the session you invoke the skill in is the coordinator.

Install: choose your client

GitHub Copilot (CLI and VS Code)

With Copilot CLI installed and authenticated, install the published plugin from the AgenticAle marketplace:

copilot plugin marketplace add alefranz/AgenticAle
copilot plugin install agenticale@agenticale

Restart the Copilot session and invoke a workflow directly; there is no agent picker. For example, from the CLI:

/agenticale:work Fix the date filtering bug
/agenticale:work Address the review feedback on this branch
/agenticale:work Investigate why export is slow and suggest an approach
/agenticale:work --pr Add CSV export

VS Code discovers the same plugin. Its autocomplete may display the work skill as /agenticale work even though the CLI uses /agenticale:work; select the suggested autocomplete entry in VS Code.

Alternative: install from a local checkout

Alternatively, clone this repository or use your current checkout, then run the installer from the repository root:

node scripts/install-copilot.mjs

To inherit the active Copilot model and effort instead of applying per-route defaults, or to override routing, pass the routing options below. Remove the plugin with:

copilot plugin uninstall agenticale

Codex plugin (CLI, VS Code extension, and ChatGPT desktop app)

The published plugins/agenticale package contains all five skills, including agents/openai.yaml metadata for the work, review, and autonomous workflows. The repository also contains a Codex marketplace at .agents/plugins/marketplace.json. Install it with the Codex CLI:

codex plugin marketplace add alefranz/AgenticAle
codex plugin add agenticale@agenticale

For a local checkout during development, use codex plugin marketplace add /absolute/path/to/AgenticAle instead of the GitHub source. Then install with the same codex plugin add command. You can also open Plugins in the ChatGPT desktop app, select the AgenticAle marketplace, and install the plugin there. Start a new chat or session afterward. In CLI and VS Code, use /skills or mention $work, $review, or $autonomous; in the desktop app, open Skills or mention the skill in your prompt.

Refresh a Git-backed marketplace with codex plugin marketplace upgrade agenticale. Inspect installs with codex plugin list and remove this plugin with codex plugin remove agenticale@agenticale. See the official Codex plugin commands.

Alternative: standalone Codex skills

Installs the five skill folders directly under a .agents/skills directory. Codex CLI, the official VS Code extension, and Codex mode in the ChatGPT desktop app can discover these standalone skills. The installer requires no native agent or plugin.

A routing choice is required (--no-model for inheritance, --models PATH|PRESET, or --routing PATH); the examples below show each. The default destination is project scope, <cwd>/.agents/skills. Because of the overlap guard, running it from a checkout of this repository installs into the repository itself and is rejected, so from a checkout use user scope:

node scripts/install-standalone.mjs --no-model --scope user

From another project, invoke the checkout's script by absolute path so the skills land in that project's own <project>/.agents/skills:

node /path/to/AgenticAle/scripts/install-standalone.mjs --no-model

--scope user installs to ~/.agents/skills (Codex's user-level skill discovery location; on Windows %USERPROFILE%\.agents\skills). --target PATH overrides the destination entirely. The state file is .agenticale-standalone-install.json (schema 1). Like the OpenCode installer, it prints a non-blocking notice: another AgenticAle install appears present (<path>) if the target already carries the other layout's marker.

After installation, start a new chat or session in the chosen client. In Codex CLI and the VS Code extension, type $work Fix the date filtering bug, $review main, or $autonomous 10 Improve the export workflow; /skills also lists available skills. In the ChatGPT desktop app's Codex mode, open Skills in the sidebar or mention the skill in your prompt. Use one install scope for the same machine unless you intentionally want separate copies: Codex may show both skills if their names occur in user and project scopes. The plugin install can also duplicate a standalone install. See the official OpenAI skill documentation for discovery and invocation details.

OpenCode V2 (generated profiles)

Installs the generated OpenCode binding: the five skills, seven generated agent profiles under agents/agenticale/, and the three command entries commands/work.md, commands/review.md, and commands/autonomous.md that expose /work, /review, and /autonomous in the OpenCode TUI. It copies into the OpenCode configuration directory and does not link to the repository source. The default target is $XDG_CONFIG_HOME/opencode when set, otherwise ~/.config/opencode.

Quick start without a checkout, POSIX (Linux, macOS, WSL):

curl -fsSL https://raw.githubusercontent.com/alefranz/AgenticAle/main/scripts/install.sh | sh

Windows PowerShell:

powershell -NoProfile -Command "Invoke-WebRequest -Uri https://raw.githubusercontent.com/alefranz/AgenticAle/main/scripts/install.ps1 -OutFile install.ps1"
powershell -ExecutionPolicy Bypass -File install.ps1

The one-liner powershell -NoProfile -Command "irm https://raw.githubusercontent.com/alefranz/AgenticAle/main/scripts/install.ps1 | iex" is equivalent: it runs the same script without saving it.

To install a specific release, pass the release tag to the wrapper with --version TAG: pinning the tag in the wrapper URL alone does not pin the installed release — both wrappers still resolve the latest release unless told otherwise. POSIX (the options go after sh -s --, which hands them to the wrapper's own parser):

curl -fsSL https://raw.githubusercontent.com/alefranz/AgenticAle/v0.17.0/scripts/install.sh | sh -s -- --version v0.17.0

Windows PowerShell:

powershell -NoProfile -Command "Invoke-WebRequest -Uri https://raw.githubusercontent.com/alefranz/AgenticAle/v0.17.0/scripts/install.ps1 -OutFile install.ps1"
powershell -ExecutionPolicy Bypass -File install.ps1 --version v0.17.0

Using the same release tag in the wrapper URL as in --version also pins the wrapper itself to that release. In either case the wrapper prints the release tag, downloads that release's source archive, and runs the installer from the extracted archive; it never launches an AI session and cleans up its temporary directory. Prerequisites: Node.js 20 or later plus curl and tar (Windows 10 or later provides curl.exe and tar). With no routing selection it installs session-model inheritance (the wrapper appends --no-model).

Option	Effect
(none)	Every role inherits the session model and effort (--no-model is appended).
--version TAG	Install that release tag instead of resolving the latest.
--models PATH|PRESET	Import a model mapping or bundled preset into the routing contract.
--effort LEVEL	Route-wide reasoning-effort override (low/medium/high/xhigh/max).
--source-root PATH	Embed a different default source-lookup root into the installed skill.
--replace	Back up and replace differing destinations during install/update.
--dry-run	Print the planned operation without changing the filesystem.
--setup	Also run the consented routing setup step after a successful install.

For the full routing options, see install-time routing options.

After a successful install the wrapper offers a consented setup step: with --setup it runs unconditionally; on a terminal without --setup it asks "Create a personal AgenticAle preferences file (~/.agenticale/preferences.md)? [y/N]" (default no); non-interactive runs skip it and print a one-line tip. The step creates the personal ~/.agenticale/preferences.md only when it is absent — a minimal scaffold with no role overrides, so the installed baseline routing applies — and it never overwrites, migrates, or removes a preference file or creates the project-scope file. The legacy name routing.md is still accepted at each scope and, when both files exist at one scope, preferences.md takes precedence and the legacy file is ignored — never merged; when only the legacy file is present, the step creates nothing rather than a file that would silently take precedence (rename it yourself to move to the new name). It then prints the file's path, editing guidance (the packaged example and project-scope precedence), and a ready-to-paste prompt for an OpenCode session to finish the customization; see user preferences and precedence.

After the install — or after editing the preferences file — you can verify your routing with the ready-to-paste prompt that the installer prints with the post-install output and the setup guidance. Paste it into an OpenCode session; it works in both cases, and it checks the personal preference location and the project preference location of the session it is pasted into (--root is set to that session's project root). With no preference file the session runs the routing bootstrap and confirms that every role in its agents output reports match; with a preference file present the bootstrap reports interpretation-required, so the session reads and interprets each listed preference file (a project file takes precedence over the personal file; any legacy file reported as ignored is never read), writes the interpreted structured layers (lowest to highest precedence) to a temporary JSON file, resolves them with resolve --runtime opencode --input <file> --explain, and compares each resolved route with its installed profile (an inherit route matches a profile with no model: line; an explicit route must match the profile's model and reasoning effort). On a mismatch, missing, or unreadable result follow the preparation/refresh procedure in the opencode runtime binding.

Alternative: install from a local checkout

From a clone or your current checkout (offline or local use), run the installer from the repository root:

node scripts/install.mjs --no-model

The install command requires either --models PATH|PRESET or --no-model. This installer is copy-only: it no longer offers a link mode. On install it migrates older copy installs (state schema 1-4), older link installs (schema 1-4), and older six-profile generated installs (schema 5) to the current generated copy layout (state .autonomous-mode-install.json, schema 6, a 35-file inventory).

If the target already carries another AgenticAle marker (for example a standalone .agenticale-standalone-install.json), the installer surfaces a non-blocking notice: another AgenticAle install appears present (<path>) line instead of failing. Review it and remove the duplicate layout if the two installs were meant to be a single one.

Google Antigravity (App and CLI)

Antigravity uses the agy command-line tool and installs plugins from a local repository clone. Clone or pull this repository, then install it directly with agy:

agy plugin install .

From another directory, pass the path to the repository root:

agy plugin install /path/to/AgenticAle

The command discovers the plugin definition in the repository and installs the package into the user plugin root (~/.gemini/config/plugins/agenticale, or %USERPROFILE%\.gemini\config\plugins\agenticale on Windows), where both the Antigravity desktop IDE and the agy CLI discover it.

Verify that the plugin is recognized and active:

agy plugin list

Expected output:

Installed plugins:
- agenticale (enabled, <version>)
    Source:     antigravity
    Components: 5 skills

To update after pulling new changes in your local clone, rerun the install command:

git pull
agy plugin install .

To remove the plugin:

agy plugin uninstall agenticale

Alternative: install via the interactive session

Inside an interactive Antigravity chat or CLI session, run the /plugin command, select Discover > Install from local directory, and choose the repository root or plugins/agenticale.

Restart any running CLI or IDE session after installing or updating so the skills are loaded into active context.

See the Antigravity installation reference and model routing guide.

Model routing

The complete policy, preference precedence, and client-specific behavior live in the model routing guide. The following legacy section anchors remain available for existing links.

Routing options

See routing options and install examples in the focused guide.

Customizing model routing

See customizing model routing for the preference file locations and precedence.

Choosing models: cheap by default, strong when it matters

See choosing routes for the packaged tier intent.

OpenCode permissions

See the OpenCode permissions guidance and the detailed Autonomous guide.

Useful build and publish commands

See build, preview, and contribution checks and the site maintenance guide.

Source lookup configuration

Set SOURCE_ROOT to your local source directory to customize lookup without rebuilding or reinstalling. This works with directly installed Copilot plugins as well as standalone and OpenCode copy installs. For example, in PowerShell:

$env:SOURCE_ROOT = 'V:\dev'
[Environment]::SetEnvironmentVariable('SOURCE_ROOT', 'V:\dev', 'User')

The first line sets the current shell's value; the second persists it for future processes. Restart an already-running editor or CLI to inherit the new value. On POSIX shells, use export SOURCE_ROOT=/path/to/repos and add it to your shell startup configuration if desired. Use an existing absolute directory.

Lookup uses an explicit task override first, then a non-empty SOURCE_ROOT, then the installed default (~/dev unless customized). An invalid or unavailable configured root is reported rather than silently replaced with the default. Alternatively, embed a different default in an install with --source-root /path/to/repos; the installer writes that default into the installed skill and SOURCE_ROOT still takes precedence at lookup time. Reinstalling with a different path requires --replace, which backs up the previous copy.

Lookup checks likely paths under the root and verifies repository identity. Missing repositories are cloned into <source-root>/<owner>/<repo> for future reuse, with the host added when needed to avoid a collision. Explicit layout instructions take precedence. Inspecting another revision preserves existing working files and branches: use Git object reads or a temporary detached worktree, removed through Git after inspection. Canonical clones remain available for later development; no separate persistent inspection clone cache is used.

Preview, update, and uninstall

Preview an OpenCode or standalone install without touching the filesystem:

node scripts/install.mjs --dry-run --no-model
node scripts/install-standalone.mjs --dry-run --no-model

Update an existing install after fetching a newer version:

# OpenCode (explicit session-model inheritance shown here)
node scripts/install.mjs --replace --no-model

# Antigravity (re-run install from the updated local checkout)
git pull
agy plugin install .

Uninstall removes only the files owned by the package and deletes its state file:

node scripts/install.mjs uninstall
node scripts/install-standalone.mjs uninstall
copilot plugin uninstall agenticale
agy plugin uninstall agenticale

The installers record their ownership, refuse to overwrite differing files by default, and create a backup before an explicitly approved replacement. Modified files are preserved during uninstall.

Troubleshooting

See the focused troubleshooting guide for common invocation, routing, and OpenCode permission issues.

Limitations

• Live runtime support per client is recorded in runtime-compatibility.md and is not tested in this pass. Do not treat the inspected client versions as verified.
• OpenCode enforces the generated per-profile step and permission rules. Copilot has no equivalent per-route hard step ceiling, and some child-session restrictions are prompt conventions when a client does not support the corresponding custom-agent field.
• Skills can request a model and effort but cannot prevent host-side fallback. A host that silently substitutes a model without detection or control does not get a strict-routing claim; that limitation is recorded per host, not here.
• A fresh child context provides independence, but it does not automatically mean a different model family; use --models or --routing for explicit model separation.
• Prompt instructions complement OpenCode permissions; they cannot make an inherently irreversible operation safe.
• Unattended operation still needs bounded budgets and final human inspection.