# Keep your agent current

Extrovert's hosted MCP runs the deployed tools. Installed skills and local CLI or stdio processes can
be older. Each current Extrovert skill instructs the agent to check guidance when first used in a
session, after an hour of continued use, and after an unknown-tool or schema error. Following those
instructions depends on the host's available tools and loaded skill version; an already loaded older
skill may need a refresh or a new session.

## Update a Claude Code plugin

For an existing, unpinned Extrovert marketplace plugin, run these commands inside
Claude Code. Update only the plugin you installed:

```text
/plugin marketplace update extrovert
/plugin update extrovert-assistant@extrovert
```

For Full, replace the second command with `/plugin update extrovert-full@extrovert`.
The first command refreshes the marketplace catalog; the second updates the installed
plugin. Restart Claude Code afterward to load the updated skills and MCP configuration.

From a terminal, the equivalent Assistant commands are:

```bash
claude plugin marketplace update extrovert
claude plugin update extrovert-assistant@extrovert
claude plugin list
```

The terminal updater defaults to user scope. For an existing project or local
installation, append `--scope project` or `--scope local` to the plugin update
command. Preserve deliberate Git/version pins, customizations, and the original
installation scope; do not install a second copy as an update.

Check the installed version with `claude plugin list`. In the restarted session,
verify access with the Extrovert `whoami` tool; use `/mcp` to authenticate only if
that connection requires it. An update does not require a new Extrovert account
or broader permissions.

