Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

purisev agent plugins

Plugins for Claude Code and Codex, published as one marketplace named purisev. An installed plugin has the same id under both hosts: <plugin>@purisev.

PluginWhat it does
openviking-memoryLong-term semantic memory backed by an OpenViking server, plus OpenViking’s tools for the agent.
ov-wikiAn agent-authored Markdown wiki stored in OpenViking.
humanizerRewrites AI-sounding text so it reads like the writer.
ponytailSteers the agent towards the smallest change that solves the task.
infraSkills for Ansible, Helm, Terraform, Terramate and MetricsQL.
playwrightBrowser tests, automation and scraping with Playwright.

Install

Linux and macOS:

curl -fsSL https://ai-plugins.purisev.com/install.sh | sh

Windows (PowerShell):

irm https://ai-plugins.purisev.com/install.ps1 | iex

The installer:

  1. checks for git and for Node.js 18 or newer, which the hooks of openviking-memory and ponytail run on. When Node.js is missing it offers the official build, checksum-verified, under your home directory — no root or administrator rights, and nothing is installed without a yes;
  2. finds Claude Code and Codex on PATH, adds the purisev marketplace to each, and installs or updates the plugins;
  3. offers to create ~/.openviking/ovcli.conf when there is none, and leaves an existing one alone.

It is safe to run again: a second run updates what is there.

Look before you run

Piping a script into a shell means trusting the address it came from. To read it first:

curl -fsSL https://ai-plugins.purisev.com/install.sh -o install.sh
less install.sh
sh install.sh --dry-run    # prints every command, changes nothing
sh install.sh
irm https://ai-plugins.purisev.com/install.ps1 -OutFile install.ps1
.\install.ps1 -DryRun
.\install.ps1

Options

install.shinstall.ps1Meaning
--host claude-AgentHost claudeInstall into this host only (claude or codex). Repeatable.
--plugin openviking-memory-Plugin openviking-memoryInstall this plugin only. Repeatable.
--no-config-NoConfigDo not offer to create the connection file.
--remove-duplicates-RemoveDuplicatesRemove other copies of these plugins and loose copies of their skills; see Troubleshooting. Without it they are only listed.
-y, --yes-YesAnswer yes to every question. Nothing is asked, so the connection file is not created.
--dry-run-DryRunPrint what would be done and change nothing.

Options after a pipe: curl -fsSL https://ai-plugins.purisev.com/install.sh | sh -s -- --dry-run, and & ([scriptblock]::Create((irm https://ai-plugins.purisev.com/install.ps1))) -DryRun.

Install by hand

Claude Code:

/plugin marketplace add purisev/agent-plugins
/plugin install ov-wiki@purisev

ov-wiki declares openviking-memory as a dependency, so Claude Code installs both.

Codex:

codex plugin marketplace add purisev/agent-plugins
codex plugin add openviking-memory@purisev
codex plugin add ov-wiki@purisev

The other plugins install the same way, as codex plugin add <plugin>@purisev. Then start codex, run /hooks, and approve the hooks openviking-memory and ponytail bring. Codex asks once, and again whenever a plugin update changes them.

After installing

Restart the host, then connect it to your OpenViking server. To check the result, ask the agent to run the ov-memory-doctor skill; Troubleshooting explains its report.

Connect to OpenViking

Both plugins talk to an OpenViking server you run or have access to. One file configures the connection for Claude Code and Codex alike:

~/.openviking/ovcli.conf

{
  "url": "https://openviking.example.com",
  "api_key": "<a user or admin key>"
}
  • url is the API root. It does not end in /api/v1 or /mcp.
  • api_key is a user or admin key. The server’s root key is refused on the data APIs the plugins use.
  • Keep the file private: chmod 600 ~/.openviking/ovcli.conf. The installer creates it that way.
  • account and user are for servers in trusted mode, where identity comes from headers. With an API-key server, leave them out: the key already carries the identity.

Where the connection comes from

