@shadowclone/cli 0.0.9 → 0.0.12

package/README.md

@@ -1,104 +1,78 @@
-# shadowclone
+![Shadowclone: your engineering instincts, as portable skills for every coding agent](docs/assets/shadowclone-banner.png)
 
-Shadowclone learns engineering preferences from coding-agent sessions you choose to share with it. It turns explicit guidance and corrections into an editable profile, and keeps a portable personal skill library in sync. Claude Code, Codex, Cursor, and Antigravity can receive that profile in ordinary sessions. Supported delegated runs use the same guidance.
+# Shadowclone
 
-The profile adds context to an existing model; it does not train a new one or guarantee that every instruction will be followed. With separate learning consent, useful sessions can update the guidance for later work. [Why I built it](docs/motivation.md).
+Shadowclone maintains the skills, instructions, and checks that help **Claude Code, Codex, Cursor, and Antigravity** follow your engineering preferences. It works with the coding agents you already use and keeps you in control of what it reads and changes.
 
-## Privacy comes first
-
-Every source has its own setting, defaults off, and appears by name before consent. The default setup asks one grouped question for detected session sources, Git remote names, and existing agent context. It asks separately about skills and background learning. `init --advanced` offers individual source choices. The paths that may be read are:
-
-| Source | Path |
-| --- | --- |
-| Claude Code sessions | `~/.claude/projects/` |
-| Claude prompt history | `~/.claude/history.jsonl` |
-| Codex sessions | `~/.codex/sessions/` or `$CODEX_HOME/sessions/` when set |
-| Cursor chats | `~/.cursor/chats/` |
-| Antigravity logs | `~/.gemini/antigravity-cli/brain/` |
-| Shell history | `~/.zsh_history`, `~/.bash_history` |
-| Repository guidance | root `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and direct `SKILL.md` files under `.claude/skills/` and `.agents/skills/` |
-| Agent context | `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.codex/AGENTS.override.md`, supported personal and repository skill roots, and `~/.claude/projects/<repo>/memory/` or `~/.codex/memories/`, only for consented evaluation |
-| Skill library | `~/.claude/skills/`, `~/.agents/skills/`, `~/.codex/skills/`, `~/.cursor/skills/`, `~/.gemini/config/skills/`, configured repository roots, and selected provider plugin caches |
-| Git metadata | repository Git remote names |
+## Get started
 
-Source detection checks whether a configured root has content. A directory check reads at most one entry to establish that fact and retains no name before consent. Agent transcripts can contain private code, credentials, internal hosts, and customer data. Shadowclone never copies raw transcripts into its store. Its SQLite index holds pointers and event kinds. Eligible excerpts pass through `resolveRedacted`, the single secret-redaction gate, before a model receives them. Tool results, file-read contents, thinking blocks, and data-access results are excluded from learning by category.
-
-Learning sends eligible redacted excerpts through your own authenticated agent CLI. Evaluation also gives that CLI access to a disposable repository snapshot and sends generated code to judges without redaction. Use only repositories you are authorized to send to that provider. A remote action from `shadowclone run` needs separate approval for that run. There is no Shadowclone service, API key, account, or telemetry. The profile is Markdown under `~/.shadowclone/profile/`; you can read, edit, or delete it. `shadowclone forget --all` removes Shadowclone's local state and recorded integrations, preserving unrelated content and stopping on conflicting edits. Your original transcripts remain where your agents wrote them. [Privacy design](docs/architecture/05-privacy.md).
-
-## Install
+Install the CLI:
 
 ```bash
 npm install -g @shadowclone/cli
