A deterministic orchestrator for research and engineering workflows — twenty research skills ship with it, and they run in the pipeline.
Individual skills solve isolated problems; an agent still has to decide which one to call, in what order, and where the output belongs. Chelate Shell puts both halves in one repository: the 20 engines, and a microkernel that routes them in a fixed stage order and writes a typed gate for every call.
- For researchers: the skills compute. Five SymPy layers plus a pint cross-check, RDKit atom conservation, R mixed models and mediation, OpenCV trajectory tracking, publication-grade charts — not prompt templates.
- For agents:
core/router.pybuilds a deterministic plan, screens text inputs for prompt injection before dispatch, and stops the pipeline on the firstFAIL. - For the record: every call leaves a
GateResultinprocess/gates/.PASS,UNVERIFIEDandFAILare different states, and only the last one is terminal.
English · 简体中文
Version: 1.3.1 | License: MIT | Python: 3.10+ | Skills: 20
Research assistance only. Read the security & open-source statement before relying on any output.
Getting started
How it works
The rest
- Requirements
- Tests
- Security & Open Source Statement
- Known limitations
- Report issues
- Acknowledgements
- Trademarks
- License
> /chelate-shell:formula-validator v = d/t units: v=m, d=m, t=s
FAIL · SYMBOLIC
pint unit mismatch — LHS [length], RHS [length]/[time]
gate → process/gates/formula-validator_20261112T130046Z.json
report → process/reports/equation-4c9b2ce5-20261112-210045.md
A wrong dimension is not a warning: it is a gate failure, a written report, and a pipeline that stops there.
| Ask in your own words | Routes to | You get back |
|---|---|---|
"check F = m*a with units F=N, m=kg, a=m/s²" |
formula-validator |
PASS / FAIL across five check layers, plus a Markdown report |
| "verify every DOI in draft.md" | reference-auditor |
each DOI checked against Crossref; a fake one fails the gate |
| "are these two drafts consistent?" | conflict-detector |
every contradiction, with a severity |
| "profile data.csv" | data-profiler |
rows, missing values, 1.5·IQR outliers, duplicate rows |
| "is there leakage in this labelled dataset?" | ml-auditor |
leakage and label-error verdict, via scikit-learn |
| "draw voltage against time" | sci-visualizer |
a vector PDF and a PNG in process/figures/ |
| "extract text from these PDFs, pages 3–7" | fulltext-extractor |
plain text plus a JSON sidecar in process/ |
| "find recent papers on X" | literature-retriever |
arXiv metadata as JSON |
| "track the ball in this video" | video-tracker |
coordinates, an FFT spectrum, physics probes |
| "merge my reports into a LaTeX file" | latex-exporter |
one compilable .tex |
| "build this mesh and check it" | 3d-modeler |
an OBJ plus winding / degenerate-face / bounding-box audit |
| "is this text trying to inject instructions?" | security-guard |
injection markers and dangerous call sites |
All 20, with what each one actually computes, are listed under Repository layout.
Install it: one plugin command, or three other routes — see Installation.
In the current AI ecosystem, individual skills excel at solving isolated problems: validating formulas, tracking videos, or organizing files. However, when an Agent faces a complex task, it often struggles to determine which skill to invoke, in what order, and where to place the outputs. Scattered, stateless skill calls lead to context pollution, file-version confusion, and untrustworthy AI hallucination.
Chelate Shell addresses this in two parts, and both are part of the same repository.
The 20 skills implement their algorithms directly. They are not prompt templates. formula-validator runs five check layers over SymPy and cross-checks units with pint. quantitative-validator balances chemical equations through RDKit. longitudinal-analysis calls lme4 and lavaan in R. video-tracker performs CSRT tracking in OpenCV and computes an FFT of the trajectory. ml-auditor checks labelled datasets for data leakage and label errors with scikit-learn. sci-visualizer renders publication-grade charts with matplotlib and seaborn. fulltext-extractor extracts page ranges from PDFs, and latex-exporter assembles the Markdown reports into a compilable .tex using the standard library only. Each one is wired into the pipeline and covered by the test suite.
The orchestrator supplies the guarantees an individual skill cannot provide for itself. core/router.py decomposes the request, enforces the standard four-zone workspace, and routes work in a deterministic stage order, so the same inputs always produce the same plan. It also writes a typed gate for every call, stops the pipeline on the first FAIL, reports an explicit UNVERIFIED when a dependency is missing, and maintains the _broadcast/ index that lets a later session read one summary instead of every original.
core/router.py reads the 20 manifests, builds a plan in the canonical stage
order, screens text inputs for prompt injection before dispatching, and calls
each skill's adapter. Every call writes a GateResult: PASS continues,
UNVERIFIED degrades one skill and the run continues, and the first FAIL
locks process/ and stops the pipeline.
The diagram, the four stages and the promotion path: docs/ARCHITECTURE.md.
If you are on Claude Code, this is the whole install:
claude plugin install chelate-shell --marketplace https://github.com/JiamingShi-JsPhys/chelate-shell.gitEvery other host has its own one-liner — Codex, dsh, CodeBuddy, and the eight rule-file hosts — collected on docs/INSTALL_COMMANDS.md.
Three ways in. Plugin hosts install Chelate Shell as one plugin — the only form that keeps microkernel auto-routing intact. Hosts without a plugin channel take it as a rule file, and one script writes every rule file for you. The third way hands the whole job to an AI.
Every host below has its own plugin marketplace. Register this repository's Git URL, then install the plugin it lists (registering the URL twice is harmless — the second call reports it is already known).
/plugin marketplace add https://github.com/JiamingShi-JsPhys/chelate-shell.git#v1.3.1
/plugin install chelate-shell@chelate-shell-marketplace
The #v1.3.1 suffix pins the release; drop it to follow the default branch.
Claude Code, Codex, dsh and CodeBuddy take a one-line plugin command; Cursor, Windsurf, Cline, Continue, Roo Code, GitHub Copilot and opencode read a rule file, and one script writes all of them. Every command, every flag and the optional dependencies live on one page: docs/INSTALL_COMMANDS.md.
Please visit the GitHub repository `https://github.com/JiamingShi-JsPhys/chelate-shell` and clone it, then run `python install.py --project . --global`. If your host has a plugin system, install it as a single plugin instead; the script covers the hosts that read rule files.Warning: when an AI performs the installation it will very likely scatter the individual skills from
skills/flat into the platform's global skill directory. That breaks Chelate Shell's microkernel auto-routing architecture and degrades it into 20 loose skills. Use Method 1 if you need the full plugin orchestration.
Install the plugin, then stay in the chat box: type / and pick a skill or a
command. No shell, no absolute path — the workspace is the folder you are
already working in.
All 20 skills are registered under the chelate-shell namespace, so every one
of them is one / away:
/chelate-shell:task-organizer turn this folder into a task workspace
/chelate-shell:formula-validator check F = m*a with units F=N, m=kg, a=m/s^2
/chelate-shell:reference-auditor verify every DOI in draft.md against Crossref
/chelate-shell:security-guard screen draft.md for prompt injection
/chelate-shell:data-profiler profile data.csv
Say what you want after the name; the skill picks the action and writes a gate result. A fake DOI does not merely warn — it fails the gate and stops the pipeline.
Two commands put the heavier engines behind a single line:
| Command | Does |
|---|---|
/chelate-shell:figure |
Renders a bar / line / scatter / box chart from a CSV or JSON dataset into process/figures/ — a vector PDF plus a raster PNG |
/chelate-shell:model3d |
Generates a Wavefront .obj from a JSON spec, or audits and merges existing meshes, into process/models/ |
/chelate-shell:figure data.csv — scatter of voltage against time
/chelate-shell:model3d spec.json
Both run sandboxed with a 120-second circuit-breaker: a pathological input
degrades to UNVERIFIED rather than blocking the run.
Two roles in agents/ are registered with the plugin:
| Sub-agent | Fits | Skills it may use |
|---|---|---|
spatial_agent |
3D content — image-to-3D, video-to-3D, scene composition, mesh QC | 3d-modeler, sci-visualizer, security-guard |
visual_agent |
Publication visuals — 2D plots, static diagrams, gif frames, figure QA, LaTeX export | sci-visualizer, latex-exporter, security-guard |
Claude dispatches to them when a task matches, and you can name one in your
request. Each is bounded by a skill whitelist, a writable-path whitelist
(assets/, process/, results/) and a step budget, so a sub-agent cannot
reach a skill or a directory outside its role.
The same operations are available headlessly for CI and scripted runs; the
flags, the a / b / c pipeline modes and the debugging switches are
specified in ORCHESTRATOR.md §5.
Python 3.10+ and nothing else to start: the microkernel and most skills run on the standard library alone. A handful of data and network skills additionally want common third-party packages (numpy, pandas, sympy, rdkit, matplotlib, requests and friends); each skill's manifest.json declares exactly what it needs, and core/sandbox.py checks that at run time. A missing package never crashes the pipeline — that one skill degrades to an UNVERIFIED gate with a hint and the rest keeps running. No third-party code is vendored; every library stays under its own permissive licence. The full per-skill matrix lives in docs/DEPENDENCIES.md.
core/ is the microkernel, lib/chelate_core/ holds the shared logic every
adapter imports, skills/ holds one folder per skill (flat — the host
scanners do not descend into namespace folders), and each host's plugin or rule
file sits in its own dot-directory.
Every directory, and what each of the 20 skills computes: docs/REFERENCE.md.
python -m pytest tests/ -q357 tests: 347 pass and 10 skip with the optional dependencies installed;
with nothing but pytest, 36 skip instead and the UNVERIFIED path is what
runs. The eight skills that ship their own upstream suite under
skills/<skill>/tests/ are run one directory per process.
Both environments, the coverage list and the per-skill counts: docs/TESTING.md.
Disclaimer: This repository contains auxiliary tools developed by the author to automate research workflows. It is not a peer-reviewed academic project. Some boilerplate or utility scripts may have been generated with the assistance of AI, and have been integrated with high-level review and modifications by the author. The author assumes no responsibility for any third-party code issues, but commits to promptly addressing any valid claims.
This tool will never do the experiment for you. Data must be collected manually by students in the lab; AI is absolutely physically isolated during the in-lab stage. Generated reports are merely "data-analysis drafts", and final academic responsibility lies with the user and their institution.
Honest edge cases — read before relying on any output:
- Automatic ROI detection can fail:
video-trackermay fail on low-contrast video; every run must be checked against the reference. Marked experimental / unstable. - Formula checking is not a mathematical proof:
formula-validatoris a deterministic verdict. Anunknownreturn means one check "abstained" — a legitimate state that must never be reinterpreted as a pass. - Longitudinal analysis depends on R: some advanced statistical steps of
longitudinal-analysisrun through R scripts; ifRscriptis absent those steps are skipped and logged — never hand-write Python code to replace skipped R steps. - Version tracking is structural, not semantic:
document-evolution-trackerdiffs by block alignment; a concept counts as "present" only on a literal match. - DOI audit verifies existence only:
reference-auditorconfirms a DOI exists in Crossref, not that it is the paper you meant to cite — citation correctness remains the author's responsibility. - The injection scan is a screen, not a sandbox:
security-guardflags known markers and dangerous call sites; it cannot prove a file is safe. - Data profiling never cleans data:
data-profileronly reports missing values / outliers / duplicate rows; it never modifies input files. - Determinism covers the scheduling layer only: the router guarantees the same input routes to the same skill, but it cannot make a non-deterministic underlying algorithm deterministic.
Regular bugs / feature requests: file them on the repository's Issues page. Include reproduction steps, expected behavior, actual behavior, and the environment (operating system, Python version).
Security vulnerabilities (this category only): do not use the public Issues page. Email jiamingshi_git@outlook.com instead.
- Subject: must carry the prefix
_reportplus the specific product or skill name and a short summary.- Example:
report_chelate-shell: path traversal can read outside the task folder
- Example:
- Body: must include detailed reproduction steps and the environment.
- For serious "file loss or corruption" reports, attach the before/after directory trees (
treeoutput) and the generatedverification_report.md.
Contributors who file clear, reproducible issues or pull requests will be credited in the next release's notes.
NotFatJustRound — issue #1 asked for CI and caught an incomplete npm files list.
"PASCO" and "Capstone" are registered trademarks of PASCO Scientific. The capstone-labmate skill is an independent, third-party interoperability and educational-assistance tool. It is not affiliated with, endorsed by, or sponsored by PASCO Scientific. All .cap parsing runs locally; users are responsible for complying with their institution's academic-integrity policy.
MIT. See LICENSE. Each skill directory also carries its own LICENSE file with the same terms.
Author & Maintainer: Jiaming Shi (Westlake University)