qingye-lab/rootloomGit

Rootloom engineering workflows

Use small, reviewable changes and traceable evidence to guide software delivery.

Before you start

Inputs: Codebase, technical environment and acceptance criteria

Check the original documentation for supported AI tools, models and runtime dependencies.
Open the repository and follow the author’s installation instructions. Model APIs or external services may require separate accounts.
Try your own material, then review the facts, layout and output files.

Read the original installation guide ↗

License: MIT

Source snapshot: 2026-09-15. README ↗

Original license & copyright

MIT License

Copyright (c) 2026 liyanqing

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Try a task like this

Use Rootloom engineering workflows with my own source material. Confirm the required inputs and available tools, then produce an editable result.

Rootloom

Turn Codex code changes into inspectable engineering work.

A native OpenAI Codex plugin for finding the right place to change,
plus an Agent Plugins preview for portable Change, Review, and Project Guidance.

Website · 简体中文 · English

What is Rootloom?

Rootloom is a local engineering workflow with a full native OpenAI Codex plugin and a separate Agent Plugins portable preview. The native plugin exposes four Skills for changing code, reviewing changes, maintaining repository guidance, and managing optional setup. The portable preview exposes Change, Review, and Project Guidance without Codex-only Hooks or Setup. Rootloom is not another coding agent and it does not replace your editor, tests, or CI. Governed and machine-evidence work remain modes of Change, not extra public workflows.

You still describe the task in plain language. Rootloom changes how Codex approaches it:

read the repository and its local rules before editing;
judge the risk and define a sensible scope;
for a defect, trace the symptom to the boundary that owns the behavior;
make the smallest coherent change;
verify the main path, the owning invariant, and an adjacent path;
report the commands that actually ran, their results, and what remains uncertain.

For most work, this is the only invocation you need:

$operating-coding-change
Fix the reconnect race and verify reconnect, clean disconnect, and cancellation.

Why use it?

Coding agents are good at producing plausible patches. Plausible is not the same as correct, reviewable, or complete.

A common failure	What Rootloom asks Codex to do instead
Patch the line closest to the error	Find the component that owns the violated behavior
Keep editing until one test passes	State the intended scope and preserve unrelated work
Test only the happy path	Check the primary path, the invariant, and a nearby alternate or failure path
Say “tests passed” without a useful record	Name the exact commands that ran and the result of each
Treat exit code 0 as proof of completion	Check whether scope, repository state, or captured evidence changed afterward
Add process to every task	Use a lightweight daily workflow; opt into deeper evidence only when it changes a decision

The practical value is simple: fewer fixes at the wrong layer, smaller diffs, clearer reviews, and completion claims you can inspect.

Rootloom makes the work easier to examine. It does not make a model infallible or turn passing tests into proof of correctness.

Quick start

You need Codex CLI or desktop with plugin support, Git, and Python 3.11+.

1. Install the plugin

codex plugin marketplace add liyanqing90/rootloom
codex plugin add rootloom@rootloom

Installation is complete after those two commands.

2. Start a new Codex task

Plugin Skills are discovered when a task starts. No project configuration, daemon, or separate Rootloom command is required.

3. Ask for the work

$operating-coding-change
The worker can reconnect after cancellation and create two active sessions.
Find the cause, fix it without changing the public API, and run the relevant tests.

A useful completion report should now answer four concrete questions:

Cause        Where did the behavior originate, and which invariant was broken?
Change       Which files and behavior changed?
Verification Which commands actually ran, and what did each prove?
Risk         What remains unverified or uncertain?

That is Rootloom's everyday path. You do not need an evidence bundle, global setup, or every Skill in the plugin to use it.

Read large files in proportion to the task

