rootloom

KO | EN

gitlite — search

#awesome-list #ai-agent #command-line #generative-ai #ai-agents #kubernetes #mysql #animation #database #editor

(★ 9)

Inspectable engineering workflows for OpenAI Codex.

File Explorer

ZIP Download

- - marketplace.json
- - bug_report.yml
  - config.yml
  - feature_request.yml
- - ci.yml
  - codex-compatibility.yml
  - pages.yml
  - release-evidence.yml
- CODEOWNERS
- PULL_REQUEST_TEMPLATE.md
- release.yml
- design.json
- - capabilities.json
- rootloom-brand.webp
- rootloom-xiaohei-loom-en.png
- rootloom-xiaohei-loom-zh.png
- - passing-command-failed-review.md
  - passing-command-failed-review.zh-CN.md
- - 2026-07-13-personal-core-enterprise-assurance-split.md
  - 2026-07-14-personal-intelligence-contract.md
  - 2026-07-14-tiered-authorization-modes.md
  - 2026-07-15-evidence-honest-strict-review.md
  - 2026-07-15-sensitive-material-and-capture-bounds.md
  - 2026-07-16-personal-core-product-boundaries.md
  - 2026-07-17-vibeloft-web-telemetry.md
  - 2026-07-29-rootloom-4-core-reset.md
  - 2026-07-29-rootloom-4.1-efficiency-loop.md
  - 2026-08-07-setup-transaction-recovery.md
  - 2026-08-07-setup-transaction-recovery.zh-CN.md
  - 2026-08-08-agent-plugins-portable-preview.md
  - 2026-08-08-agent-plugins-portable-preview.zh-CN.md
  - 2026-08-08-unified-host-capability-baseline.md
  - 2026-08-08-unified-host-capability-baseline.zh-CN.md
  - 2026-08-10-global-agents-managed-block.md
  - 2026-08-10-impact-scoped-verification.md
  - 2026-08-10-impact-scoped-verification.zh-CN.md
  - 2026-08-10-regenerable-contract-compatibility-boundary.md
  - 2026-08-10-regenerable-contract-compatibility-boundary.zh-CN.md
  - 2026-08-13-artifact-context-lane.md
  - 2026-08-13-artifact-context-lane.zh-CN.md
  - 2026-09-05-rootloom-4.4-workflow.md
  - 2026-09-05-rootloom-4.4-workflow.zh-CN.md
- - architecture-en.svg
  - [email protected]
  - architecture-zh.svg
  - [email protected]
- agent-plugins.md
- agent-plugins.zh-CN.md
- architecture.md
- architecture.zh-CN.md
- brand.md
- brand.zh-CN.md
- guidance-design.md
- guidance-design.zh-CN.md
- maturity.md
- maturity.zh-CN.md
- migration-4.0.md
- migration-4.0.zh-CN.md
- migration-4.1.md
- migration-4.1.zh-CN.md
- setup.md
- setup.zh-CN.md
- troubleshooting.md
- troubleshooting.zh-CN.md
- - baseline-v3.4.json
  - evaluate.py
  - README.md
  - results-2026-07-29.json
  - results-4.1.0.json
  - results-4.2.0.json
  - results-4.2.1.json
  - results-4.2.2.json
  - results-4.3.0.json
  - results-v1.example.json
  - results.example.json
  - run_matrix.py
  - scenarios-v1.json
  - scenarios.json
  - score_matrix.py
- AGENTS.project.md
- - AGENTS.md
- - AGENTS.md
- - LICENSE
  - plugin.json
- impact_tests.py
- sync_host_adapters.py
- sync_portable_plugin.py
- validate_repo.py
- verify_vibeloft_runtime.py
- - rootloom-loom-en.webp
  - rootloom-loom-zh.webp
  - rootloom-loom.webp
  - rootloom-mark.svg
- main.js
- styles.css
- compatibility_smoke.py
- live_smoke.py
- portable_compatibility_smoke.py
- test_component_hook.py
- test_core_reset_eval.py
- test_core_reset_runner.py
- test_engineering_change.py
- test_evidence_orchestrator.py
- test_host_adapters.py
- test_impact_tests.py
- test_portable_plugin.py
- test_project_memory.py
- test_seed_project_guidance.py
- test_setup_rootloom.py
- test_simple_lock.py
- test_web_telemetry.py
.editorconfig
.gitattributes
.gitignore
AGENTS.md
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
CONTRIBUTING.zh-CN.md
DESIGN.md
index.html
LICENSE
Makefile
PRODUCT.md
README.md
README.zh-CN.md
SECURITY.md
SUPPORT.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Rootloom</h1>

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.

<a href="https://liyanqing90.github.io/rootloom/">Website</a> · <a href="README.zh-CN.md">简体中文</a> · 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:

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

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

```text
$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

```bash
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

```text
$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:

```text
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](docs/agent-plugins.md) 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

```text
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:

```text
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](docs/case-studies/passing-command-failed-review.md).

## 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](docs/architecture.md) and [Maturity and guarantees](docs/maturity.md) 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.

<details>
<summary>Technical contract reference</summary>

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](evals/core-reset/reports/4.3.0.md) 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](docs/decisions/2026-09-05-rootloom-4.4-workflow.md).
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.

</details>

## 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:

```text
$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](docs/setup.md).

## 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](https://github.com/github/spec-kit) and [OpenSpec](https://github.com/Fission-AI/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

```text
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](https://github.com/liyanqing90/rootloom/tree/codex/enterprise-assurance). 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:

```bash
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

- [Architecture](docs/architecture.md)
- [Setup, update, and rollback](docs/setup.md)
- [Maturity and guarantees](docs/maturity.md)
- [Guidance design](docs/guidance-design.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Migrate from Rootloom 3.x to 4.0](docs/migration-4.0.md)
- [Migrate from Rootloom 4.0 to 4.1](docs/migration-4.1.md)
- [Contributing](CONTRIBUTING.md)

## 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](docs/decisions/2026-07-17-vibeloft-web-telemetry.md) for the exact boundary, review procedure, and rollback.

## Development

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

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](LICENSE)

rootloom

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README