wellactually

Getting started

Install the plugin

The plugin connects Claude Code, Codex, OpenCode or pi to your advisory board. It needs Node 20 or newer and nothing else. Check that node --version prints 20 or more before you install it, because every agent but pi starts the plugin's command with Node. Without it the plugin installs fine and no principle reaches your agent.

Claude Code#

Run these three lines inside Claude Code:

/plugin marketplace add passsy/wellactually
/plugin install wellactually@wellactually
/wellactually:login
  1. The first line adds the marketplace that holds the plugin, the public repository passsy/wellactually.
  2. The second installs the plugin. From now on it runs on every session.
  3. The third signs you in and downloads your advisory board. It prints a link and a code: open the link, check that the code matches and confirm.

Claude Code leaves auto-update off for marketplaces outside Anthropic's own. To get new releases of the plugin, type /plugin, open the Marketplaces tab, select wellactually and choose Enable auto-update.

That is all. The next file your agent writes is already checked.

Codex#

Codex installs plugins from your terminal:

bash
codex plugin marketplace add passsy/wellactually
bash
codex plugin add wellactually@wellactually

Then open Codex and do two things in it:

  1. Type /hooks and press t to trust the new hooks, wellactually's among them. To trust them one by one instead, open an event with Enter and press t on each hook.
  2. Type $wellactually:login. It prints a link and a code, and you confirm the code in the browser.

OpenCode#

OpenCode installs plugins from your terminal:

bash
opencode plugin add 'github:passsy/wellactually#path:opencode'

Then open OpenCode and type @wellactually-login. OpenCode 2 has no slash command for a skill and loads the one you mention with @. It prints a link and a code, and you confirm the code in the browser.

The plugin lives in the opencode folder of the repository, which is what #path:opencode installs. opencode plugin add needs OpenCode 2, and opencode --version tells you which one you have. The plugin also works with OpenCode 1 from version 1.18.29. OpenCode 1 cannot install a plugin from a folder of a repository, so there you clone the repository and name the plugin's file in opencode.json:

bash
git clone https://github.com/passsy/wellactually ~/.wellactually-plugin
json
{
  "plugin": ["file:///Users/you/.wellactually-plugin/opencode/index.mjs"]
}

Use your own home folder in place of /Users/you. In OpenCode 1 the skill is a slash command, so you type /wellactually-login. To update it, run git pull in that folder.

pi#

pi installs packages from your terminal:

bash
pi install git:github.com/passsy/wellactually

Then open pi and type /skill:wellactually-login. It prints a link and a code, and you confirm the code in the browser.

pi has no MCP of its own, so the plugin offers the MCP server's tools as pi tools, named wellactually_rate_principle and so on. pi update keeps the plugin up to date with the rest of your packages.

Updates#

The plugin tells you when a newer release is out. At the start of a session, at most once a day, you see one line with the new version and the command that updates the plugin in your agent. Codex and OpenCode 1 show it once you send the first message, because that is when they start the session. The line goes to you, not to your agent. WELLACTUALLY_UPDATE_CHECK=0 turns it off.

Check that it works#

In Claude Code, type /wellactually:sync. In Codex, type $wellactually:sync. In OpenCode 2, type @wellactually-sync, in OpenCode 1 /wellactually-sync, and in pi /skill:wellactually-sync. Each reports how many principles are on your advisory board, how many of them are switched on, and what was downloaded.

An empty advisory board is normal right after you sign up. The sync then lists a few experts you can follow, with a link to each. Follow experts on the website and sync again.

When a hook seems not to fire, Troubleshooting shows where to look.

What the plugin installs#

  • Hooks for the session start, every prompt, every file the agent writes or reads, and every shell command and its output. Each hook runs wellactually hook. OpenCode and pi have no hooks that run a command, so there the plugin is a small module that hands each of these events to wellactually hook the same way. At the start of a session it starts a sync in the background, and on every other event it reads only local files.
  • The skills login, sync, disable and enable: /wellactually:login and so on in Claude Code, $wellactually:login in Codex, @wellactually-login in OpenCode 2, /wellactually-login in OpenCode 1 and /skill:wellactually-login in pi. disable and enable turn advice off and on in the project you work in.
  • An MCP server with the tools the agent uses to rate advice, to switch a principle off when you ask, and to write principles. See MCP tools.

Everything the plugin runs is in the public repository, including the sandbox that runs other people's detectors. Safety and privacy explains what it may and may not do.