These plugins fetch skills/configuration from our GitHub marketplace and connect
to hosted MCP. They do not select npm `@next` or `@latest`. Updating the plugin
does not deploy or pin the hosted backend. See
[first installation](https://docs.extrovert.dev/mcp/client-configuration/#install-skills-and-hosted-mcp-together)
and [Claude's plugin command reference](https://code.claude.com/docs/en/plugins-reference#plugin-update).

## Update now

Paste this into your agent, including an older installation that has never checked for updates:


> Read https://docs.extrovert.dev/llms.txt and follow its update checklist in order; report pending reloads.


Use it once for an older installation, or any time you want a fresh check, including just after a
release. An explicit update request skips the current session's freshness interval: fetch the live
guide and contract again, then refresh the Extrovert components installed in that environment.
It does not reset your account or remove intentional version pins or customizations.

Check pins before executing downloaded tooling. In a pinned environment, use the
public HTTPS contract or the exact saved CLI version with its supported options.
Do not run an unpinned default, `@latest`, or `@next` status, verification, or refresh helper unless the
user separately authorizes that execution. A read-only command still executes
the downloaded package; preserving the saved pin alone does not make it allowed.
If the pinned version cannot perform a check, report that check as pending.

The agent should complete these steps in order, using only the current host's commands:

The examples below target stable. Preserve an explicitly selected `@next` or `@beta`
channel unless the user requests a switch; use that selector for both one-off CLI
commands and saved launch entries. See [preview access](#preview-access).

1. Fetch the guide and public contract again. Inspect the existing host, manager, scope, package,
   installed Extrovert skills, pins and local edits. For an unpinned Claude Code installation
   whose policy permits the helper, run the refresh helper in step 2 before deciding whether
   an MCP update is needed. For pinned or unknown policy, inspect through the host's supported
   private inspection commands instead. The helper inspects saved scopes privately;
   an empty or absent project `.mcp.json` does not rule out a local or user entry. Do not dump
   configuration. For any native inspection or change beyond that helper, first run the current
   host's `mcp --help`, then the chosen subcommand's `--help`. This includes read-only
   `list` and `get`: read `mcp list --help` before listing entries and `mcp get --help`
   before inspecting one. Use only arguments and options shown by that host's help.
   Never dump environment variables or raw configuration, even through filters or
   post-hoc redaction. Inspect only the explicitly needed non-secret fields through
   supported private helpers. Host and session tokens are credentials too; do not
   print them or include them in tool output. Retain the account and profile.
2. Refresh the unpinned local package through the **existing** manager. For an **npx-launched MCP**,
   update its existing host launch entry to `npx --yes --prefer-online @extrovert.dev/mcp`,
   keeping its other arguments and environment. Preserve the existing launch command except the
   necessary version or freshness change: a direct-node entry stays direct-node. The launch runs
   the MCP server; `setup` is a one-time configuration command, not a server launch argument.
   A hosted MCP has no local server package to reinstall.
   After inspecting the saved npx entry, edit that entry in place and read it back before
   proceeding to connection verification. If the host cannot apply the edit, explicitly hand off
   the exact saved-entry change as pending. A one-off `agent status` or `whoami` invocation of
   `@extrovert.dev/mcp` does not update the saved MCP launch.
   For an authorized unpinned Claude Code installation, run:
   `npx --yes --prefer-online @extrovert.dev/mcp setup --refresh --host claude --json`.
   `--refresh` supports Claude Code only; do not substitute another host name.
   Use its result to determine the saved entry and update status; do not skip it because a project
   file looks empty. This privately refreshes one supported existing **local- or user-scope npx entry**, preserving
   its other arguments, environment, profile and scope. It does not remove and reconstruct the entry
   or expose inline credentials. `restart_required` means the saved configuration is ready; the
   running MCP is still unverified. Continue with skills and connection verification below.
   `manual_required` means no configuration changed: report the returned reason and the MCP update
   as pending, preserving the existing entry for private review. Project-scope MCP entries, pins,
   wrappers and ambiguous configurations require that handoff. `cleanup_required` is an additional
   flag, not a status or a rollback: the saved entry may already be updated. Use `configuration_changed`
   to report whether the entry changed, and report private cleanup as pending before attempting another
   refresh. Neither flag verifies the running MCP. Project-scoped skills do not imply
   project-scoped MCP configuration. Do not replace the helper's refusal with remove/re-add commands.
   For Codex, privately edit the existing launch entry through its settings or configuration.
   For an unpinned npx entry, change the package to `@extrovert.dev/mcp` and include
   `--prefer-online` in its **saved launch arguments**. Preserve its scope, all other arguments
   and environment. If that edit cannot be made safely,
   report it as pending. Ordinary `setup --host codex` preserves an existing entry; it does not
   refresh its package launch.
3. Update only installed, unmodified Extrovert skills in their original scope. Use the targeted
   command below for skills.sh; use the host's updater for a plugin. Preserve pins and local edits
   for a decision rather than overwriting them.
4. **Reload the changed skills and read each complete updated `SKILL.md` body.** Read one file
   per tool call. A truncated or persisted-output preview is not the complete file: read consecutive,
   bounded line ranges from the original installed file until every line has been observed.
   Reading its beginning and end or checking a digest does not fill in an unread middle. Copying files or
   checking only their metadata does not load the instructions. Check the installed version or digest
   against live context. If the files are still old, report the file update as pending; a reload
   cannot update old files. If the host requires a new session, report that step as pending.
5. For local stdio, verify local access with the Extrovert CLI:
   `npx --yes --prefer-online @extrovert.dev/mcp whoami --json` for an unpinned npx installation.
   For a pinned npx installation, invoke `npx --yes --prefer-online @extrovert.dev/mcp@<saved-version> --help`,
   substituting the exact inspected version and preserving its other launch arguments. Use that same
   prefix for `whoami --json` only if supported. `@extrovert.dev/mcp` is a package name, not an
   executable. Use an installed `extrovert` binary only if it is present. For other managers, check
   their installed CLI's `--help` before using `whoami --json`.
   If that version lacks it, report identity verification pending and preserve the pin. Only a
   successful identity response verifies access. Do not open, read or print credential files or any key/token fragment. The CLI reads its saved profile privately. **Separately restart
   its MCP through the host**, or refresh hosted discovery, then call `whoami` through that resumed
   connection. Local CLI verification does not verify hosted MCP or replace a pending host restart.
   An MCP restart does not reload skills.
6. Report observed versions and completed steps. Name any pending session or human action instead
   of declaring the update complete. If a release is not yet visible in the registry, report that
   observation and check later. Do not clear shared npm caches to force a refresh.

Other existing package managers have their own refresh command:

| Existing installation | Unpinned package refresh |
| --- | --- |
| npm project dependency | `npm install @extrovert.dev/mcp` in that project |
| npm global installation | `npm install -g @extrovert.dev/mcp` |
| Another package manager | Use that manager's equivalent with the selected channel; default is stable |

Choose the row only when it matches the existing installation. Keep intentional version pins
until a change is approved. Unqualified package names resolve npm `latest`; `@next` is opt-in preview.
Package resolution and restarting the running process are separate steps.

The targeted skills command and read-only version check below are also useful when updating manually.

## Preview access

Use a preview when you deliberately want an early feature or fix, for example at
Extrovert support's request. Keep the existing account, credentials and profile.

```bash
# Run the preview CLI once; this does not change a saved MCP launch.
npx --yes --prefer-online @extrovert.dev/mcp@next --help

# Use the preview SDK in the existing npm project.
npm install @extrovert.dev/sdk@next

# Create a NEW local stdio entry on the preview channel.
npx --yes --prefer-online @extrovert.dev/mcp@next setup --host codex --transport stdio --channel next
```

For new Claude Code or Hermes stdio entries, replace `codex` with `claude` or
`hermes`. Existing entries are preserved by ordinary setup. To change an existing
unpinned local/user Claude Code stdio entry, run this from its project root:

```bash
npx --yes --prefer-online @extrovert.dev/mcp@next setup --refresh --host claude --channel next --json
```

For other existing stdio entries, privately change only the package selector in
the saved launch arguments to `@extrovert.dev/mcp@next`, using the existing host's
supported settings. Preserve other arguments, scope and credentials. Restart that
MCP connection, inspect its version, and call `whoami` through the host. Exact
version pins and unsupported launchers require an explicit, manual update.

To return to stable, use `npm install @extrovert.dev/sdk@latest` for that SDK
project, or select `@extrovert.dev/mcp@latest` in the existing stdio launch. For
supported Claude refresh, use the default CLI and `--channel latest` instead.
Check compatibility first: returning from a preview can be a downgrade. Restart
the MCP afterward; never recreate an account or erase credentials to switch versions.

`@next` is a moving preview tag; use an exact published version supplied by support
when reproducing a particular fix. Ordinary refreshes preserve a selected preview.
Changing an npm tag does not change hosted MCP, Claude's hosted plugins, or skills
installed from GitHub. Those need their own released, explicitly selected artifact;
do not install duplicate plugins or assume a hosted preview endpoint exists.

## Read live context

Call `agent_context` only when it appears in the current tool catalog. With no Extrovert MCP, fetch the public
[agent contract](https://mcp.extrovert.dev/.well-known/agent-contract.json), or use your installed or
pinned CLI's `agent status --json` when supported. If your normal installation policy permits an
unpinned CLI, you can use:

```bash
npx --yes --prefer-online @extrovert.dev/mcp agent status --json
```

The [agent guide](https://docs.extrovert.dev/llms.txt) is the documentation fallback. None of these
public reads needs an account credential. Reading the fixed HTTPS endpoints does not require an
installation or changing a pin.

The context includes the deployed release, its channel, skill versions and SHA-256 digests,
guide URLs, and current signup availability. It checks the corresponding npm tag live and returns
`published_cli_version` with the lookup time in `publication_observed_at`. Both are `null` when the
lookup is unavailable; that does not mean the package is unpublished. Signup can be `enabled`,
`disabled`, or `unavailable`; the last means its status check did not succeed.
Published skill digests describe the release; this check does not inspect your local skill files.
Each skill's `sha256` hashes its **entire directory**, not just `SKILL.md`, an archive,
Git tree, or the skills CLI lock hash. Recursively sort the relative file paths,
using `/` as the separator. For each file, hash its UTF-8 relative path, one NUL byte,
the exact file bytes, then one NUL byte. Do not normalize line endings or whitespace.
This is Extrovert release metadata, separate from installer-managed lockfiles; it does not replace skills.sh update tracking. The contract's `skill_digest_format` names this format. Its separate `skill_md_sha256`
can be compared directly with `sha256sum path/to/SKILL.md`; that verifies only that
file, not accompanying references. Older contracts omit these explanatory fields.

For full-bundle verification, use the scoped `agent status` command below. A matching
version string establishes the declared version; it is not cryptographic verification.
Compare the `metadata.version` in each installed `SKILL.md` with that skill's live version. Older
skills without version metadata can still use the live guide; inspect their original installation
manager to refresh them when permitted.

Use the returned freshness interval, up to an hour. Read the current guide for the task and use the
host's current tool schemas. A different version or digest signals a change; it does not by itself
mean the installed version is incompatible, grant wider permissions, or authorize a downgrade.
If live context is unavailable, report that condition and use available compatible guidance.

## Refresh skills in their existing scope

For a skills.sh installation, update only the installed Extrovert skills. This example updates the
two initial skills in the current project:

```bash
npx --yes --prefer-online skills@latest update extrovert-connect extrovert-send-email --project --yes
```

For an existing user-level installation, replace `--project` with `--global`. Add other installed
Extrovert skill names when those workflows need refreshing. Preserve the original installation
manager and scope, explicit pins, and local edits. A host or project that permits managed updates can
apply this targeted refresh; otherwise continue from live guidance and report the required update.
Do not overwrite customized skills or change unrelated installations.

`skills check` is not a safe read-only alternative: in Skills CLI 1.5.23 it invokes the update flow.
Use Extrovert's public context for a read-only release check, and inspect the installed manager's
current help before choosing an update command. Plugin installations use their host's plugin updater.

## Refresh local tooling and loaded instructions

For an unpinned installation, you can also check the requested skill files against the live
release. This example checks the two project skills for Claude Code:

```bash
npx --yes --prefer-online @extrovert.dev/mcp agent status --host claude --scope project --skills extrovert-connect,extrovert-send-email --json
```

Use `--host codex` for Codex and `--scope user` for a user installation. Preserve the actual
installation scope and any pins; check a pinned CLI's help before using new options. The check
does not change files. `files_ready` means the requested files match the live release; missing,
unreadable, different or ambiguous files remain pending. If live hashes or a supported host
inventory cannot be established, the result is unavailable. Hermes requires its native inventory
and currently returns unavailable from this check. File verification does not establish that
the current session loaded the skills or restarted MCP.

The npm packages default to stable. An unpinned CLI invocation can request
fresh registry metadata with `--prefer-online` as above. npm uses a cache; `npx` alone is not a
guarantee that every command starts the latest release. Keep deliberate package pins until an update
is authorized, and inspect the installed CLI's `--help` for its supported flags.

Updating files does not replace instructions already loaded into an agent's conversation. Read the
live guide for the current task, reload the changed skill through the host, and read its complete updated `SKILL.md` body.
If a new session is required, report that step as pending. Separately restart a local stdio
server to load a changed package. Hosted clients may need refreshed tool discovery or reconnection;
call `whoami` in the actual resumed connection before continuing account work.

On a schema error, refresh the catalog before guessing a replacement command. Before retrying a send
or another mutation with an uncertain result, recover its existing state and retain its idempotency
key. Updating tooling does not require a new account, a new consent grant, or broader credentials.
Preserve locally stored OAuth refresh credentials as well as agent keys. Run `whoami` on the resumed
connection first; if it needs sign-in, use that connection's [authentication path](https://docs.extrovert.dev/quickstart/authentication/).
A CLI `auth login` is separate from the MCP host's hosted OAuth login.

## Start from one prompt


> Read https://docs.extrovert.dev/llms.txt and follow its setup checklist in order to send my first email. Stop and report install errors. Do not request credentials in chat.


The agent uses existing access first. Interactive setup uses hosted OAuth and explicit consent;
unattended workers use their own authorized credentials. New-account signup requires live availability
and the human's email verification. See [first email](https://docs.extrovert.dev/quickstart/zero-to-first-email/) and
[host setup](https://docs.extrovert.dev/mcp/client-configuration/) for the supported paths.

## Observe the active connection

The executing runtime returned by MCP `agent_context` and `whoami` identifies the
package/profile version, build, transport, catalog digest and runtime instance
answering that call. Hosted release metadata describes a separate release.
A fresh CLI cannot observe the active conversation's MCP runtime and reports it
as unknown. Local facts remain available if public release metadata is unavailable.

For Hermes local MCP, use `/reload-mcp` after an authorized package update, then
call an Extrovert MCP tool in this same conversation to verify the version.
A separate probe, tool count or hosted instance change does not prove refresh.
Keep selected channels, explicit pins, credentials, profiles and edited skills.