-shadowclone init
 ```
 
-The commands below use the installed `shadowclone` binary. From this checkout, use `bun run cli` in its place.
-
-`init` shows the detected agents and source paths, then asks three questions, each defaulting to yes:
-
-1. Learn how you work from these sessions?
-2. Keep your skills in sync across the detected agents?
-3. Keep improving in the background as you work?
+| Step | Command | What happens | Time |
+| --- | --- | --- | ---: |
+| 1 | `shadowclone init` | Answer three questions about learning and skill maintenance | About 1 minute |
+| 2 | `shadowclone learn --deep` | Learn from enabled past sessions; repeat if more history remains | Up to 5 minutes per run |
+| 3 | `shadowclone wizard` | Choose skills in the browser and review the files before applying them | About 1 minute |
 
-Only detected transcript sources are enabled by the first answer. Setup then imports supported repository guidance if present, synchronizes consented skills, runs a first learning pass when background learning is enabled, and installs global native guidance for detected agents. The first pass selects recent unprocessed steering and limits model calls to 12 or 90 seconds; scanning local transcripts can take longer. Reaching a model budget does not block setup. Later sessions continue bounded learning when the agent marks a useful session. No extra `learn` command is required to finish setup.
+Setup takes about two to three minutes, excluding learning. Deep learning needs an installed and authenticated `claude`, `codex`, or `cursor-agent` CLI.
 
-Use `shadowclone init --advanced` for individual source choices and the seed guidance wizard. Run `shadowclone wizard` later to change seed preferences and starter skills. Run `shadowclone skills configure --global` or `--repo` to configure skill roots separately. Managed policy may limit any setting.
+**Skip learning.** Run `shadowclone wizard` by itself if you do not want Shadowclone to read sessions or call a model. It starts from an empty active environment and lets you choose a build locally.
 
-## How it works
+**For coding agents.** Install the CLI, run `shadowclone wizard --no-open`, and give the user the printed local URL. Keep the command running while they edit their build. `shadowclone init` asks consent questions and needs the user.
 
-```text
-enabled transcripts -> local index -> steering episodes -> redacted reconciliation
-                                                        -> editable profile
-profile + personal skills -> native agents and clones -> new transcripts
-```
-
-Plain `shadowclone learn` updates the local index and prints a structural report without model calls or profile writes. `shadowclone learn --deep` works through the oldest unprocessed episodes in bounded batches, proposes changes, and asks before applying them. `--deep --apply` accepts that local write without a prompt. Explicit reusable guidance can become active from one session; inferred behavior needs three independent sessions. The processed ledger lets later runs continue through older history. `shadowclone remember --repo "Use complete variable names."` records a direct preference immediately.
+## Evaluations
 
-The first setup pass starts at the newest unprocessed episodes so the next session can benefit quickly. Reconciliation batches run concurrently, then apply results in their original order. Completed checkpoints let a later run reuse finished model work. All model calls use `claude`, `codex`, or `cursor-agent` under your existing authentication.
+The preference study tested ordinary coding tasks on GPT-6 Sol, GPT-6 Luna, Sonnet 5.5, and Opus 5.5. Each agent ran with no personal help, with existing skills, with Shadowclone skills, and with Shadowclone skills plus deep learning.
 
-Repository imports preserve your edits and rejected rules. The compiler selects global guidance, the matching Git remote owner, and the exact repository. Without Git metadata consent, working directories stay isolated. It caps compiled guidance at 16 KiB and drops whole blocks when needed.
+| Share of preferences followed | GPT-6 Sol | GPT-6 Luna | Sonnet 5.5 | Opus 5.5 |
+| --- | ---: | ---: | ---: | ---: |
+| Agent alone | 72% | 73% | 55% | 57% |
+| With Shadowclone skills | 84% | 83% | 68% | 68% |
+| With Shadowclone skills and deep learning | 97% | 88% | 76% | 82% |
+| Improvement with skills and deep learning | **+25** | **+15** | **+22** | **+25** |
 
-Native installation adds a small pointer and lifecycle hooks while preserving other instructions. Claude Code's `SessionStart` hook injects the current scoped profile into the main agent. Its `SubagentStart` hook gives spawned subagents that same profile without creating another learning request. Codex, Cursor, and Antigravity use their supported native delivery paths. A useful main-agent session can request bounded learning at session end. `shadowclone install --subagent` and `--auto-delegate` remain optional Claude repository modes.
+Here is what changed in practice. Each cell compares the agent alone with Shadowclone skills and deep learning.
 
-Portable skills live in `~/.agents/skills` and sync to supported provider locations. A single edited copy becomes the source for the next sync; divergent edits are reported as conflicts. Existing user skills and plugin packages are preserved. Skill assessment reads only enabled roots, sends redacted `SKILL.md` content through the chosen agent CLI, and leaves technical or routing changes for review. [Skill maintenance](docs/skill-maintenance.md).
+| Preference | GPT-6 Sol | GPT-6 Luna | Sonnet 5.5 | Opus 5.5 |
+| --- | ---: | ---: | ---: | ---: |
+| Review reply preferences | 2 of 6 → 6 of 6 | 2 of 6 → 6 of 6 | 0 of 6 → 6 of 6 | 0 of 6 → 6 of 6 |
+| Failing test first | 0 of 3 → 3 of 3 | 0 of 3 → 2 of 3 | 0 of 3 → 0 of 3 | 0 of 3 → 2 of 3 |
+| Pull request checklist | 0 of 3 → 3 of 3 | 3 of 3 → 3 of 3 | 0 of 3 → 1 of 3 | 2 of 3 → 3 of 3 |
 
-## Check the result
+Skills with deep learning beat the agent alone on all four agents by 15 to 25 points. The gain is statistically clear on GPT-6 Sol and Opus 5.5, and directional on the other two. The participant's existing skills scored in the same range and slightly higher on GPT-6 Luna. [Read the tasks, intervals, and limitations](evals.md).
 
-`shadowclone doctor` reports installation and engine status. `shadowclone context` prints the compiled profile for the current scope. `shadowclone history` shows local revisions, and `shadowclone undo <revision-id>` restores one when no later edit conflicts.
+## Privacy comes first
 
-Transfer evaluation compares three matched setups: repository guidance only, that guidance plus the existing personal skill/context library, and both plus the Shadowclone profile. It freezes a source-backed coding-preference rubric before execution and saves three blinded votes per check. Correctness is graded separately. Missing grades are reported as ungraded, and a completed evaluation does not require Clone to win. [Evaluation design](docs/architecture/09-evaluation.md).
+**There is no Shadowclone collection service or telemetry.** Learning records, revisions, and original-library snapshots stay on your machine. Model work goes through the authenticated agent CLI you select and is subject to that provider's terms.
 
-```bash
-shadowclone eval --repo /path/to/repository --engine codex --model gpt-5.6-sol --reasoning-effort medium --tasks 3 --repeat 2
-```
+**You choose what it reads.** Every capture source is off by default and has its own consent setting. Reading sessions does not silently enable memory, repository metadata, or skill editing.
 
-`shadowclone run "fix the flaky test"` runs a headless clone in a local worktree and records a receipt. The invocation approves one worktree, branch, and local commit. Remote actions also need a matching repository policy ceiling and `--approve` for that run. No action approval carries to the next run. [Acting policy](docs/architecture/04-acting.md).
+| Operation | What the selected provider can receive |
+| --- | --- |
+| Learning and skill maintenance | Selected redacted instructions, steering, and supporting context |
+| Browser editor | Nothing merely from opening it; optional AI drafting sends reviewed form fields |
+| Delegated `run` | The authorized task worktree and guidance |
+| Evaluation | Synthetic prompts, the tested setup's guidance, and generated code |
 
-## Early evaluation results
+**Redaction is a boundary, not an anonymity guarantee.** Tool results, tool-returned file contents, thinking blocks, and data-access results are excluded from learning. Use only sources and repositories you are authorized to send to the selected provider.
 
-Across four small TypeScript tasks using GPT-5.6 Sol at medium reasoning effort, the recorded preference scores were:
+**Removal stays in your control.** Disable background learning with `shadowclone learning disable`, stop automatic skill edits with `shadowclone skills automatic off`, or remove recorded state with `shadowclone forget --all`. See [data handling](docs/data-handling.md) and [enterprise controls](docs/architecture/07-enterprise.md) for sources, storage, managed policy, and removal details.
 
-| Repository only (Bare) | Personal skills/context (Skills) | Skills/context + profile (Clone) |
-| ---: | ---: | ---: |
-| 55/68 (80.9%) | 59/68 (86.8%) | 62/68 (91.2%) |
+## Guides
 
-These are guideline checks passed, not correctness or productivity scores. The skills were existing user-written or user-guided instructions, potentially outdated and not tuned for this comparison. This was one implementation per arm per task, with known judging limitations. Read [the tasks, setup, results, and caveats](evals.md) before drawing broader conclusions.
+| Guide | Use it to |
+| --- | --- |
+| [Agent builds](docs/guides/agent-builds.md) | Choose, create, and equip skills |
+| [Learning](docs/guides/learning.md) | Run deep learning, background learning, or record a preference |
+| [Skill maintenance](docs/guides/skills.md) | Review updates, conflicts, history, and undo |
+| [Repository setup](docs/guides/repositories.md) | Share checks and skills with a repository |
+| [How it works](docs/guides/how-it-works.md) | Follow guidance from consented evidence to coding agents |
+| [Command reference](docs/guides/commands.md) | Find everyday and advanced commands |
 
-## Commands
+**Further reading:** [Documentation index](docs/README.md) · [Architecture](docs/architecture/README.md) · [Design history](docs/design/README.md) · [Migration](docs/migration.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
 
-| Command | Use |
-| --- | --- |
-| `shadowclone init [--advanced]` | Set consent and install detected integrations |
-| `shadowclone import`, `shadowclone wizard` | Refresh repository guidance or seed choices |
-| `shadowclone learn [--deep] [--dry-run] [--apply]` | Inspect history or reconcile guidance |
-| `shadowclone skills`, `shadowclone skills update` | List starter guidance or maintain consented skills |
-| `shadowclone skills pending`, `show`, `apply`, `reject` | Review skill proposals |
-| `shadowclone learning enable|disable|status` | Control session learning |
-| `shadowclone doctor`, `shadowclone context`, `shadowclone sync` | Inspect or refresh delivery |
-| `shadowclone install [--agent <agent>|all] [--global|--repo]` | Install native guidance manually |
-| `shadowclone uninstall [--global]` | Remove owned integrations |
-| `shadowclone remember`, `history`, `undo` | Manage direct rules and revisions |
-| `shadowclone eval`, `shadowclone run <task>` | Measure transfer or run a local clone |
-| `shadowclone forget --all` | Remove all recorded Shadowclone state |
-
-Contributors can run `bun install` and `bun run check`. See [the architecture](docs/architecture/README.md), [design records](docs/design/README.md), [contribution guide](CONTRIBUTING.md), and [security policy](SECURITY.md). Shadowclone is MIT licensed.
+Shadowclone is MIT licensed.

package/bin/shadowclone.mjs

@@ -17,10 +17,13 @@ function bundledBunPath() {
     const manifest = require(manifestPath);
     const relative =
       typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.bun;
+
     if (typeof relative !== "string") {
       return null;
     }
+
     const candidate = path.join(path.dirname(manifestPath), relative);
+
     return existsSync(candidate) ? candidate : null;
   } catch {
     return null;
@@ -45,8 +48,10 @@ if (runtime === null) {
 const result = spawnSync(runtime, [bundle, ...process.argv.slice(2)], {
   stdio: "inherit",
 });
+
 if (result.error) {
   console.error("shadowclone: could not start bun");
   process.exit(1);
 }
+
 process.exit(result.status ?? 1);

package/dist/_.._/web/client/index.html

@@ -0,0 +1,150 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="referrer" content="no-referrer" />
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; connect-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'none'; form-action 'none'"
+    />
+    <title>Your agent build · Shadowclone</title>
+    <link rel="icon" type="image/svg+xml" href="../../../web/shadowclone-mark-w6a76wqy.svg" />
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+  <link rel="stylesheet" crossorigin href="../../../web/index-174jt7gq.css"><script type="module" crossorigin src="../../../web/index-1ezbn24z.js"></script></head>
+  <body>
+    <div class="frame">
+      <header class="masthead">
+        <a class="brand" href="/" aria-label="Shadowclone agent builder">
+          <img class="brand-mark" src="../../../web/shadowclone-mark-w6a76wqy.svg" alt="" />
+          shadowclone
+        </a>
+        <span class="local-badge"><span></span> LOCAL WORKSPACE</span>
+      </header>
+
+      <main>
+        <section class="intro" aria-labelledby="page-title">
+          <p class="eyebrow">YOUR AGENT. YOUR INSTINCTS.</p>
+          <h1 id="page-title">Build the way you think.</h1>
+          <p class="subtitle">
+            Equip a way of working. Every skill shapes how your agent approaches
+            a task.
+          </p>
+        </section>
+
+        <div class="toolbar">
+          <label class="scope-field">
+            Build scope
+            <select id="scope">
+              <option value="global">Personal · everywhere</option>
+              <option value="private">Personal · this repository</option>
+              <option value="shared">Shared · this repository</option>
+            </select>
+          </label>
+          <label class="search-field">
+            <span class="visually-hidden">Find a skill</span>
+            <input id="search" type="search" placeholder="Find a skill…" />
+          </label>
+          <button id="new-skill" class="quiet-button">+ Create a skill</button>
+        </div>
+
+        <div class="scope-meta">
+          <p id="scope-note" class="scope-note"></p>
+          <details id="library-note" class="library-note" hidden>
+            <summary>Built-in library · add your own</summary>
+            <p>
+              Include your installed skills by choosing the folders Shadowclone
+              can read.
+            </p>
+            <code>shadowclone skills configure</code>
+          </details>
+        </div>
+        <div id="notice" role="status" class="notice" hidden></div>
+
+        <div class="workspace">
+          <section
+            id="constellation"
+            class="constellation"
+            aria-label="Skill tree"
+          >
+            <svg
+              id="starfield"
+              class="starfield"
+              viewBox="0 0 600 900"
+              preserveAspectRatio="none"
+              aria-hidden="true"
+            ></svg>
+            <svg
+              id="tree-connections"
+              class="tree-connections"
+              aria-hidden="true"
+            ></svg>
+            <div id="tree" class="tree"></div>
+            <div class="tree-root" aria-hidden="true">
+              <span id="tree-origin"
+                ><img src="../../../web/shadowclone-mark-w6a76wqy.svg" alt="" /></span>
+            </div>
+            <p class="tree-hint">Select a star to inspect its skill.</p>
+          </section>
+
+          <aside class="build-panel" aria-label="Your character build">
+            <section class="identity" aria-labelledby="identity-title">
+              <div>
+                <p class="eyebrow">YOUR BUILD</p>
+                <h2 id="identity-title">An open canvas</h2>
+                <p id="identity-description">
+                  Choose the instincts you want your agent to bring to work.
+                </p>
+              </div>
+              <div id="traits" class="traits"></div>
+              <button id="describe" class="quiet-button">
+                Describe my agent with my model
+              </button>
+              <div
+                id="model-description"
+                class="requirements"
+                aria-live="polite"
+              ></div>
+            </section>
+            <section
+              id="detail"
+              class="detail"
+              aria-label="Selected skill"
+            ></section>
+          </aside>
+        </div>
+
+        <section
+          id="requirements"
+          class="requirements"
+          hidden
+          aria-label="Repository requirements"
+        ></section>
+      </main>
+
+      <footer class="footer">
+        <div>
+          <strong id="equipped-count">0 skills equipped</strong>
+          <p>Your build is editable at any time.</p>
+        </div>
+        <div class="footer-actions">
+          <button id="undo" class="quiet-button" hidden>Undo last apply</button>
+          <button id="review" class="primary-button">
+            Review your build <span aria-hidden="true">↗</span>
+          </button>
+        </div>
+      </footer>
+    </div>
+  </body>
+</html>