John
中文版: README_ZH.md
John turns unstructured source material into a working knowledge-dense app. It keeps knowledge engineering and app building in one durable run, coordinates large per-entry fan-outs, and leaves auditable events and checkpoints on disk.
Use either Claude Code or Codex. Both are recommended runtimes over the same John plugin, skills, scripts, hooks, workspace state, and template format.
Install and update
Claude Code
Install and verify:
claude plugin marketplace add kitchen-engineer42/joharnessburg
claude plugin install john@joharnessburg
claude plugin list
Then run /reload-plugins in an active session, or start a fresh Claude Code session.
Update and verify:
claude plugin marketplace update joharnessburg
claude plugin update john@joharnessburg
claude plugin list
Run /reload-plugins or start a fresh session after the update.
Codex
Install and verify:
codex plugin marketplace add kitchen-engineer42/joharnessburg
codex plugin add john@joharnessburg
codex plugin list
Restart Codex or start a new task so the plugin reloads. Open /hooks, inspect John's hook definition, and trust it only after review; installing the plugin does not trust its hooks automatically.
Update and verify:
codex plugin marketplace upgrade joharnessburg
codex plugin add john@joharnessburg
codex plugin list
codex plugin add is idempotent and refreshes the installed plugin from the upgraded marketplace snapshot. Review /hooks again if the definition changed, then restart Codex or start a new task.
Quick start
Open your project in either runtime, initialize John with an optional input file or directory, confirm the generated PLAN.md, then describe the app you want. John advances through the knowledge and app phases while .john/events/, .john/checkpoints/, and .john/runs/ preserve durable evidence.
| Operation | Claude Code | Codex |
|---|
| Initialize | /john:init <input-path> | “Use init-workspace to initialize John from <input-path>.” |
| Status | /john:status | “Use workspace-status to show the John workspace status.” |
| Run report | /john:report | “Use codex-run-report to generate the John run report.” |
| Endurance goal | /john:endurance <goal> | “Use endurance-goal to set <goal>.” |
| Archive | /john:archive [label] | “Use archive-workspace to archive this John workspace.” |
John initializes both CLAUDE.md and AGENTS.md, plus byte-identical project skill trees under .claude/skills/ and .agents/skills/ when knowledge is packaged.
Scale-out execution
- Claude Code:
vertical-workflows can author Claude dynamic workflows for large uniform fan-outs. When unavailable, the same work runs through inline subagent waves.
- Codex:
codex-vertical-workflows uses native subagent waves and the durable .john/runs/ ledger for retries, reconciliation, status, and cancellation.
Both paths emit the same events, pass the same extraction audits, reduce into the same checkpoints, and continue through the same PLAN.md.
Templates
A John template is a version-pinned diff that specializes the shared harness for one app family. Install it as a regular directory, apply it once, and use the resulting merged plugin; the same applied output serves both providers.
cp -R /path/to/template ~/.claude/plugins/joharnessburg-templates/<name>
~/.claude/plugins/joharnessburg-templates/<name>/apply.sh
For Claude Code, launch the printed path:
claude --plugin-dir ~/.claude/plugins/joharnessburg-applied/<name>
For Codex, activate that same merged plugin in the target project:
python3 ~/.claude/plugins/joharnessburg-applied/<name>/scripts/activate_codex_template.py \
--merged-plugin ~/.claude/plugins/joharnessburg-applied/<name> \
--project-root /path/to/project
Follow the printed steps: add the project-local marketplace, install the applied listing, verify it with codex plugin list, disable vanilla john@joharnessburg for that project, inspect and trust the applied hooks through /hooks, and restart Codex. Activation prepares project-local files only; it does not change personal marketplace or global plugin state automatically.
Do not delete an applied directory while a live session is using it. See the template authoring guide for the format and Hamster for dual-provider examples and a guided authoring workflow.
Prerequisites and optional services
- Python 3.10+ for John's standard-library toolkit.
- Optional
markitdown for non-PDF conversion.
- Optional PPX-compatible service at
$JOHN_PPX_CLIENT_URL for high-fidelity PDFs.
- Optional OpenAI-compatible workerLLM service at
$JOHN_LLM_CLIENT_URL for produced apps that need runtime model calls.
John installs and runs without the optional services. They are external URL contracts, not package dependencies.
Hook trust
hooks/hooks.json is John's sole hook declaration. Hooks execute the bundled scripts with the active coding session's permissions. Review this file and the referenced scripts before trusting an unfamiliar fork. Codex users must review and trust the current definition through /hooks; plugin installation or enablement alone is not trust.
Repository layout
.claude-plugin/marketplace.json Claude marketplace
.agents/plugins/marketplace.json Codex marketplace
plugins/joharnessburg/
.claude-plugin/plugin.json Claude manifest
.codex-plugin/plugin.json Codex manifest
hooks/ shared hook declaration
skills/ shared + provider adapter skills
commands/ Claude slash commands
agents/ canonical Markdown agents
codex/agents/ generated Codex agents
scripts/ deterministic toolkit
templates/ apply script and authoring guide
CONTEXT.md canonical vocabulary
Credits
John is maintained by kitchen-engineer42, with contributions and field evidence from @HalfMoon001, @oubeichen, @Ruilin-mmwa, and @AnselKocen.
License
MIT. See LICENSE.
