VexJoy Agent

Essays and writing behind this toolkit live at vexjoy.com.

VexJoy Agent connects plain-English requests to specialist agents, skills, and workflows. /do selects the knowledge and tools needed for your task. Hooks enforce specific checks, and scripts handle repeatable work.

The aim is to give capable models useful domain knowledge without making you learn the toolkit’s catalog.

43 agents, 45 skills, 70 hooks, 163 scripts. Agents carry domain knowledge, skills provide reusable methods, hooks enforce selected checks, and scripts handle repeatable plumbing.

Works across Claude Code (/do), Codex ($do), Factory (/do), Reasonix (/do), and Antigravity CLI (/do).

What It Looks Like

$ claude

> /do debug this Go test

===================================================================
 ROUTING: debug a failing Go test
===================================================================
 Selected:
   -> Agent: golang-general-engineer - Go code and test tooling
   -> Skill: workflow - "debug" runs the systematic-debugging pipeline
   -> Pipeline: OBSERVE → HYPOTHESIZE → TEST → FIX → RECORD
 Invoking...
===================================================================

  OBSERVE: reproduced the failure with go test -run TestHealthCheck
  HYPOTHESIZE: pool timeout shorter than the health-check deadline
  TEST: the failure follows the timeout value
  FIX: raised the pool timeout; go test ./... passes
  RECORD: noted the cause for later sessions

The router pairs the Go agent with the workflow skill’s debugging pipeline, then follows the task through each phase. The output is illustrative and abridged: the banner format, agent, skill, and phases are real; the run is an example.

The Pipeline

  ROUTE        PLAN         EXECUTE      VERIFY       DELIVER      RECORD
 ┌──────┐    ┌──────┐    ┌──────┐    ┌──────┐    ┌──────┐    ┌──────┐
 │ /do  │───▶│ Task │───▶│Agent │───▶│Tests │───▶│  PR  │───▶│Route │
 │Router│    │ Plan │    │+Skill│    │Gates │    │Branch│    │Result│
 └──────┘    └──────┘    └──────┘    └──────┘    └──────┘    └──────┘

/d — Jev-Powered Router

/d requires TypeSafe’s Jev. Jev classifies the request, checks that the selected route preserves the requested outcome, and then dispatches the agent, skill, and pipeline.

Intent preservation is production behavior: /d restates the requested outcome and gates dispatch on a Jev receipt for that exact proposed intent, preventing an agent from quietly expanding an apple into an orchard. The gate is an instruction in the /d skill, not a hook.

Choose either transport:

# Preferred: Jev through Vercel AI Gateway
export JEV_TRANSPORT=vercel
export AI_GATEWAY_API_KEY=...

# Alternative: Jev's direct API
export JEV_TRANSPORT=direct
export TYPESAFE_API_KEY=...

JEV_TRANSPORT=auto is the default. It prefers Vercel when AI_GATEWAY_API_KEY is set, then uses the direct API when only TYPESAFE_API_KEY is set. An explicit transport never silently switches to the other one. The TypeSafe MCP plugin is not required for /d.

Intent-alignment judgments are recorded in learning.db without raw request text. Receipts keep the Jev judge model separate from the executing agent’s configured model and effort level. View proposed-intent difference rates by agent profile, judge model, and transport:

python3 scripts/jev-intent-stats.py --days 30

Example (illustrative):

> /d fix the flaky test in the payments module

  Intent alignment (/d):
    -> Restated outcome: Fix the flaky payments test without changing unrelated behavior.
    -> Jev: aligned

  ROUTING (/d): testing-automation-engineer + testing
  Source: jev (confidence: medium)
  Invoking...

Anti-Rationalization

Skills ask for evidence rather than confidence.

These rows are skill and agent instructions, not hooks. No hook stops a session or a subagent from finishing without evidence. The Stop hooks are advisory (in this checkout, stop-drift-guard can wake the session again after it stops when its changes caused hook, doc-count, or routing drift), and subagent-completion-guard’s deny is not an output SubagentStop honors, so it never blocks in Claude Code. The hooks that do block cover specific actions: commits on main or master, pushes and PR creation before /pr-review records the commit (in every repo except non-fork github.com/notque ones), merges before CI passes, destructive commands, writes to credential files, and pipeline phases written without their artifact. The full list is in Start Here. Coverage depends on the runtime and tool path.

Knowledge Work Is First-Class

The content engine researches, drafts in a calibrated voice, checks 397 writing patterns, and adapts finished pieces for each platform. /frontend (its HTML artifact mode) produces a self-contained report, deck, prototype, chart, or diagram.

It Proves Its Own Changes

Toolkit changes use direct review and relevant checks. Model comparisons can settle specific uncertainties; they are not required for every edit. PHILOSOPHY.md explains the validation policy.

