@shadowclone/cli 0.0.5 → 0.0.7

package/.claude-plugin/hooks/hooks.json

@@ -11,6 +11,16 @@
         ]
       }
     ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run \"${CLAUDE_PLUGIN_ROOT}/dist/shadowclone.js\" hook session-start"
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

package/README.md

@@ -1,196 +1,104 @@
 # shadowclone
 
-Memory and alignment compiler for AI coding agents.
+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 reads historical coding sessions already on your disk (Claude Code, Codex, Cursor), mines your steering habits without sending raw transcripts to any server, and compiles an editable profile into the agents you already use.
+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).
 
-Developers who install the profile see a measurable action delta against unprofiled runs on their held-out corpus: the agent stops asking for confirmations you never gave, runs the tests you run, and avoids the tools you refuse.
+## Privacy comes first
 
-Verify the delta directly on your own machine:
+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:
 
-```bash
-shadowclone eval --sessions 10
-```
-
-## Architectural scope: what shadowclone is and is not
-
-**Not an agent runtime.**
-Shadowclone does not provide an LLM chat loop, an autonomous worker daemon, or an IDE extension. It compiles behavioral profiles and subagents for the agent CLIs you already install, authenticate, and pay for.
-
-**A memory and alignment compiler.**
-Every turn where you interrupted an agent, refused a tool, corrected a proposal, or chose one implementation over another is an alignment signal. Shadowclone indexes those moments locally and distills them into plain markdown rules scoped by repository origin.
-
-## The pipeline
-
-```
-observe  ->  index  ->  signal  ->  distill  ->  profile  ->  dispatch / eval
-                          |                        |
-                     zero tokens          user's subscription
-```
-
-| Stage | Module | Function |
-| --- | --- | --- |
-| observe | `src/observe/` | Normalizes agent transcripts into one incremental event stream |
-| index | `src/index/` | Rebuildable SQLite cache of byte offsets and event kinds, never text |
-| signal | `src/signal/` | Detects interruptions, plan changes, and tool refusals in pure code |
-| distill | `src/distill/` | Distills high-signal moments into rules via your installed agent CLI |
-| profile | `src/profile/` | Plain markdown rules and subagents scoped to git origins |
-| dispatch | `src/dispatch/` | Executes unattended tasks on isolated worktrees with receipts |
-| eval | `src/eval/` | Replays historical prompts through baseline vs clone to score behavioral deltas |
-
-Model calls run through `claude`, `codex`, or `cursor-agent`. There is no shadowclone API key, no telemetry, and no hosted server.
+| 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 |
 
-## Quickstart
+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.
 
-Install the global CLI:
-
-```bash
-npm i -g @shadowclone/cli
-```
+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).
 
-Verify your environment and supported provider CLIs:
-
-```bash
-shadowclone doctor
-```
-
-Grant consent for desired transcript sources:
+## Install
 
 ```bash
+npm install -g @shadowclone/cli
 shadowclone init
 ```
 
-Every source is off until it is enabled here, and two of them read files that are not transcripts:
-
-- **`git-metadata`** reads the git remote origin of a working directory, so rules can be scoped to the organization they were learned from. Without it every directory is treated as its own isolated origin.
-- **`agent-context`** reads the user's own `CLAUDE.md` or `AGENTS.md`, their skill markdown, and their agent memory directory. It exists so a transfer evaluation can freeze the same setup for both arms, and it is read only by `shadowclone eval`. Contents pass through redaction before they are written into a snapshot.
-
-Index your historical sessions and build your profile:
-
-```bash
-shadowclone learn
-```
-
-To preview without writing files or databases:
-
-```bash
-shadowclone learn --dry-run
-```
-
-To enable deep distillation through your authenticated agent CLI:
+The commands below use the installed `shadowclone` binary. From this checkout, use `bun run cli` in its place.
 
-```bash
-shadowclone learn --deep
-```
+`init` shows the detected agents and source paths, then asks three questions, each defaulting to yes:
 
-Install the compiled profile into the current repository:
+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?
 
-```bash
-shadowclone install
-```
-
-This writes `.claude/agents/shadowclone.md` and excludes it from git tracking.
+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.
 
-## Transfer evaluation
+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.
 
-Shadowclone measures whether the profile changes behavior, against tasks the user actually asked for:
+## How it works
 
