John - Harness para Aplicações Ricas em Conhecimento
kitchen-engineer42/joharnessburg
Construa apps densos em conhecimento a partir de corpora desestruturados
Ver no GitHubAgent que encapsula Claude Code em skills, hooks e slash commands para transformar corpus desestruturado (PDFs, regulações, documentos) em aplicações standalone que executam mecanismos fixos sobre muitas entradas uniformes de conhecimento. Orquestra fases de engenharia de conhecimento e construção de app em sessões longas, com suporte a templates, evolução de skills e subagentes paralelos.
Instalação
npx convez-ai kitchen-engineer42/joharnessburg1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Transformar regulações/políticas em apps de conformidade automatizadas
- Extrair e estruturar conhecimento de livros/documentos para consulta inteligente
- Orquestrar pipelines paralelos de processamento de conhecimento com subagentes
- Construir aplicações standalone que rodam localmente sem plataforma externa
Veredito

John é uma ferramenta sofisticada e bem arquitetada para quem precisa construir aplicações complexas baseadas em processamento de corpus. Exige familiaridade com Claude Code, workflows agnósticos e engenharia de prompts; o retorno é alto para casos de uso enterprise (compliance, extração regulatória, apps de conhecimento), mas a curva de aprendizado é íngreme.
README
A tradução para o português deste README ainda está na fila.
joharnessburg
John is the plugin (slash commands /john:init, /john:status, …); joharnessburg is the marketplace/repo it ships from — pronounced "jo-harness-burg" (the harness is in the middle), or "jo-hannesburg" if you prefer the city pun. Hence claude plugin install john@joharnessburg.
John wraps Claude Code in skills, hooks, slash commands, and a small toolkit so it can take unstructured input (books, regulations, mixed docs) through the knowledge phases (knowledge engineering) and the app phases (app building) in one long-running session — and produce a working knowledge-dense app: an app that runs a fixed mechanism over many uniform knowledge entries, where the entries come from your corpus. Produced apps run standalone by default (locally, .env-configured, no external platform assumed); templates can add platform integration.
The project's canonical vocabulary lives in CONTEXT.md; a handful of design decisions are recorded in docs/adr/.
中文版:
README_ZH.md
Install
claude plugin marketplace add kitchen-engineer42/joharnessburg
claude plugin install john@joharnessburg
# Verify
claude plugin list
# Expect: john@joharnessburg listed, status enabled
After install, the using-john skill auto-loads when you start a fresh Claude Code session. That's John's orientation entry point — Claude reads it and orients itself to the harness.
Quick start
Open a fresh Claude Code session in a project directory. John's using-john skill should trigger on session-start; if not, ask Claude "what is John, how do I use it here?" — that phrasing triggers it.
The natural flow for a new John project:
- (Optional) Apply a template for your app family before launching the session. See Templates below — install at
~/.claude/plugins/joharnessburg-templates/<name>/, run itsapply.sh, then launch Claude with--plugin-dir. Skip for vanilla John. - Scaffold a workspace — run
/john:init(or just tell Claude "set up John in this dir"). This createsPLAN.md,CLAUDE.md, and a.john/working directory in your project. - Drop your inputs into
.john/input/(PDFs, regulations, sample documents — whatever the produced app should be built from). - Tell Claude what kind of app to build. Claude advances through the phases declared in
PLAN.mdvia ralph_loop (the iterative driver), dispatches parallel subagents per phase, and ends with a working app.
Along the way the session learns from the run (the skill-evolution skill, v0.3.x): lessons are distilled into .john/lessons/ at phase boundaries, skill invocations and phase-gate verdicts are recorded for the deterministic process scorecard (scripts/process_scorecard.py), and — where a template ships a scorer — the produced app's workerLLM skills can be trained with a held-out-gated edit loop during the build.
Other slash commands available after install:
/john:status— current phase + progress/john:report— assemble the run report (scorecard + outcome + scrubbed lessons; the evidence a template owner aggregates — sharing is always manual)/john:archive— archive a finished workspace/john:endurance— set/clear the long-running goal (pinned into the system prompt; survives context compaction)
Running John with dynamic workflows
John's vertical axis — fanning out hundreds-to-thousands of per-entry subagents (extract every chunk, apply every rule, render every slide) — maps directly onto Claude Code's dynamic workflows: Claude writes a script that runs the fan-out off its context, adversarially cross-checks the workers, and writes every result to John's event log. The vertical-workflows skill teaches Claude the John-shaped fan-out; you set the session up so it fires on the right phases and not on everything.
Requirements: Claude Code with dynamic-workflows support (research preview; a recent build on a paid plan), feature enabled.
Recommended session config (these are your moves — John reads them, it can't set them for you):
- Turn on ultracode. Run
/effort ultracodeat the start of the session. This is what lets Claude author a workflow autonomously; John's skills then steer it to the heavy fan-out phases and keep small/coupled/interactive work inline. Ultracode is per-session — it resets when you start a new session, so set it each time (it needs a model that supportsxhigheffort). - Pre-seed your permission allowlist. Workflow subagents inherit your tool allowlist; un-allowlisted Bash/web/MCP calls still prompt mid-run and will stall an unattended pipeline. Add the tools John's agents call (Read/Write/Grep/Glob/Bash + your workerLLM and ppx client calls) to your allowlist before a long run.
On the keyword trigger — nothing to turn off. Claude Code's per-prompt workflow trigger is now the word
ultracode(it changed fromworkflowin a mid-2026 update, with Claude using judgment so an incidental mention no longer hijacks a run). John's skills and your messages say "workflow" constantly and that no longer starts a run — so/effort ultracodefor the session is all you need; typeultracodein a prompt only when you want a one-off run.
Fallback: none of this is required. If workflows aren't available (older Claude Code, feature off, not in ultracode), John runs the same fan-out as inline subagents — same events, same reducer, same PLAN.md, same output. Nothing below the execution line changes; you just don't get the off-context scale and the built-in cross-check. John checks availability before its first fan-out phase and tells you the recipe above if the session isn't configured.
Endurance mode note: if you set an endurance goal (/john:endurance <goal>), John assumes you've done the config above and will not pause a long run to re-confirm it — set up the session first, then start the run.
Upgrade
claude plugin marketplace update joharnessburg
claude plugin update john@joharnessburg
# Restart Claude Code for the new version to take effect.
Note:
claude plugin installis a no-op when the plugin is already installed. Useclaude plugin update <plugin>@<marketplace>for upgrades. Auto-update is OFF by default for third-party marketplaces; enable via the/pluginUI → Marketplaces → joharnessburg → Enable auto-update if you want it on.
Prerequisites
- Python 3.10+ — the plugin's toolkit scripts use stdlib only; system Python is fine.
- For non-PDF document parsing (
markitdown_parse.py):pip install markitdown. - For PDF parsing: an external
local_clients/ppx/FastAPI server wrappingmemect-ppx. See Local clients below. - For workerLLM calls at runtime: an external
local_clients/llm/FastAPI server. Also under Local clients.
Both parser dependencies are optional. The plugin installs and using-john loads regardless; parser scripts fail loud with install instructions when invoked without their deps.
Templates
Templates specialize John for a family of apps. A template is a diff against original John that purpose-builds the harness for one kind of pipeline (overriding some skills, adding new ones, shipping a starter PLAN.md skeleton).
The three-step flow:
# 1. Install the template (copy or symlink into user-scope template dir)
cp -R /path/to/your-template ~/.claude/plugins/joharnessburg-templates/your-template
# 2. Apply it (produces a merged plugin at ~/.claude/plugins/joharnessburg-applied/<name>/)
~/.claude/plugins/joharnessburg-templates/your-template/apply.sh
# 3. Launch Claude with the merged plugin
cd /path/to/your-project
claude --plugin-dir ~/.claude/plugins/joharnessburg-applied/your-template
The merged plugin IS John for that session — all template skills load equally with the core ones; there's no second-class "template layer." Which template is loaded is fixed at session start; to switch, exit and relaunch with a different --plugin-dir. Multiple applied templates can coexist (parallel Claude sessions can use different ones).
To reset: rm -rf ~/.claude/plugins/joharnessburg-applied/<name>/ (or wipe all with ~/.claude/plugins/joharnessburg-applied/). The next launch without --plugin-dir uses vanilla John.
Where to find templates: This plugin ships no bundled examples — that keeps John's runtime focused on the one template you load (or none). Reference examples (functional demonstrators of the diff format) live in the companion tool Hamster (github.com/kitchen-engineer42/hamster) under examples/. Real production templates ship separately from your team.
To author your own template, see plugins/joharnessburg/templates/README.md for the diff-script architecture, directory anatomy, and apply.sh mechanics. For a guided, Claude-driven authoring experience, use Hamster — it ships skills + a methodology that walk Claude Code through building a template from raw inputs.
Local clients
For LLM calls + PDF parsing, John talks to external FastAPI servers that you run alongside the plugin. They live OUTSIDE the plugin (workspace-level) so you can swap providers without changing John itself.
The plugin's parsing + workerllm-runtime skills teach Claude to call them via env-var-configured URLs:
$JOHN_LLM_CLIENT_URL(defaulthttp://localhost:8500) — workerLLM client (wraps SiliconFlow + DeepSeek today).$JOHN_PPX_CLIENT_URL(defaulthttp://localhost:8501) — PDF parser client (wrapsmemect-ppx, theppxparser engine at github.com/kitchen-engineer42/ppx).
When your team ships its own production servers (on-prem or different providers), swap these env vars — nothing inside John changes.
One-time setup (per machine)
Prerequisite: uv installed. Get the John workspace bundle (which contains local_clients/ + setup_john.sh) — contact the project owner for access if you don't already have it.
# 1. Clone the ppx engine outside the workspace
git clone https://github.com/kitchen-engineer42/ppx.git ~/code/ppx
# 2. Run the workspace setup script — creates venvs + installs both clients
cd /path/to/john-workspace
./setup_john.sh
# First run will create .env from .env.example; fill in SILICONFLOW_API_KEY + DEEPSEEK_API_KEY.
# 3. Install the ppx engine into the ppx client's venv
cd /path/to/john-workspace/local_clients/ppx
uv pip install -e ~/code/ppx
# 4. Verify
cd /path/to/john-workspace
./setup_john.sh
# Should report: "memect-ppx is installed in the ppx client's venv."
Per-session launch
cd /path/to/john-workspace
./start_john.sh
# Reports both clients' liveness; prints the env vars to export.
# Then in your Claude Code shell (or persist in .zshrc / .bashrc):
export JOHN_LLM_CLIENT_URL=http://localhost:8500
export JOHN_PPX_CLIENT_URL=http://localhost:8501
# Launch Claude Code in your project:
cd /path/to/your-project
claude
To stop:
cd /path/to/john-workspace
./stop_john.sh
Smoke test (verify the chain works end-to-end)
# LLM client health + provider inventory
curl -s http://localhost:8500/healthz | jq
# Actual LLM call (should return "OK" or similar)
curl -s http://localhost:8500/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"reply with just OK"}]}' | jq
# ppx client health (should say "ppx: available")
curl -s http://localhost:8501/healthz | jq
Reference docs
local_clients/llm/README.md— LLM client install + API contractlocal_clients/ppx/README.md— ppx client install + API contractplugins/joharnessburg/skills/workerllm-runtime/SKILL.md— how the plugin teaches Claude to call these clients
What's in this repo
.claude-plugin/
marketplace.json # Marketplace catalog (this repo is also a marketplace)
plugins/
joharnessburg/ # The plugin itself
.claude-plugin/
plugin.json # Claude Code plugin manifest
hooks/hooks.json # Hook declarations (auto-registered on install)
skills/ # John's meta-skills (loaded into John-wrapped Claude Code sessions)
commands/ # Slash commands
scripts/ # Small Python toolkit (ppx wrapper, event reducer, apply_template, etc.)
agents/ # Subagent role definitions
templates/ # Universal apply.sh + authoring guide (templates/README.md)
CONTEXT.md # The project glossary — canonical vocabulary
docs/adr/ # Architecture decision records (short)
README.md # This file
README_ZH.md # 中文版
LICENSE # MIT
Acknowledgments
- @HalfMoon001 — heavy field-testing of John end-to-end, and the analysis behind the
job-runtimeskill (#2): the produced-app long-running I/O job pattern (task registry, slot leases, split queue/generation budgets, resumable progress) was specified from her testing and issue work.
License
John (joharnessburg) is released under the MIT License — see LICENSE. Use it, fork it, build on it freely.
Vanilla John and its companion tool Hamster are MIT. Domain-specialized variants built on top of John (e.g. KC Agent CLI) may be offered under separate commercial terms.