The automated nightly evolution loop (the toolkit skill’s evolution flow, skills/meta/toolkit/references/toolkit-evolution.md; it wrote to the gitignored evolution-reports/) ran regularly through mid-May 2026. It is currently dormant; recent evidence has come from manual PRs instead.

Installation

You need Python 3.10+, git, and bash: Linux or macOS, or Git for Windows’ bash. The installer runs pip, so it needs network access. npm is optional: it installs Jev’s Vercel gateway, and without it /d falls back to /do.

git clone https://github.com/notque/vexjoy-agent.git ~/vexjoy-agent
cd ~/vexjoy-agent
./install.sh

Installs into ~/.claude/, and into ~/.codex/, ~/.factory/, ~/.hermes/, ~/.reasonix/, ~/.gemini/ (Antigravity), and ~/.cline/ when that home directory exists. install.sh first creates the home of each runtime whose command is on PATH (not Cline’s). install.sh wraps the vexinstall engine (scripts/vexinstall/). Each SessionStart in the checkout re-syncs every runtime through the same engine, and so does the post-merge git hook after git pull. Symlinks (default in a git checkout on Linux and macOS) follow git pull; --copy gives a stable snapshot and is the default on Windows.

The install also changes your machine outside those directories, and its hooks then run in every repo you open with Claude Code:

• It merges the toolkit’s hook registrations and its env settings into ~/.claude/settings.json, after backing up the old file.
• It installs requirements.txt with pip (--break-system-packages when pip supports it, else --user), writes post-merge and pre-commit hooks into this checkout’s .git/hooks, and adds a managed block to ~/.bashrc.
• Several hooks block actions in any repo: git commit on main or master, git push and gh pr create until /pr-review records the commit (in every repo except non-fork github.com/notque ones), and gh pr merge before CI passes.

Every change, its opt-out, and how to turn off a gate: What the installer changes.

Layout and safety rules: docs/installer-layout.md.

Want only part of the toolkit? Run ./install.sh --configure, or copy .local.example/profile.yaml to .local/profile.yaml and edit it. Without a profile, the full toolkit installs. Details: .local.example/README.md.

Jev Auto-Compact plugin (optional, requires TYPESAFE_API_KEY):

claude plugin marketplace add ./plugins/jev-auto-compact
claude plugin install jev-auto-compact@jev-auto-compact -y

Replaces generated compaction summaries with Jev-judged verbatim pruning after context reaches 60%. The plugin is a Claude Code function hook; the CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 setting the installer adds turns those on. Inspect recorded before/after tokens and duration with python3 scripts/jev-compact-evidence.py.

Full setup: docs/start-here.md

Four Layers

The counts are active components: agents with a frontmatter name, skills not retired with promoted_to, hook files registered in .claude/settings.json, and the Python scripts in scripts/.

Full skill catalog: docs/skills.md.

┌──────────────────────────────────────────────────┐
│  SKILL.md                                        │
│  ┌─ Frontmatter ──────────────────────────────┐  │
│  │ name, description,                         │  │
│  │ routing: triggers, pairs_with              │  │
│  └────────────────────────────────────────────┘  │
│  Modes or phases, with gates                     │
│  Reference table (which references/ to load)     │
│  Verification (evidence requirements)            │
└──────────────────────────────────────────────────┘

This is the common shape, not a schema. Every active skill declares routing triggers; most also add phases or modes, a table that loads references/ files on demand, and a verification step.

Built with the Toolkit

A game built entirely by Claude Code using these agents, skills, and pipelines:

Choose Your Path

I just want to use it Install, learn /do, done.

I do knowledge work Writing, research, data analysis, moderation, HTML artifacts. No code.

I’m a developer Architecture, extension points, adding agents and skills.

I’m an AI power user Routing tables, pipelines, hooks, telemetry DB.

I’m an AI agent Machine-dense inventory. Tables, paths, schemas.

Philosophy

• Outcome-first operation. Describe the result; routing selects the relevant catalog entries.
• Programs compute; models judge and generate. Use deterministic code where the answer is computable.
• Density. Every word carries instruction, rule, or decision. Cut everything else.
• Breadth over depth. Right context ensures correctness. Unfocused context adds cost.
• Enforce what has earned it. A blocking hook’s exit code enforces what instructions can’t, for the actions it covers. Most quality gates are skill instructions, and a new check starts advisory until it proves its value.
• Everything pipelines. Complex work decomposes into phases. Phases have gates. Gates prevent cascading failures.

Full design philosophy: PHILOSOPHY.md

Maintenance

One report-only script surfaces upkeep work; it prints a digest and never edits, deletes, or blocks.

• python3 scripts/stale-skill-scan.py --top 20 ranks stale skills and agents as pruning candidates. Run it quarterly; see docs/deprecation-template.md.

Scheduled work follows the same boundary as everything else: judgment uses models; repeatable plumbing uses 163 scripts.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.