-```bash
-shadowclone eval --tasks 5 --engine codex
+```text
+enabled transcripts -> local index -> steering episodes -> redacted reconciliation
+                                                        -> editable profile
+profile + personal skills -> native agents and clones -> new transcripts
 ```
 
-The evaluator selects historical requests that name an identifiable starting commit, rebuilds each one as an isolated git snapshot at that commit, and runs the task twice:
-1. **Baseline run:** the agent with frozen instructions and no profile.
-2. **Clone run:** the same agent with the profile learned from sessions strictly earlier than the task.
+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.
 
-Arm order alternates between repetitions, and the profile is learned only from evidence that predates the task and shares no session with it.
+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.
 
-Each run is graded two ways. The repository's own `test` and `typecheck` scripts run inside a `sandbox-exec` or `bubblewrap` boundary with no network. A blind judge then grades the observed files and actions twice with the requirement order reversed, and any disagreement between the two passes is recorded as uncertain rather than resolved.
+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.
 
-The command previews how many agent invocations it may spend and asks before starting. Pass `--yes` to skip the prompt, or `--json` for machine-readable output.
+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.
 
-Receipts are written to `~/.shadowclone/eval/<evalId>/receipt.json` after every run, so `--eval-id <id>` resumes an interrupted evaluation against the same frozen tasks.
+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).
 
-## Unattended dispatch
+## Check the result
 
-Execute tasks in an isolated git worktree without touching your working tree:
+`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.
 
-```bash
-shadowclone run "fix the flaky test in src/auth.test.ts"
-```
-
-The default dispatch mode creates a local worktree and branch, runs verification checks, and commits locally without pushing.
-
-Remote actions (push, open PR) require both a repository ceiling in `~/.shadowclone/config.toml` and an explicit per-run approval flag:
+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).
 
 ```bash
-shadowclone run "prepare release notes" --approve push
+shadowclone eval --repo /path/to/repository --engine codex --model gpt-5.6-sol --reasoning-effort medium --tasks 3 --repeat 2
 ```
 
-## Ground-truth privacy
+`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).
 
-Agent transcripts contain private code, environment variables, internal hosts, and customer data. Shadowclone protects data through structural guarantees:
+## Early evaluation results
 
-**Pointers instead of text copies.**
-The SQLite index stores file offsets, timestamps, and event kinds. Raw transcripts are never duplicated to a secondary store.
+Across four small TypeScript tasks using GPT-5.6 Sol at medium reasoning effort, the recorded preference scores were:
 
-**Sliced secret redaction.**
-Distillation excerpts pass through a deterministic sliced replacer before reaching any model. Secrets keep identifying prefixes (such as `AKIA` or `sk_live_`) while stripping high-entropy characters, keeping code context intact without leaking credentials.
+| Repository only (Bare) | Personal skills/context (Skills) | Skills/context + profile (Clone) |
+| ---: | ---: | ---: |
+| 55/68 (80.9%) | 59/68 (86.8%) | 62/68 (91.2%) |
 
-**Shannon entropy layer.**
-Tokens of 24 characters or more that reach 4.5 bits of entropy per character are sliced under the `shannon-entropy` label, even when they match no known vendor pattern. Long identifiers, file paths, and UUIDs measure below that threshold and stay readable.
+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.
 
-**Third-party tool results are excluded.**
-Distillation inputs allowlist user prompts and developer steering corrections. Tool outputs from database queries, log dumps, and file reads are excluded by category rather than relying on regex filtering.
-
-**Single-command wipe.**
-Wipe the entire local index, profile, checkpoints, and receipts:
-
-```bash
-shadowclone forget --all
-```
-
-## Enterprise governance
-
-Security teams can enforce policy ceilings fleet-wide via root-owned managed configuration:
-- **macOS:** `/Library/Application Support/shadowclone/managed.json`
-- **Linux:** `/etc/shadowclone/managed.json`
-
-```json
-{
-  "enabled": true,
-  "allowedSources": ["claude-code"],
-  "allowedEngines": ["claude-code"],
-  "distillation": "local-only",
-  "originScope": "strict",
-  "blockedOrigins": ["github.com/acme/security-*"],
-  "maxActionTier": "draft"
-}
-```
-
-Managed policies act as an absolute ceiling. Users cannot enable unapproved sources or engines, and `enabled: false` enforces an immediate stop across the machine.
-
-## CLI commands
-
-```bash
-shadowclone init                                 # Configure source consent and capabilities
-shadowclone learn [--deep] [--dry-run]           # Index sessions and synthesize rules
-shadowclone doctor                               # Inspect active paths, engines, and policies
-shadowclone install                              # Install profile as .claude/agents/shadowclone.md
-shadowclone run <task> [--approve <action>]      # Dispatch headless clone in a worktree
-shadowclone eval [--sessions N] [--json]         # Measure behavioral deltas against baseline
-shadowclone mcp                                  # Start stdio Model Context Protocol server
-shadowclone forget --all                         # Remove ~/.shadowclone/ completely
-```
-
-## Contributing
-
-Review `CONTRIBUTING.md` and `SECURITY.md`. All contributions must pass:
-
-```bash
-bun run check
-```
+## Commands
 
-## License
+| 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 |
 
-MIT. See `LICENSE`.
+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.