Start with bounded reads that answer the task. When repeated reads or substantial context cost justify preprocessing, Change can use the optional Artifact Context Lane: a local standard-library helper hashes and deduplicates files and caches intent-specific receipts. Raw bytes stay at their source; finalized receipts are capped at 24 KiB. Preparation accepts up to 16 files, at most 512 MiB each and 1 GiB of unique contents. Once the unique total exceeds that limit, it rejects the bundle before reading later files or writing a manifest or draft; duplicate contents count once.

A cache miss can use one host-owned worker with no inherited conversation. If that facility is unavailable, continue with bounded reads and skip the receipt optimization. Explicit user isolation, file access, upload, and retention limits still apply. The helper makes no model or network request; the optional worker adds a model call, while cache hits add none. Rootloom cannot erase already-recorded attachments or task history and does not require a fresh task merely because a file was already read.

Agent Plugins portable preview

portable/rootloom/ is a separate Agent Plugins 1.0.0 package containing exactly operating-coding-change, operating-code-review, and project-guidance. Compatible clients discover those Skills from the package's root plugin.json and fixed skills/ directory. Installation, updates, permissions, and client UX remain client-owned parts of the Agent Plugins Working Draft, so use the target client's own flow and select portable/rootloom/ as the plugin root.

Cursor, VS Code, GitHub Copilot CLI, and Kiro use this same package without platform manifests or duplicated Skills; only their loader configuration differs. Copilot cloud still needs a published, resolvable marketplace entry, which Rootloom does not yet provide. Codex keeps its native package because its managed Hook, Setup, and interface surface are intentionally larger than Agent Plugins v1.

The preview includes Review, Project Guidance, and Direct, Scoped, and Governed Change. Persistent guidance still requires exact user intent. The package deliberately omits Setup, Hooks, Rules, Memory, MCP, OpenAI UI metadata, and the plugin-wide Evidence helpers. It includes the optional standard-library Artifact Context helper. Hosts without a no-history worker can use ordinary bounded reads without creating a cached semantic receipt. An explicit Evidence request therefore fails closed instead of fabricating an evidence bundle. Do not install the native and portable packages into the same client because duplicate-Skill precedence is not standardized.

Repository checks prove package shape, containment, Agent Skills metadata, relative References, and synchronization with the native source. A disposable Codex CLI smoke also proves that Codex can install an isolated package whose Skill surface contains exactly those three directories and a self-contained helper. Static and synthetic tests also exercise opt-in host adapter envelopes, but do not prove runtime discovery, activation, or identical behavior in Cursor, VS Code, GitHub Copilot, Kiro, or every other compatible client. See Agent Plugins portable preview for exact Cursor, VS Code, Copilot, and Kiro loading instructions, runtime smoke gates, migration, and rollback.

Choose the workflow that matches the task

You want Codex to…	Use	When to reach for it
Build, fix, refactor, migrate, deploy, or capture strict evidence	`$operating-coding-change`	The single implementation entry; it routes Direct, Scoped, Governed, Evidence, and External Action modes
Review a diff, PR, migration, or design without editing	`$operating-code-review`	You want findings and evidence, not a patch
Seed, refresh, refine, or validate repository `AGENTS.md`	`$project-guidance`	Project commands or durable invariants should persist
Install, upgrade, inspect, or roll back optional global setup	`$setup-rootloom`	You want cross-project guidance or Autonomy Rules

Rootloom Core always presents these four entries. Change loads detailed governed, external-action, verification, or Evidence References only when the task requires them. Version numbers and serialized artifacts do not trigger compatibility by themselves: regenerable internal records stay Scoped and current-only, while rollback restores the complete old release and historical replay uses its matching runtime. Runtime compatibility requires evidence of a real post-cutover consumer. Project Guidance may validate when active repository guidance requests inspection, but persistent seed, refresh, or refinement requires explicit user intent; natural-language requests naming the guidance file are sufficient and need not name the Skill. A repository may authorize one refinement of one file only with the exact standalone  marker; repository prose alone never authorizes a write.

How an ordinary change works

Your request
    ↓
Repository evidence and local guidance
    ↓
