AGENTS.md@packages/clones git:20261013.1fb932eA

Immutable. This exact content never changes and is served at /api/v1/blob/bb71a653293c629a.

# @shadowclone/clones

Runs cloud sessions: Claude Code or Codex works for the owner, as the owner, on a host that the owner owns. Only the owner's `/shadowclone` comment starts a session. The CLI and the MCP server call it. [Design record 044](../../docs/design/044-cloud-sessions.md) explains the design.

<!-- package-facts:start -->

(generated by `bun run guides`; do not edit by hand)

- Package name: `@shadowclone/clones`
- Workspace dependencies: `@shadowclone/cloud`, `@shadowclone/core`
- External dependencies: `smol-toml`, `zod`
- Export subpaths: `.`

<!-- package-facts:end -->

## Owns

- `src/session/`: the session config schema, the providers and their secrets, and the host paths.
- `src/trigger/`: the events, the `/shadowclone` command, and the rules that accept a request (`resolveSessionRequest`).
- `src/state/`: the GitHub state: claim refs and the daily budget, the session head ref, and the status comment.
- `src/run/`: the run program inside the clone image (`runSession`), with the workspace, git hooks, engine, review stages, save, and finish steps.
- `src/serve/`: the local server on a spare machine: the poller, the Docker launcher, the queue, and the launchd or systemd service.
- `src/setup/`: host setup, the default branch ruleset, the secrets file, and the check.
- `image/Dockerfile`: the clone image that `release.yml` publishes to GHCR.

## Rules

- A session starts only in three cases:
  - a comment from the owner's numeric user ID whose first line is `/shadowclone`,
  - a CI run on the commit that the session pushed last,
  - an allowed reviewer bot on a session pull request.
- shadowclone never reads a model login or the GitHub token. The owner pastes them into the host's secret store. Docker gets the secrets file path only.
- GitHub holds the state. A claim ref stops a second run of one request, and the claim refs of a day are the budget.
- A session never pushes to the default branch. The pre-push hook refuses it, and setup adds a ruleset with no bypass.
- A review runs the toolchain only on a pull request that the owner wrote in this repository. Other reviews turn the network off.
- Setup refuses a ChatGPT plan login on a public repository.

## Tests

Run `bun test` in this folder, or `bun test packages/clones` from the root. `src/fixtures.ts` has a fake GitHub and a sample config. The hook tests use real `git` in a temporary folder. No test needs an account or Docker.

To try a branch in Docker, run `bun run stage`, then `npm pack` in `packages/cli/out/package` with `--pack-destination packages/clones/image`. Build with `--build-arg SHADOWCLONE_PACKAGE=/tmp/shadowclone-build/<file>.tgz`, and pass the tag to `session setup --image`.

Update this file in the same commit when you change the package purpose, public exports, dependencies, or a rule above.