# @shadowclone/live

Tracks the Claude Code and Codex sessions that the owner starts, after the owner turns on live sessions. Its hooks keep one state file for each session, and deliver the owner's messages to a session.

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

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

- Package name: `@shadowclone/live`
- Workspace dependencies: `@shadowclone/core`, `@shadowclone/redact`
- External dependencies: `zod`
- Export subpaths: `.`

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

## Owns

- `src/hook.ts`: `handleLiveHook` and `runLiveHook`, which write the session file for each hook event.
- `src/hookChange.ts`: the state change and the output for each hook event.
- `src/store.ts`: the session files, the inbox, and the `pending` marker.
- `src/sessions.ts`: `localLive`, the `list`, `get`, and `send` operations.
- `src/terminal.ts`: typing into a tmux pane or a cmux surface.
- `src/typing.ts`: `typeInbox`, which types the waiting messages and keeps them if the terminal refuses.
- `src/install.ts`: the hook entries in `~/.claude/settings.json` and `~/.codex/hooks.json`.
- `src/consent.ts`: `liveSessionsEnabled` and `switchLiveSessions`.

## Rules

- Do nothing unless `remote.live-sessions` is on in the effective config.
- Store only the repository, the branch, the folder name, the state, the times, the terminal, and the redacted last message. Never store a prompt, a tool input or output, or thinking.
- Bound the summary to 2 KB after `redactSecrets`.
- Deliver each queued message once. Never type into a session that waits for a permission answer.
- A Claude turn that ends with `StopFailure`, and an `idle_prompt` notification, make the session idle and type its waiting messages.
- Prefer a tmux pane over a cmux surface, because tmux can run inside cmux.
- Keep the owner's own hooks. Find shadowclone's hooks by the `live hook` text in their command.
- A hook never fails the agent. An error gives no output.

## Tests

Run `bun test` in this folder. The tests use a temporary home, a fake Git, and a fake terminal. They start no agent.

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