VexJoy Agent: A Router, a Skill Catalog, and Hooks That Refuse to Accept Confidence
VexJoy AI Agent with Intelligent Routing - /do routes plain-English requests to the right specialist agent and gates the work with reviews, tests, and a learning loop.
At a glance
- What is it?
- VexJoy Agent wraps Claude Code, Codex, Factory and Reasonix with a /do router, 43 domain agents, 122 workflow skills and 76 hooks. The interesting part is not the catalog size, it is the exit gates that block work when the evidence is missing.
- Who is it for?
- Adopt VexJoy Agent if you already drive Claude Code or Codex from a terminal and you want domain knowledge plus verification gates installed at the runtime level rather than pasted into prompts. Do not adopt it if you need a single portable agent runtime, if your writes go through unified_exec or unmatched MCP tools, or if you expect Codex to behave exactly like Claude Code.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is not model capability, it is routing and evidence
A capable model asked to debug a Go test will happily start editing files. It may not know your connection-pool conventions, and it may declare victory without running the test. VexJoy Agent targets both gaps at once. The README states the aim plainly: give capable models useful domain knowledge without making you learn the toolkit's catalog. The user types a plain-English request, and /do picks the knowledge and tools for the task.
The second gap is verification. The README's anti-rationalization table lists the excuses the toolkit is built to reject. "Code looks correct, skip tests" is answered by an exit gate that requires test output. "Trivial change, no verification" is answered by a hook that blocks completion without evidence. "I'm confident" is answered by a gate that demands an exit code. This is the design thesis: checks require evidence rather than confidence, and the enforcement lives in hooks rather than in instructions the model can talk itself out of.
The audience follows from that. This is for engineers who already run an agent CLI in a terminal and want a pre-built domain layer on top of it, not for people looking for a hosted service or a Python library to import. The primary language is Python, but the deliverable is a directory of agents, skills, hooks and scripts installed into a runtime's home directory.
The six-stage pipeline and where the router sits in it
The README draws the flow as ROUTE, PLAN, EXECUTE, VERIFY, DELIVER, RECORD. /do is the router at stage one. It selects an agent and a skill, then the task plan is produced, the agent and skill execute, tests gate the result, a PR branch is created, and the route result is recorded. The worked example in the README shows a request to debug a Go test resolving to go-engineer plus systematic-debugging, followed by four numbered phases: reproduce, hypothesize, verify, fix. The example output ends with a delivered PR and a one-line description of the fix.
The division of labor between the four asset types is stated explicitly. Agents carry knowledge. Skills enforce methodology. Hooks block incomplete work. Scripts handle determinism. That is a cleaner separation than most agent toolkits manage, and it explains why the counts are split the way they are: 43 domain agents, 122 workflow skills, 76 hooks, 138 scripts.
The RECORD stage is the learning loop. Route results are written back, and the README mentions an automated nightly evolution loop invoked as /evolve that writes into evolution-reports/. That loop ran regularly through mid-May 2026 and is currently dormant, with recent evidence coming from manual PRs instead. Treat the learning loop as a designed-in component that is not currently being exercised automatically. The README says so directly, which is more than most projects do.
Hooks, not prompts: how blocking actually works
The mechanism that distinguishes VexJoy from a prompt library is the hook layer. Hooks run at configured events. Skills state what to verify, and blocking hooks enforce the checks they cover. The README is careful about the boundary here: coverage depends on the runtime and the tool path. That caveat is doing real work, and it is the sentence to reread before assuming a check is universal.
The Codex section shows what the caveat means in practice. The installer classifies 62 Claude hook registrations as 26 native, 27 adapter-backed, and 9 unsupported, for 53 supported. Those are registration counts, not unique hook files. Codex now exposes apply_patch to tool hooks, and VexJoy's adapter converts each patch operation into the Write/Edit payload the existing guards expect. But the adapter cannot intercept writes performed through unified_exec, unmatched MCP tools, WebSearch, or other unsupported tool paths. PreCompact and Stop adapters also receive less telemetry than Claude Code, because Codex does not provide Claude's conversation_history or session_data. The README calls this expanded compatibility, not full Claude parity.
So the enforcement story has a shape: strong on the paths the adapter covers, absent on the paths it does not. If your agent workflow writes files through a shell command rather than a patch, the write guard is not in the loop. That is a design constraint you can plan around, but only if you know it.
Installation, profile.yaml, and the symlink-versus-copy decision
The install path is four commands. Clone the repository to ~/vexjoy-agent, change into it, and run ./install.sh. The installer writes into ~/.claude/ and mirrors into ~/.codex/, ~/.factory/, and ~/.reasonix/ when the runtime command is on PATH or its home directory exists. You choose symlinks, which give live updates through git pull, or copies, which give a stable snapshot. That choice is the main operational lever at install time and it is worth making deliberately, because a symlinked install means an upstream commit changes your agent behavior on the next pull.
Partial installs are supported two ways. Running ./install.sh --configure opens an interactive picker for skills, agents and hooks. Alternatively, copy .local.example/profile.yaml to .local/profile.yaml and edit it. The README states that no profile file means a full install with unchanged behavior, so the profile is strictly additive. The .local.example/README.md holds the details.
Entry points differ per runtime: /do in Claude Code, $do in Codex, /do in Factory, and /do in Reasonix. Reasonix is the narrowest target. It mirrors skills, scripts, and the allowlisted hooks from scripts/reasonix-hooks-allowlist.txt, and it gets no agent or custom-command surface, so the /do router rides in as a skill. Reasonix fires only four events (PreToolUse, PostToolUse, UserPromptSubmit, Stop), which is why only hooks for those events are allowlisted. Factory mirrors agents as "droids", plus skills and all hooks, with hook config merged into ~/.factory/settings.json and paths rewritten.
The Codex hook trust trap and the Gemini removal
Two operational details deserve attention because both can leave you with a toolkit that looks installed and is not enforcing anything.
First, Codex hash-trusts hook commands and skips changed, unreviewed definitions. The README instructs you to run /hooks in Codex after install or after any hook-definition change, and to review the new definitions before trusting them. If you skip that step, the hooks you believe are blocking incomplete work may simply not be running. This is not a VexJoy bug, it is a Codex security behavior, but it makes the review step mandatory rather than optional.
Second, Gemini CLI support has been removed. Per Google's transition announcement, Gemini CLI stops serving requests on 2026-06-18 for Google AI Pro and Ultra subscribers and for free Gemini Code Assist for individuals. Antigravity CLI support is pending CLI maturity. Gemini API integrations are unaffected and stay in the toolkit, including image-generation backends, the sprite pipeline, and GEMINI_API_KEY. If a previous install mirrored into ~/.gemini/, the README gives a removal command that deletes ~/.gemini/skills, ~/.gemini/agents, ~/.gemini/hooks, ~/.gemini/scripts, and ~/.gemini/antigravity/plugins/vexjoy-agent.
The pattern across both cases is the same: the toolkit's reach is bounded by each host runtime's hook surface, and that surface moves. A project that tracks four runtimes inherits four upgrade calendars.
Where the toolkit is thin, and what it says about itself
The content engine is described as researching, drafting in a calibrated voice, checking 397 writing patterns, and adapting finished pieces per platform. /html produces a self-contained report, slide deck, prototype, chart, or diagram, and the README says it needs no coding or setup beyond installation. That is a second product living inside the same installer, aimed at a different user than the Go-debugging example. Whether you want both is a real question. The profile.yaml picker exists precisely because some people will not.
The validation policy is the most unusual part of the repository. The README states that toolkit changes use direct review and relevant checks, and that model comparisons can settle specific uncertainties but are not required for every edit. docs/PHILOSOPHY.md holds the policy, and docs/what-didnt-work.md records failed experiments, routing reversals, unvalidated A/B citations, disabled lint rules, and program refutations. A project that publishes its own refuted claims is telling you the routing decisions are empirical and have been revised. It also tells you the current router configuration is a snapshot of that process, not a settled answer.
One documentation detail is worth flagging as a maintenance signal. A comment in the README asks that the counts match the Four Layers table around line 143 and points to python138 scripts/validate-doc-counts.py as the verifier. A project that needs a script to keep its own numbers consistent has a documentation surface large enough to drift. Expect the counts in any given section to be the thing most likely to be stale.
Alternatives and the honest boundary
The obvious comparison is a plain Claude Code setup with a CLAUDE.md file and a handful of custom commands. That approach costs nothing to maintain and has no installer to re-run. The difference is enforcement. A CLAUDE.md instruction to run tests is advisory; the model can decide the change is trivial. VexJoy's hooks are the part that turns the instruction into a gate, and the README's anti-rationalization table is essentially a list of the failure modes that motivated moving from prose to hooks. If you have never been burned by an agent skipping verification, you do not need this layer.
The second comparison is any single-runtime agent framework that ships its own execution loop. Those give you one coherent model of how a task runs. VexJoy does the opposite: it installs into whatever runtime you already use and inherits that runtime's limits. The Codex adapter story is the cost of that choice made visible. You get to keep your CLI, and you get a compatibility matrix instead of a guarantee.
The wrong-tool case is concrete. If your agent writes files through unified_exec, unmatched MCP tools, or WebSearch, the write guards are not intercepting those paths, and the blocking behavior you installed does not apply. If you are on Gemini CLI today, the mirror is gone and the upstream service stops on 2026-06-18. And if you need a stable, frozen toolchain, the symlink install option works against you, since git pull changes behavior underneath you.
Licence and the cost of staying current
The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the standard permissive position and it removes licence negotiation from the adoption decision. This is a description of the licence text, not legal advice; if you are redistributing a modified copy inside a product, have counsel read the notice requirements.
The maintenance cost is the part the licence does not cover. Four runtimes means four hook surfaces to track, and the README already documents one that broke: the original six-hook allowlist was correct for Codex v0.114, when tool hooks only intercepted Bash, and current support requires Codex v0.144.1 or later. That is a version floor that moved once and will move again. The installer also sets MultiAgent V2 compatibility keys for GPT-5.6 Sol, referencing openai/codex#31814, which is another upstream dependency to watch.
Upgrades are cheap in the mechanical sense: git pull plus a re-run of ./install.sh, or a re-run of ./install.sh --configure if you use a profile. The expensive part is re-reading the hook definitions after any hook-definition change, because Codex will skip the ones you have not trusted. Budget for that review, not for the pull.
Editorial conclusion
Adopt VexJoy Agent if you already drive Claude Code or Codex from a terminal and you want domain knowledge plus verification gates installed at the runtime level rather than pasted into prompts. Do not adopt it if you need a single portable agent runtime, if your writes go through unified_exec or unmatched MCP tools, or if you expect Codex to behave exactly like Claude Code. Before trusting it, run ./install.sh, then run /hooks in Codex and read the definitions, because Codex hash-trusts hook commands and silently skips changed ones you have not reviewed.
Community notes