Skip to content
CodeBook

Work in a local checkout and run proof

Choose a local or cloud station, understand macOS and Windows terminal support, run a repository’s proof recipe, and control transcript capture.

Run here lets a Claude Code session manage work in a checkout using your Claude plan. Run in CodeBook sends the agent stations to the factory’s cloud workers under its policies. Choose cloud work when the terminal needs to close. Start a supervised cloud order

Set up the checkout

  1. Open the connected repository in Claude Code. In Factory settings → Your computer, check the path CodeBook uses for the repository. Confirm the checkout is accessible from the shell where Claude Code runs.
  2. Enter /factory status to see the current story and the repositories found on this computer. For a new local story, enter /factory run Payments "Fix the invoice export" --here. Press Enter when the prepared request looks right, then review the proposed work.
  3. Local code workers use Git worktrees and the station’s repository permissions. For a station that opens a draft GitHub PR, make sure Git and the authenticated GitHub CLI (gh) are available inside the same shell. Keep the owning Claude Code session running while a local station works.

On startup the plugin reads the Git origin and looks up factories visible to your account that use that repository. A matched checkout can supply manager instructions and prompt before a push, PR creation or merge. Use /factory outside to work outside that checkout’s factory in the current session; /factory inside restores it. To change your saved preference, use Factory settings → Your computer. Checkout behavior in the plugin

macOS and Windows Terminal

The CodeBook plugin has one Claude Code distribution. Windows Terminal can host either a native Windows shell or a WSL Linux shell. Their paths, tools and Claude Code profiles can differ. Install the plugin, open the checkout and run claude plugin list from the environment you intend to use. The native Windows acceptance run installed CodeBook 0.24.1 into a clean Claude Code profile and opened its command list with /factory help. The macOS acceptance run used the same plugin version to read factory state. Claude Code platform setup

Environment What to check for local proof and capture
macOS Terminal Proof attempts to use the macOS sandbox, sandbox-exec. Git and the tools in the repository’s recipe must be on the worker’s path.
Linux, including WSL Proof attempts to use a working bwrap (bubblewrap). Install the repository’s tools inside that Linux environment and use a checkout path it can read.
Native Windows in PowerShell or Command Prompt CLI plugin management uses the same claude plugin commands. The proof runner invokes POSIX tools and has sandbox implementations for macOS and Linux. For transcript capture, install Git for Windows and make its sh, head, tail and grep available in the same shell that launches Claude Code. For sandboxed local proof on Windows, use a WSL environment with bwrap.

Run a queued proof

In Factory settings → Proof runs, configure the repository recipe and queue a dry run with Try it. From the checkout’s Claude Code session, enter /factory prove or /factory prove 12 for a specific waiting proof. The plugin claims the run, executes the recipe and submits its measured evidence to CodeBook. Look for the commit, steps and sandbox result on the proof. If a step fails, the runner can replay it against the default branch in a separate worktree to distinguish a pre-existing failure. Uncommitted changes cannot establish that a particular commit passed.

The runner reports whether it could use an operating-system sandbox. If sandboxing is unavailable and the POSIX commands can run, the proof can proceed and is marked not boxed. A filtered list of allowed network hosts is not supported by this runner. A station can require a different proof location or the factory’s own runner. Proof runner details

Control saved conversations

When capture is enabled and permitted, a Claude Code session that calls CodeBook can upload its transcript from the beginning, including tool calls and their answers. Subagent sessions are stored as linked conversations. Enter /factory capture status to see whether this computer is saving eligible sessions. /factory capture off stops capture here; /factory capture on enables it. /factory capture backfill requests older eligible sessions in the current project. The organization’s settings and your permissions still apply. Configure retention in Factory settings → Your computer → Saved conversations. The plugin redacts recognized secrets locally, but free-form text can still contain sensitive information. Capture behavior and data handling

Claude chat and ChatGPT can use the cloud connector. Automatic local proof, transcript capture, checkout prompts, and local station subagents require the Claude Code plugin.