Lifecycle

The lifecycle of a slice is: create a worktree, bind it to state, bring processes up, bring them down, optionally detach and rebind.

Binding

A worktree must be bound to a state directory before processes can start. The binding tells thinslice which database files, port assignments, and configuration to use.

slice use

slice use <state>

Bind the current worktree to a state directory. Run this from inside a worktree.

If the state is already bound to another worktree with running processes, those processes are stopped and the old worktree is unbound first — except processes marked depends_on_worktree = false, which keep running so a swap only restarts the code you're changing. This is how you swap code:

# feature-auth is running with dev-signed-in state
$ cd ../bugfix-503
$ slice use dev-signed-in       # stops feature-auth, binds dev-signed-in here
$ slice up                      # same database, same ports, different code

slice detach

slice detach

Stop processes and unbind the current worktree from its state. The state directory is left intact — its data is preserved. Another worktree can bind to it later.

Starting and stopping

slice up

slice up [profile]

Start the processes defined in your slice configuration. Each process inherits all variables from the [env] section of thinslice.toml. Processes read their configuration from these environment variables — they need no knowledge of the thinslice directory structure.

Without a profile, all processes start as background daemons. slice down sends them a kill signal.

With a profile name, thinslice uses the corresponding hooks.up.<profile> definition to arrange processes in tmux. See Hooks.

$ slice up                    # background everything
$ slice up dev                # arrange in tmux using hooks.up.dev

slice up will not work if the current worktree is not bound to a state. Run slice use <state> first.

slice down

slice down

Stop all running processes for the current slice. The worktree remains bound to its state — you can slice up again without re-binding.

If processes were started with a tmux profile, slice down kills the processes in those panes. The tmux window behavior (stay open or close) is configurable.

slice restart

slice restart [profile]

Stop and restart processes. Equivalent to slice down && slice up [profile]. Useful after changing configuration or pulling new code.

Inspection

slice status

slice status

Show the full picture: all worktrees, their bound state, running processes, and port allocations.

$ slice status

  WORKTREE              STATE             PORTS              STATUS
  main                  —                 —                  —
  local/feature-auth    dev-signed-in     pg:5440 web:8090   running
  tmp/fix-login         fix-login-state   pg:5441 web:8091   running
  pr/4521               —                 —                  —

slice ports

slice ports

Show port allocations for the current slice.

$ slice ports

  PROCESS    PORT
  postgres   5440
  redis      6390
  nats       4222
  api        3010
  web        8090

slice logs

slice logs [process]

Tail logs for all processes, or a specific process.

$ slice logs               # interleaved output from all processes
$ slice logs api           # just the API process
$ slice logs --follow      # follow mode (like tail -f)

slice config

slice config

Print the resolved thinslice.toml to stdout. Useful for debugging your template or checking what configuration a slice is actually using.

slice edit

slice edit

Open the thinslice.toml file in $EDITOR. The file lives in the state directory, not the worktree. This is useful for one-off tweaks without regenerating from the template.

Typical flows

Start fresh work

$ slice local feature-auth
$ cd local/feature-auth
$ slice state new dev --from template-clean
$ slice use dev
$ slice up dev
# work...
$ slice down

Quick agent task

$ slice tmp fix-bug --from current claude -p "fix the login redirect"
# agent works in a new tmux window, you keep working
# later:
$ cd tmp/fix-bug
$ git diff main
$ slice down
$ slice rm tmp/fix-bug

Swap code on existing state

# you've been working on feature-auth against dev-signed-in
# you want to try your bugfix branch against the same data
$ cd ../bugfix-503
$ slice use dev-signed-in     # shuts down feature-auth
$ slice up                    # same state, different code
# test the fix...
# swap back:
$ cd ../local/feature-auth
$ slice use dev-signed-in
$ slice up