clairvoyance

Clairvoyance

AI agents can write working code, but they don't stop to consider effective design unless asked. Clairvoyance is a set of skills inspired by John Ousterhout's A Philosophy of Software Design. Each skill gives your agent extrasensory perspective around software design, with concrete tests to see ahead of obstacles during implementation and review.

How It Works

Skills activate automatically and push your agent to ask questions like:

• Does this interface hide real complexity, or just pass things through?
• Can this method be understood without reading another one in a different file?
• Is error handling pushing work onto callers that the module could handle itself?

You can also invoke them directly. Use /red-flags to trigger a design smell scan, /deep-modules to check interface depth and /design-it-twice to compare alternatives before committing.

Installation

Give your agent Clairvoyance: Claude Code, skills.sh, Codex, Cursor, OpenCode, Gemini CLI, Antigravity, Factory Droid, GitHub Copilot CLI, Kimi Code, Pi.

Note: Installation differs by platform. If you use more than one, install Clairvoyance separately for each.

Claude Code

/plugin marketplace add codybrom/clairvoyance
/plugin install clairvoyance@clairvoyance-plugins

skills.sh

npx skills add codybrom/clairvoyance --skill '*'

Codex

Requires Codex CLI ≥ 0.142.0 (codex --version). The Codex App and CLI share the same config, so this also makes Clairvoyance visible in the App's Plugins panel.

codex plugin marketplace add codybrom/clairvoyance
codex plugin add clairvoyance@clairvoyance

Older Codex versions only get the 16 skills, via a manual symlink — see .codex/INSTALL.md for that fallback and full troubleshooting.

Cursor

Cursor doesn't yet have a one-line "install from a GitHub URL" flow for unlisted plugins, so clone (or symlink) the repo into Cursor's local plugins folder and restart:

git clone https://github.com/codybrom/clairvoyance.git ~/.cursor/plugins/local/clairvoyance

Then check the Customize panel in the sidebar to confirm Clairvoyance and its 16 skills are listed.

OpenCode

Add Clairvoyance to the plugin array in your opencode.json (global or project-level):

{
  "plugin": ["clairvoyance@git+https://github.com/codybrom/clairvoyance.git"]
}

Restart OpenCode — no symlinks or manual skill paths needed. See .opencode/INSTALL.md for version pinning, troubleshooting, and migrating off the old symlink-based install.

Gemini CLI

Requires Gemini CLI ≥ 0.26.0 and an account Gemini CLI currently serves (Code Assist Standard/Enterprise, Google Cloud, or a paid API key — see .gemini/INSTALL.md for details).

gemini extensions install https://github.com/codybrom/clairvoyance.git

Restart Gemini CLI to load the extension.

Antigravity

agy plugin install https://github.com/codybrom/clairvoyance

Factory Droid

Droid translates Claude Code plugin format automatically — no Clairvoyance-specific files needed.

droid plugin marketplace add https://github.com/codybrom/clairvoyance
droid plugin install clairvoyance@clairvoyance-plugins

GitHub Copilot CLI

copilot plugin marketplace add codybrom/clairvoyance
copilot plugin install clairvoyance@clairvoyance-plugins

Kimi Code

In Kimi Code's plugin manager (/plugins), choose Custom, or run directly:

/plugins install https://github.com/codybrom/clairvoyance

Kimi Code will show a third-party trust prompt since this isn't an officially curated source — confirm to proceed.

Pi

pi install git:github.com/codybrom/clairvoyance

Pi auto-discovers the skills/ directory with no extra config.

llms.txt

Machine-readable skill index for LLM agents:

• clairvoyance.fyi/llms.txt — table of contents with descriptions
• clairvoyance.fyi/llms-full.txt — full content of all skills

What's Inside

Structure & Modules