janix

Janix creates isolated Docker + Nix dev environments per git branch. Each branch gets its own git clone, Docker container, and Nix-based environment — so you can work on multiple branches simultaneously without conflicts.

Each container mounts your Claude config, so Claude Code works inside environments out of the box.

How it works:

• init configures the project: detects package manager, collects .env files, template variables, init/teardown scripts, and optional Docker network
• create clones the repo for the branch, builds a Docker image from flake.nix, and starts a container with persistent cache volumes
• attach drops you into an interactive shell inside the container via nix develop
• Package manager and Nix caches are persisted across environment recreations via Docker volumes
• flake.nix changes are detected automatically and trigger an image rebuild offer

Usage

janix init               # Initialize janix in current repo
janix create [branch]    # Create dev environment for a branch
janix list               # List environments and their status
janix ps                 # List running containers
janix attach [branch]    # Attach to a running environment
janix stop [branch]      # Stop a container (preserves clone)
janix start [branch]     # Start a stopped container
janix rm [branch]        # Remove container and clone

Development

npm run check && npm run build

Release

Before 1.0, janix does not follow strict SemVer.

• Fixes bump patch
• Features bump minor
• Breaking changes also bump minor
• We will switch to normal SemVer rules when 1.0 is released

Use npm version to update package.json, create the release commit, and create the git tag:

npm version patch
npm version minor

Agent guidance

AGENTS.md and CLAUDE.md currently defer to this section for shared working policy.

• Before 1.0, we do not optimize for backward compatibility.
• Prefer clean breaking changes over compatibility layers, shims, aliases, dual code paths, or legacy fallbacks.
• Do not build legacy behavior or migration scaffolding unless explicitly requested.
• When changing APIs or behavior, implement the simplest forward-looking version.