Risk + scope
    ↓
Root cause for a defect / intended behavior for a feature
    ↓
Focused change
    ↓
Behavior-based verification
    ↓
Evidence-backed completion report

For a defect, Rootloom pushes the investigation toward an explicit chain:

symptom → trigger → owning boundary → violated invariant → cause

For a feature, there is no invented “root cause”; the workflow states the intended behavior and ownership instead. Verification is derived from what changed rather than from whichever test command is easiest to run.

Why “the command passed” is not enough

Rootloom's own development produced a useful example. A verification command exited successfully, but while running it created a newly ignored .env file and copied its synthetic value into an ordinary file. The command passed; the reviewed repository state did not remain the same.

The post-verification capture caught that difference, quarantined the sensitive path, kept changed content out of the patch bundle, and failed the strict review instead of issuing a passing completion claim.

The full scenario and executable regression are documented in The command passed, the review failed.

When you need stronger evidence

Most tasks should stay on the normal edit-and-test path. When a change needs a reproducible local record, ask $operating-coding-change explicitly for Evidence Mode.

The optional evidence path can bind:

the Git and repository state before the change;
allowed and forbidden paths;
behavior claims to commands that actually ran;
a second repository capture after verification;
machine-observed results separately from human semantic judgment.

It produces a local bundle containing the captured patch, test log, and machine-readable summary. This is an inspectable review record, not a security proof or an immutable audit system. See Architecture and Maturity and guarantees for the exact contract.

For the usual strict intake → edit → finalize loop, resources/evidence/orchestrate_evidence.py offers prepare and finish. It composes the existing intake, sealed contract, and finalizer without changing their wire formats. finish still requires an explicit semantic-review assertion. This is a single-command verification convenience path: multiple targets or specialized commands, migrations, mixed-version checks, security boundaries, and build-plus-runtime proof use the low-level lifecycle.

Technical contract reference

Rootloom 4 Core remains An inspectable personal engineering workflow for Codex. Its public surface is Change, Review, Project Guidance, and Setup. Optional Autonomy is installed through Setup; deterministic Evidence is an explicit Change mode. Experimental Project Memory is a separate plugin and repository evidence remains authoritative.

The opt-in Evidence path uses resources/evidence/analyze_change.py for advisory analysis. analyze_change.py --write-baseline can write analyzer-only evidence, while governed intake publishes an exact contract with seal_contract.py. Strict review uses --strict; machine consumers should read quality_status and the stable capability field evidence_complete. REVIEW_EVIDENCE_COMPLETE means the evidence chain is complete, while REVIEW_REQUIRED_WITH_REDACTIONS means material redaction prevents that claim.

Core Reset v2 retains historical model comparisons and the optional research command make core-reset-release-eval CORE_RESET_RESULTS=/absolute/path/results-v2.json. Its fixed 135-cell matrix and historical efficiency thresholds are no longer release gates. The retained 4.3.0 report describes that version only; it is not evidence for a later candidate.

Current releases use checks selected from the actual change, package/Setup validation, and behavior comparisons when the workflow changes. The 4.4 change uses six scenarios with one current/candidate pair each, serially on the same model, reasoning effort, and isolation. Task outcomes and permission boundaries determine acceptance; latency and available usage are observations. This small comparison cannot establish general performance gains. See the 4.4 workflow decision. The tag workflow checks source/package integrity, Setup behavior, and tag/version identity.

Repository state is accepted only after two consecutive bounded captures agree. Each capture lifecycle is bounded by --max-capture-seconds. A material metadata change, including a newly discovered ignored addition, activates metadata-only quarantine before ordinary content capture. Classification uses is_sensitive_material_path; Rootloom is not a content-aware secret scanner.

--reviewable-path is an intake-only declaration for exact eligible files. It rejects ignored files, symlinks, hardlinks, ambiguous duplicates, strong secret material, and Git entries marked assume-unchanged or skip-worktree. The summary's reviewability_policy reports exact paths and policy_provenance; historical declarations that no longer meet current policy return reintake-required before content is read.

