Getting started

Well Actually docs

Well Actually puts the advice of engineers you trust inside your coding agent. A detector watches what the agent does, and the advice shows up only when it applies.

The idea in one example#

Your agent writes this line in a Flutter app:

lib/greeting.dart

final hour = DateTime.now().hour;

An expert on your advisory board has a principle about exactly that. Its detector sees the line, and before the agent moves on it reads:

<principle id="passsy/use-clock" expert="passsy" title="Use clock.now() instead of DateTime.now()">
- line 1: final hour = DateTime.now().hour;

# Use clock.now() instead of DateTime.now()

Read the time through clock.now() from package:clock, so tests can control it with fakeAsync or withClock.
...
</principle>

Nothing else changes. The agent keeps working on your task, and only advice that fits the code it just wrote reaches it.

The words#

Word	What it means
Principle	One piece of advice, plus a detector that decides when it applies.
Detector	A small TypeScript file. It sees one event, such as a file the agent wrote, and reports what it found. It runs sandboxed on your machine.
Expert	Whoever publishes principles. Anyone can become one.
Collection	A list of principles from any experts, picked by a curator.
Advisory board	The experts and collections you trust. Everything they publish runs in your agent, unless you switch it off.

Pick your path#

You use Claude Code, Codex, OpenCode or pi and want better advice in it. Start with Install the plugin, then build your advisory board.
You have opinions about code and want agents to follow them. Become an expert takes you from nothing to a released principle.
You want the details. The detector API with its versions, the test API and the MCP tools are in the reference.

How it fits together#

You follow experts and collections on this website. Together they are your advisory board.
The plugin in your agent downloads their principles when a session starts.
On every event of the session the plugin hands that one event to the detectors that asked for it: a file written or read, a prompt, a shell command and what it printed.
A detector that finds something puts its expert's advice in front of the agent, in full the first time in a session and as a one-line summary after that.

The check of an edit never waits for the network. It reads what the plugin downloaded at the start of the session, so a slow or unreachable registry never slows your agent.