First match wins:

  1. OPENVIKING_URL, OPENVIKING_API_KEY, OPENVIKING_ACCOUNT, OPENVIKING_USER in the environment that launches the host.
  2. ~/.openviking/ovcli.conf.
  3. The server section of ~/.openviking/ov.conf, the server’s own configuration, on the machine that runs the server.
  4. Nothing configured: Codex uses http://127.0.0.1:1933 without a key. Claude Code keeps the plugin off.

Claude Code turns the plugin on only when ovcli.conf or ov.conf exists, or when OPENVIKING_MEMORY_ENABLED=1 is set. With the connection in environment variables alone, set that variable too.

Tuning

Behaviour settings go under plugin in the same file:

{
  "url": "https://openviking.example.com",
  "api_key": "<key>",
  "plugin": {
    "recallLimit": 10,
    "codex": { "captureTimeoutMs": 25000 },
    "claude_code": { "debug": true }
  }
}

Keys directly under plugin apply to both hosts. plugin.codex applies under Codex only and plugin.claude_code under Claude Code only; each overrides the shared value. The OpenViking client configuration lists the keys.

A repository can carry its own settings in .openviking/config.json; see workspace configuration.

Check it

Ask the agent to run the ov-memory-doctor skill. Its Configuration section names the source of every value (← ~/.openviking/ovcli.conf, ← env) and its Connection section proves the key against the server: /health answers 200 even with a wrong key, so reachability alone proves nothing.

Plugins

openviking-memory

Source: the official OpenViking plugins, pinned to release v0.5.5 — Claude Code installs examples/claude-code-memory-plugin (plugin 0.7.22), Codex installs examples/codex-memory-plugin (plugin 0.11.21). Both are named openviking-memory, so ov-wiki’s dependency resolves on either host.

Gives the agent a memory that outlives the session, kept on your OpenViking server.

  • Session start — injects your profile and an index of stored preferences and entities.
  • Every prompt — recalls memories relevant to it and adds them to the turn.
  • Every turn end — appends the new messages to a server-side session and commits it once the server reports more pending tokens than commitTokenThreshold (default 20000).
  • Session end and before compaction — commits the session, and the server extracts durable memories from it. Claude Code also captures subagents.
  • Tools — a local MCP proxy forwards the server’s own MCP tools (search, find, read, list, glob, grep, write, edit, remember, …); the exact set comes from your server version.

Needs Node.js 18 or newer on the PATH of the environment that launches the host: the hooks and the proxy run the bare node command.

Skills: openviking-memory, ov-experience-memory, ov-memory-doctor, openviking-skills and openviking-rule-search. Full reference: Claude Code, Codex.

Memories are filed under a workspace peer derived from the repository’s git origin (falling back to the repository root). Outside a git repository memories go to your user-level space. Memories filed under a peer derived from the working directory are still recalled; to keep writing under such peers, set "peerSource": "cwd" under plugin in ~/.openviking/ovcli.conf.

To update to a newer OpenViking release, change ref in both marketplace files to the new tag.

ov-wiki

Repository: purisev/openviking-wiki. The plugin was called openviking-wiki until 0.3.0; the repository keeps that name.