Evidence and bundle paths must be outside both the repository worktree and the resolved Git common directory. Optional authorization modes are Single action, Standard, and Full: Standard is Persistent across tasks, but every task still needs an explicit goal and resolved scope; Full is never inferred. The Archived Assurance Edition remains available at codex/enterprise-assurance without an active maintenance promise.

Optional personal setup

Installing Rootloom only exposes its four Skills. It does not write ~/.codex/AGENTS.md, install command Rules, enable a Hook, run Evidence helpers, or install/read Project Memory.

If you want Rootloom's working agreement across projects, ask for the optional setup explicitly:

$setup-rootloom
Show me the personal preset plan, then install it if there are no conflicts.

Setup is plan-first, backup-backed, conflict-refusing, and reversible within its documented limits. It does not change your model, reasoning effort, sandbox, approval policy, providers, MCP servers, plugins, or apps. See Setup, update, and rollback.

What Rootloom is—and is not

Rootloom is deliberately narrow:

It is a single-agent engineering workflow with a full native OpenAI Codex plugin.
It is an Agent Plugins 1.0.0 portable preview for Change, Review, and Project Guidance.
It is local, inspectable, and Python-standard-library-only at runtime.
It is not a specification framework, test runner, linter, secret scanner, CI system, or replacement for human review.
It is not a sandbox for untrusted verification commands.
It does not promise equivalent Hooks, Setup, permissions, Evidence, or model behavior across coding-agent clients.

Specification tools such as GitHub Spec Kit and OpenSpec help define work before implementation. Tests, linters, scanners, and CI execute their own checks. Rootloom sits at the execution and review boundary: why this change, why here, what ran, and what evidence supports completion.

Product shape

Rootloom Core
├── Change: Direct / Scoped / Governed / Evidence
├── Review
├── Project Guidance
├── Setup
├── Optional Autonomy: authorization modes / Command Rules
└── Optional Evidence resources: Analyzer / Baseline / Contract / Seal / Finalizer

Rootloom Memory
└── Separate experimental plugin

The unmaintained 1.2.19 implementation is preserved as the Archived Assurance Edition. Human approval state machines, immutable audit chains, multi-agent audit runners, and recovery journals are not part of main.

Optional Rootloom Memory

Project Memory is no longer discovered by Core. Install it only when you want explicit, repository-owned historical lessons:

codex plugin add rootloom-memory@rootloom

Its $project-memory Skill preserves rootloom-project-memory-v1, remains advisory, and never overrides current source, tests, schemas, or runtime evidence.

Documentation

Website telemetry

The public GitHub Pages site loads the official VibeLoft browser runtime once from the global index.html. Rootloom does not install a telemetry package, send manual page views, contact Supabase from the browser, or configure an alternate collector. The runtime owns its random first-party device ID, coarse environment digest, GPC/DNT handling, navigation coverage, retry behavior, and failure isolation. Because the published runtime is obfuscated, the release gate pins the exact SHA-256 of a request-blocked browser-reviewed build and fails closed on any upstream change. See the accepted website telemetry decision for the exact boundary, review procedure, and rollback.

Development

make check-changed BASE=origin/main
make validate
make test
make check
make compatibility-smoke
make telemetry-check

# Preview the website at http://localhost:8000
python3 -m http.server 8000

check-changed is the default development path: it selects tests from changed owners across committed, staged, and unstaged tracked work, while excluding unrelated untracked files. Use INCLUDE_UNTRACKED=1 only when they all belong to the task. Unknown executable paths or shared test-selection infrastructure fall back to the full suite. test and check are explicit full-suite targets. CI keeps one canonical full run on main; routine additional environments repeat named compatibility cases, while broad version matrices and full portable subsets are scheduled or manually invoked.

License

MIT