Ciresk dev quickstart

Your local worktree is the source of truth. You and Claude Code edit files locally; the session gets every change within a second and runs it. Nothing you edit lives only in the cloud.

Install

The installer puts ciresk, ciresk-ci and ciresk-dev in ~/.ciresk/bin and checks the signature and checksum of each one. It needs minisign (scoop install minisign on Windows, brew install minisign on macOS, your package manager on Linux).

irm https://get.ciresk.com/ci.ps1 | iex           # Windows PowerShell

curl -fsSL https://get.ciresk.com/ci | sh         # macOS, Linux, WSL2

Open a new terminal and check that it answers:

ciresk dev --version

Sign in

ciresk ci auth login
ciresk dev doctor

ciresk dev reads the key ciresk ci auth login stored in the OS keychain, so one sign-in covers both. ciresk dev doctor checks .localhost resolution, core.autocrlf, the name resolution rule on Windows, this device's key, the session's file watch limits and whether your sign-in can read your organization's dev policy, and names the fix for each problem it finds.

Add a template

A session runs what your repository's .ciresk/dev.yaml declares. If the repository has none yet, translate the compose file or devcontainer you already have:

ciresk dev init                 # prints the template and what it could not translate
ciresk dev init --write         # merges it into .ciresk/dev.yaml

Commit .ciresk/dev.yaml so everyone who clones the repository gets the same session. templates.md is the reference for every field, including the parameters and presets a person picks at start.

Start a session

From the root of your worktree:

ciresk dev up
ciresk dev up --preset light            # a preset the template declares
ciresk dev up --param seed=none         # one parameter's value

ciresk dev up starts the session from the template, waits until its services are ready, prints their URLs and returns. Each service is at http://<label>.localhost:<port> on your machine. Run it again from the same worktree and you get the same session back.

Each worktree gets its own session. ciresk dev status shows the services, their health and the clients attached; ciresk dev down ends it. sessions.md covers the rest of a session's life: pausing, autostart, sharing and reset.

Coding agents

Register the MCP servers once for Claude Code, Codex and Cursor:

ciresk dev setup --agents           # prints the command or config for each client
ciresk dev setup --agents --repo    # or writes .mcp.json for everyone who clones the repository

With --repo, a service whose template declares Next.js diagnostics also gets ciresk-dev-next, Next.js's own tools for that service. The tools act on the session of the worktree the agent runs in; the browser and Next.js servers need that session running when the agent starts them. mcp.md lists every tool.

Checks, tests and builds still go to Ciresk CI (ciresk ci check, ciresk ci test -p <crate>); the session is for running and looking at the code, not for the gate.

Editors

ciresk dev code
ciresk dev code apps/web           # open one directory of the repository, not the root

ciresk dev code opens VS Code with Remote-SSH on the session, at the directory you are in (--editor picks Cursor or Windsurf, --jetbrains opens JetBrains Gateway). Before the first connection, set this in VS Code's settings, so the editor server is downloaded on your machine and copied over:

"remote.SSH.localServerDownload": "always"

ciresk dev ssh opens a plain shell in the session; ciresk dev ssh --read-only follows along without write access. editors.md covers every editor, SSH, port forwarding and your dotfiles.

Run commands

ciresk dev exec -- pnpm test
ciresk dev exec --cwd apps/api -- cargo check

exec runs in the session's shell container by default (--container picks another), in the directory you are in. Output streams back as it comes and the exit code is the command's. --timeout (default 10m, at most 60m) kills the command and everything it started at the deadline.

Search

ciresk dev search "fn handle_invoice"
ciresk dev search --regex "fn (create|update)_invoice"

Search runs over the session's copy of the workspace, so it is as fast on a large repository as on a small one.

Evidence

ciresk dev evidence --url /invoices

evidence captures a screenshot, the console and the failed requests of one page of the session as a bundle, with secrets redacted, and prints where it saved it. --full-page captures the whole page; --out writes the bundle to a directory of your choice.

Services and diagnostics

ciresk dev logs web
ciresk dev restart web
ciresk dev diagnostics
ciresk dev open

logs and restart take the name of a service in your template. A service the template starts on demand starts the first time something opens it. diagnostics returns compile and type errors as data.

Windows

• Run ciresk dev setup --resolver once, in a PowerShell started with Run as administrator. It adds a name resolution rule so http://<session>.localhost:<port> reaches the daemon from every program, not only from the browser. ciresk dev doctor tells you when it is missing.
• The daemon listens on two named pipes, \\.\pipe\ciresk-dev-<user> and \\.\pipe\ciresk-devd-<user>. Only your user can open them; remote clients are refused.
• Keep core.autocrlf off for the worktree (git config core.autocrlf false); doctor warns when it is on, since converted line endings show up as changes in the session.
• The device key lives in the Windows Credential Manager. Without one, ciresk dev keeps it in a file under your profile and refuses to use it when the file grants access to anyone but you, SYSTEM or Administrators; the error names the icacls command that fixes it.