Maintains a Markdown wiki that the agent writes and keeps consistent, stored in OpenViking: source summaries, entity and concept pages, an index and a log. The wiki is private to your user by default (viking://user/<you>/resources/wiki); a shared one (viking://resources/wiki) is used only when you say so.

CommandDoes
/wiki-initCreates the wiki’s schema, index and log.
/wiki-ingestReads a source and files it into the wiki.
/wiki-queryAnswers from the wiki, with citations.
/wiki-lintChecks structure, links and index coverage.
/wiki-recoverFinishes or rolls forward an interrupted multi-page update.

It registers no tools of its own and uses the OpenViking tools of openviking-memory. Claude Code installs that plugin automatically as a declared dependency; under Codex install it yourself.

Two offline helpers, wiki_validate.py and wiki_plan.py, are optional. They need Python 3 with PyYAML; uv run resolves that from the scripts’ headers. Without them the agent runs the same checks through the tools.

humanizer

Source: blader/humanizer, release v4.0.0, by Siqi Chen. MIT. Claude Code installs it from that repository; Codex installs a copy of the same commit from purisev/agent-skills, because Codex does not find a skill kept at the root of a repository.

One skill, humanizer: rewrites text so it reads like its writer, removing AI writing patterns such as forced triads, staged openers, inflated claims and stock AI words, without changing what it says.

If you installed it earlier from its author’s marketplace, the skill appears twice until that copy goes; the installer’s --remove-duplicates removes it.

ponytail

Source: DietrichGebert/ponytail, release v5.3.3, by Dietrich Gebert. MIT. Both hosts install it from that repository.

“Lazy senior dev mode”: steers the agent towards the smallest change that fully solves the task — YAGNI, the standard library first, no abstractions nobody asked for.

  • Hooks at session start, at subagent start and on every prompt turn the mode on in every session and every subagent, at level full. PONYTAIL_DEFAULT_MODE=off in the host’s environment, or defaultMode in ~/.config/ponytail/config.json, changes the default.
  • Skills: ponytail, ponytail-review, ponytail-audit, ponytail-debt, ponytail-gain, ponytail-help.
  • Task board (Claude Code): after every turn it appends a row to ~/.config/ponytail/band/<project>.csv. A webhook can receive the same row; it is off until you set its URL in the plugin’s options. Nothing leaves the machine without it.

Needs node on PATH for its hooks; without it the skills still work. Codex asks to approve its hooks once (/hooks).

infra

Source: purisev/agent-skills.

Skills for infrastructure command-line tools. They work through the tools’ own CLIs, which must be installed, and prefer checks and previews to changes.

SkillCovers
ansibleInventories, playbooks, roles, check and diff runs, collections, Vault.
helmCharts and releases: render, lint, package, install, upgrade, rollback, OCI registries.
metricsqlVictoriaMetrics MetricsQL queries for dashboards, alerts and recording rules.
terraformAuthoring, fmt, validate, speculative plan, read-only state. Never apply, destroy or state changes.
terramateTerramate templating and code generation: generate_hcl, globals, tm_* functions.

playwright

Source: Clawic’s Playwright skill by Ivan G. Davila, version 1.0.4, from clawic/skills pinned to a commit. MIT. Claude Code installs it from that repository, where the skill is listed as playwright:Playwright--Automation---MCP---Scraper-; Codex installs a copy of the same commit from purisev/agent-skills, where it is playwright:playwright.

Writes and repairs Playwright tests, diagnoses flaky and CI-only failures, drives a live browser through Playwright MCP and extracts data from JS-rendered pages. Needs Node.js and npx; Playwright and @playwright/mcp are installed on first use. The skill keeps its own preferences in ~/Clawic/data/playwright/.

Third-party plugins

humanizer, ponytail and playwright come from repositories purisev does not maintain. Each is pinned to one commit in both catalogs, so an update reaches you only when the pin here changes.

Platforms

LinuxmacOSWindows
Installertested, including the Node.js downloadsame script; run in CIinstall.ps1; run in CI
Plugins under Claude Codetestedexpected to workhooks need sh, which Git for Windows provides
Plugins under Codexinstall, hooks and MCP wiring testedexpected to worknot tested

“Expected to work” means nothing platform-specific is known to be in the way, and nobody has checked.

Troubleshooting

Start with the doctor. Ask the agent to run the ov-memory-doctor skill, or run it yourself from the installed copy:

# Claude Code
node "$(claude plugin list --json | node -p 'JSON.parse(require("fs").readFileSync(0,"utf8")).find((p) => p.id.startsWith("openviking-memory@") && p.enabled).installPath')/scripts/ov-memory-doctor.mjs"

# Codex
node "$(ls -d ~/.codex/plugins/cache/purisev/openviking-memory/*/ | sort -V | tail -1)scripts/ov-memory-doctor.mjs"

It only reads. The report has sections for the environment, the plugin install, the configuration, the connection, the server’s health and recent activity, and ends with every failure and warning next to its fix. Fix the first failure and run it again: one cause often shows up in several sections.

Nothing happens at all

No recalled context, no tools, nothing logged.

  • node is not on PATH for the environment that launched the host. The hooks and the MCP proxy cannot start. Under Claude Code the /plugin Errors tab shows Executable not found in $PATH. Install Node.js 18 or newer — the installer offers to — and restart the host. A shell profile that adds node to PATH does not help a host started from a desktop launcher.
  • Codex: the hooks were never approved. Run /hooks and approve them. An update that changes the hooks needs approval again; the doctor lists the hooks that have no trust record.
  • Claude Code: disableAllHooks is set in a settings file. The doctor names the file.
  • The plugin is disabled, or Claude Code disabled it over a missing dependency. claude plugin list shows the state and the reason.

Host key verification failed when a plugin installs or updates

Claude Code clones a plugin whose catalog entry has a github source over SSH, and fails on a machine without an SSH key for GitHub. This catalog names every plugin by its https URL, so the error means Claude Code still holds an older copy of the catalog. Run the installer again: it refreshes the marketplace before it updates the plugins. By hand:

claude plugin marketplace update purisev && claude plugin update <plugin>@purisev

The same error from a plugin of another marketplace goes away when git takes GitHub’s SSH addresses over https:

git config --global url."https://github.com/".insteadOf "git@github.com:"

Moving from the fork to the upstream plugin

openviking-memory@purisev used to come from the fork purisev/openviking-memory. It now comes from the official OpenViking repository. Refresh the marketplace and update the plugin:

claude plugin marketplace update purisev && claude plugin update openviking-memory@purisev
codex plugin marketplace upgrade purisev && codex plugin add openviking-memory@purisev

Restart the host afterwards. Codex asks to approve the new hooks once (/hooks). Keys the fork read, such as plugin.codex.serverAutoCommit, are ignored and can be removed from ovcli.conf.

Every hook runs twice, or a skill is listed twice

The same plugin is enabled from two marketplaces, or a skill a plugin ships also sits loose in a skills directory. The installer lists both kinds at the end of every run, and removes them when run with --remove-duplicates (-RemoveDuplicates on Windows):

curl -fsSL https://ai-plugins.purisev.com/install.sh | sh -s -- --remove-duplicates
  • Another copy of a plugin: a plugin with the name of a purisev plugin, installed from another marketplace out of the same repository, such as humanizer@humanizer from its author’s marketplace. It is uninstalled, and its marketplace removed once nothing else is installed from it. A plugin that only shares the name, coming from a different repository, is left alone.
  • A loose copy of a skill: a directory in ~/.claude/skills, ~/.codex/skills or ~/.agents/skills named like a skill a purisev plugin ships, such as ~/.claude/skills/helm next to infra. It moves to <skills directory>.replaced/<date-time>/, from where you can restore it.

Each removal asks first, unless --yes is given; --dry-run prints them and changes nothing. Looking for duplicates needs node.

By hand, for a plugin: claude plugin uninstall <plugin>@<marketplace>, then claude plugin marketplace remove <marketplace>; under Codex, codex plugin remove and codex plugin marketplace remove.

Recall is empty, captures do not land

  • The key is wrong. /health answers 200 regardless, so look at the doctor’s “credentials accepted” line, not at reachability.
  • The root key is in use. It is refused on the data APIs. Use a user or admin key.
  • A stray OPENVIKING_* variable overrides ovcli.conf. The doctor marks such values ← env.
  • Settings sit under the other host’s section. plugin.codex does not apply under Claude Code, nor plugin.claude_code under Codex. Put shared settings directly under plugin.
  • The server cannot reach its embedding provider. The doctor’s Server health section shows /ready per subsystem; the fix is on the server.

404 on profile.md, preferences, entities in the server log

Expected for a new user. At session start the plugin looks for your profile and memory indexes, and the server creates those only when it first extracts something to put there. The plugin treats the 404 as “no profile yet”; the requests turn into 200 once the first memories exist.

POST /mcp with API type unknown in the server log

That is the MCP proxy. Each host session opens with three requests (initialize, its confirmation and tools/list), then one per tool call, and a DELETE on close. The proxy polls nothing. “unknown” is the server’s label for a path outside /api/v1.

Logs

With OPENVIKING_DEBUG=1 in the host’s environment, or "debug": true in the plugin settings, hooks and the proxy write JSON lines to ~/.openviking/logs/cc-hooks.log (Claude Code) or ~/.openviking/logs/codex-hooks.log (Codex). An unchanged log after a full turn means the hooks were never started: look at node, approval and enablement, not at the server.

Adding a plugin

A plugin purisev maintains lives in its own repository, such as purisev/openviking-wiki, or as a directory of purisev/agent-skills, which suits plugins made only of skills. purisev/agent-plugins holds the two catalogs, the installer and this site. Plugins from other authors follow Third-party plugins.

  1. Give the plugin repository a .claude-plugin/plugin.json with a name and a version, and check it with claude plugin validate <checkout>/.claude-plugin/plugin.json. For Codex it also needs a .codex-plugin/plugin.json.
  2. Add an entry with the same name to both catalogs:
    • .claude-plugin/marketplace.json — a url source with the https clone URL, or a git-subdir source for a directory of purisev/agent-skills, with no ref, so it follows the default branch. Not a github source: Claude Code clones that over SSH and fails without an SSH key for GitHub;
    • .agents/plugins/marketplace.json — the same source with "ref": "main", and a policy. Codex lists nothing from the first file.
  3. A plugin that needs another plugin from this catalog lists it under dependencies in its .claude-plugin/plugin.json. A bare name resolves inside this marketplace, so Claude Code installs it automatically.
  4. Add the plugin to ALL_PLUGINS in docs/install.sh and to $AllPlugins and the -Plugin ValidateSet in docs/install.ps1, and give it a section in docs/plugins.md.
  5. Run the checks and open a pull request.

Do not give a plugin repository a marketplace.json of its own. The same plugin reachable through two marketplaces can be enabled twice, and its hooks then run twice.

Claude Code tells plugin versions apart by version in plugin.json, so raise it with every release.

Third-party plugins

A plugin from another author is listed from its own repository and pinned to one commit, so an install never follows someone else’s branch:

  • Claude Code: a url or git-subdir source with ref (the release tag, or the branch when there are no releases) and sha (the full commit). A source without .claude-plugin/plugin.json needs no wrapper: the catalog entry is then its manifest, so give it description, version, author, license and skills, as the playwright entry does.
  • Codex: the same repository, ref and sha, when the source has a manifest Codex reads and its skills under skills/. Otherwise Codex installs the plugin empty, without an error. Such a plugin gets a Codex-only copy in purisev/agent-skills, whose README describes the layout, and joins CODEX_WRAPPERS in marketplace.test.mjs.

An install that succeeds does not prove that Codex found the skills. codex debug prompt-input hi prints the prompt Codex would send, and its skills section lists every skill it loaded.

To move a third-party plugin to a new release, change ref and sha in both catalogs, and for a wrapper follow the update steps in the purisev/agent-skills README. Hooks shared by both hosts use ${CLAUDE_PLUGIN_ROOT} in their commands: Claude Code expands only that token, and Codex provides it next to its own ${PLUGIN_ROOT}.

Checks

node --test
claude plugin validate .
codex plugin marketplace add . && codex plugin list
mdbook build

node --test needs no network. It guards both catalogs and that they agree, and runs both installers against stand-ins for claude, codex, git and node, so nothing is installed. The install.ps1 cases are skipped where pwsh is missing.

The marketplace name purisev is part of every installed plugin’s id and of users’ settings. Renaming it would orphan those installs.