feat: Nix flake support for reproducible installation

[frankbria]

Summary

Add Nix flake support for Ralph, enabling Nix users to install and use Ralph with reproducible, declarative package management.

Background

PR #95 by @MSDimos proposed adding a flake.nix that provides:

• nix shell github:frankbria/ralph-claude-code for instant usage
• All dependencies bundled (bash, jq, git, nodejs, tmux, coreutils, gnugrep, gnused)
• Development shell environment

Scope

This enhancement requires architectural assessment:

1. Maintenance burden - Who maintains the flake when dependencies change?
2. Version synchronization - How to keep flake.nix in sync with install.sh
3. Testing - CI/CD integration for Nix builds
4. Documentation - Nix-specific installation instructions

Prior Art

• PR feat: add flake.nix #95 contains a working flake.nix implementation
• Contributors: @MSDimos

Priority

P4 - Nice-to-have enhancement

Labels

• enhancement
• platform: nix

[traycerai]

Plan

Implementation Plan: Nix Flake Support for Ralph

Observations

Ralph is a bash-based autonomous development tool with a well-defined dependency chain: Node.js (for @anthropic-ai/claude-code CLI), jq, git, bash 4.0+, coreutils, tmux (optional), gnugrep, and gnused. The project has a mature testing infrastructure (452 BATS tests with 100% pass rate requirement) and GitHub Actions CI/CD. The codebase is modular with 7 library scripts in file:lib/, 4 template files in file:templates/, and multiple entry-point scripts (file:ralph_loop.sh, file:ralph_monitor.sh, file:setup.sh, etc.). Current version is v0.11.2 with minimum Claude CLI version requirement of 2.0.76.

Approach

The implementation will create a file:flake.nix that provides three outputs: (1) a package for direct installation via nix shell github:frankbria/ralph-claude-code, (2) a development shell with all dependencies, and (3) NixOS module support for system-wide installation. The flake will bundle all bash scripts, library files, and templates into the Nix store, ensuring reproducibility. To minimize maintenance burden, the flake will reference the same dependency versions as file:install.sh, and CI/CD will be extended to test Nix builds. Documentation will be added to file:README.md with a dedicated Nix installation section.

Implementation Steps

1. Create Core Nix Flake Structure

Create file:flake.nix in the repository root with the following structure:

• Inputs: Define nixpkgs (nixos-unstable for latest packages) and flake-utils (for multi-system support)
• Outputs: Use flake-utils.lib.eachDefaultSystem to support Linux (x86_64-linux, aarch64-linux) and macOS (x86_64-darwin, aarch64-darwin)
• Package derivation: Use pkgs.stdenv.mkDerivation to create the ralph package
  • Set pname = "ralph-claude-code" and version = "0.11.2" (extract from README.md badge or create VERSION file)
  • Include src = ./. to bundle entire repository
  • Define buildInputs with all runtime dependencies: nodejs, jq, git, bash, coreutils, gnugrep, gnused, tmux
  • Create installPhase that:
    • Copies all .sh scripts to $out/bin/ (ralph_loop.sh, ralph_monitor.sh, setup.sh, ralph_import.sh, ralph_enable.sh, ralph_enable_ci.sh, migrate_to_ralph_folder.sh)
    • Copies file:lib/ directory to $out/lib/ralph/
    • Copies file:templates/ directory to $out/share/ralph/templates/
    • Creates wrapper scripts in $out/bin/ for each command (ralph, ralph-monitor, ralph-setup, ralph-import, ralph-enable, ralph-enable-ci, ralph-migrate)
    • Uses wrapProgram from pkgs.makeWrapper to ensure all dependencies are in PATH
  • Set meta attributes: description, homepage, license (MIT), maintainers, platforms

2. Create Wrapper Scripts for Nix Installation

Modify the installation logic to work with Nix store paths:

• Main wrapper script: Create a template that sets RALPH_HOME to $out/share/ralph instead of $HOME/.ralph
• Path adjustments: Update all scripts to use Nix store paths when installed via Nix:
  • Check for RALPH_NIX_INSTALL environment variable to detect Nix installation
  • If Nix install: use $out/lib/ralph/ for library scripts, $out/share/ralph/templates/ for templates
  • If traditional install: use $HOME/.ralph/lib/ and $HOME/.ralph/templates/
• Wrapper generation: In installPhase, create wrapper scripts that:
  • Set RALPH_HOME appropriately
  • Export RALPH_NIX_INSTALL=1
  • Call the actual script from $out/bin/
  • Use substituteInPlace to replace hardcoded paths in scripts

3. Add Development Shell

Add devShells.default output to file:flake.nix:

• Build inputs: Include all runtime dependencies plus development tools:
  • Runtime: nodejs, jq, git, bash, coreutils, gnugrep, gnused, tmux
  • Development: bats (testing framework), shellcheck (bash linting)
• Shell hook: Print welcome message with available commands and development workflow instructions
• Environment variables: Set RALPH_DEV=1 to indicate development mode

4. Extend CI/CD for Nix Testing

Update file:.github/workflows/test.yml to include Nix build verification:

• Add new job: nix-build that runs after the existing test job
• Install Nix: Use cachix/install-nix-action@v22 to install Nix in GitHub Actions
• Enable flakes: Configure Nix with experimental-features = nix-command flakes
• Build package: Run nix build .# to verify the package builds successfully
• Test installation: Run nix shell .# -c ralph --help to verify the package works
• Test development shell: Run nix develop .# -c bash -c "which ralph && which bats" to verify dev shell
• Cache Nix store: Use cachix/cachix-action to cache build artifacts for faster CI runs

5. Version Synchronization Strategy

Implement a mechanism to keep file:flake.nix in sync with file:install.sh:

• Create VERSION file: Add file:VERSION containing 0.11.2 at repository root
• Update flake.nix: Read version from file:VERSION using builtins.readFile ./VERSION
• Update install.sh: Add version check that reads from file:VERSION
• Update README.md: Reference file:VERSION for the version badge
• CI validation: Add a CI check that verifies version consistency across files:
  • Extract version from file:VERSION
  • Verify it matches the version in file:flake.nix
  • Verify it matches the badge in file:README.md

6. Documentation Updates

Update file:README.md with Nix-specific installation instructions:

• Add "Installation via Nix" section after the existing "Phase 1: Install Ralph" section:
  • Instant usage: nix shell github:frankbria/ralph-claude-code
  • Permanent installation: nix profile install github:frankbria/ralph-claude-code
  • Development environment: nix develop github:frankbria/ralph-claude-code
  • NixOS system-wide: Instructions for adding to configuration.nix (future enhancement)
• Add "Nix Flake" subsection to "System Requirements":
  • List Nix-specific benefits: reproducibility, declarative dependencies, no manual dependency installation
  • Note that Nix installation bundles all dependencies automatically
• Update CONTRIBUTING.md: Add section on testing with Nix:
  • How to build with nix build
  • How to enter dev shell with nix develop
  • How to test changes locally with Nix

7. Maintenance Documentation

Create file:docs/nix-maintenance.md with guidelines for maintaining the flake:

• When to update flake.nix:
  • Adding new bash scripts → Update installPhase to copy new scripts
  • Adding new dependencies → Update buildInputs in both package and devShell
  • Changing file structure → Update path references in wrapper scripts
  • Version bumps → Update file:VERSION file
• Dependency version policy:
  • Use nixpkgs-unstable for latest packages by default
  • Pin specific versions only if compatibility issues arise
  • Document any version constraints in comments
• Testing checklist:
  • Run nix flake check to validate flake structure
  • Run nix build to verify package builds
  • Run nix shell .# -c ralph --help to test installation
  • Run nix develop to verify dev shell
  • Test on both Linux and macOS if possible
• Troubleshooting common issues:
  • PATH issues → Check wrapProgram calls
  • Missing files → Verify installPhase copies all necessary files
  • Version mismatches → Check file:VERSION file consistency

8. Optional: NixOS Module

Create file:nix/module.nix for NixOS system-wide installation (future enhancement):

• Module options: Define services.ralph.enable, services.ralph.package, services.ralph.config
• System packages: Add ralph to environment.systemPackages when enabled
• User configuration: Allow users to specify .ralphrc settings via NixOS configuration
• Update flake.nix: Add nixosModules.default output pointing to file:nix/module.nix

Architecture Diagram

graph TD
    A[flake.nix] --> B[Package Output]
    A --> C[Dev Shell Output]
    A --> D[NixOS Module]
    
    B --> E[Install Phase]
    E --> F[Copy Scripts to $out/bin]
    E --> G[Copy lib/ to $out/lib/ralph]
    E --> H[Copy templates/ to $out/share/ralph]
    E --> I[Create Wrappers with wrapProgram]
    
    I --> J[ralph wrapper]
    I --> K[ralph-monitor wrapper]
    I --> L[ralph-setup wrapper]
    I --> M[ralph-import wrapper]
    I --> N[ralph-enable wrapper]
    
    C --> O[Runtime Dependencies]
    C --> P[Dev Dependencies]
    O --> Q[nodejs, jq, git, bash, coreutils, tmux]
    P --> R[bats, shellcheck]
    
    S[CI/CD] --> T[Existing Tests]
    S --> U[Nix Build Job]
    U --> V[nix build]
    U --> W[nix shell test]
    U --> X[nix develop test]

Loading

Maintenance Burden Mitigation

Concern	Solution
Dependency drift	Use file:VERSION file as single source of truth; CI validates consistency
Script changes	Document in file:docs/nix-maintenance.md which flake sections to update
Testing overhead	Automated Nix build in CI catches issues early; no manual testing required
Version bumps	Single file:VERSION file update propagates to all locations
Path changes	Wrapper scripts abstract Nix vs traditional installation differences

Success Criteria

• Users can run nix shell github:frankbria/ralph-claude-code and immediately use Ralph
• All 452 tests pass in Nix-built package
• CI/CD includes Nix build verification
• Documentation clearly explains Nix installation option
• file:VERSION file keeps all version references synchronized
• Maintenance documentation exists for future contributors

Import In IDE

🤖 Prompt for AI Agents

# Implementation Plan: Nix Flake Support for Ralph

## Observations

Ralph is a bash-based autonomous development tool with a well-defined dependency chain: Node.js (for @anthropic-ai/claude-code CLI), jq, git, bash 4.0+, coreutils, tmux (optional), gnugrep, and gnused. The project has a mature testing infrastructure (452 BATS tests with 100% pass rate requirement) and GitHub Actions CI/CD. The codebase is modular with 7 library scripts in `file:lib/`, 4 template files in `file:templates/`, and multiple entry-point scripts (`file:ralph_loop.sh`, `file:ralph_monitor.sh`, `file:setup.sh`, etc.). Current version is v0.11.2 with minimum Claude CLI version requirement of 2.0.76.

## Approach

The implementation will create a `file:flake.nix` that provides three outputs: (1) a package for direct installation via `nix shell github:frankbria/ralph-claude-code`, (2) a development shell with all dependencies, and (3) NixOS module support for system-wide installation. The flake will bundle all bash scripts, library files, and templates into the Nix store, ensuring reproducibility. To minimize maintenance burden, the flake will reference the same dependency versions as `file:install.sh`, and CI/CD will be extended to test Nix builds. Documentation will be added to `file:README.md` with a dedicated Nix installation section.

## Implementation Steps

### 1. Create Core Nix Flake Structure

Create `file:flake.nix` in the repository root with the following structure:

- **Inputs**: Define `nixpkgs` (nixos-unstable for latest packages) and `flake-utils` (for multi-system support)
- **Outputs**: Use `flake-utils.lib.eachDefaultSystem` to support Linux (x86_64-linux, aarch64-linux) and macOS (x86_64-darwin, aarch64-darwin)
- **Package derivation**: Use `pkgs.stdenv.mkDerivation` to create the ralph package
  - Set `pname = "ralph-claude-code"` and `version = "0.11.2"` (extract from README.md badge or create VERSION file)
  - Include `src = ./.` to bundle entire repository
  - Define `buildInputs` with all runtime dependencies: `nodejs`, `jq`, `git`, `bash`, `coreutils`, `gnugrep`, `gnused`, `tmux`
  - Create `installPhase` that:
    - Copies all `.sh` scripts to `$out/bin/` (ralph_loop.sh, ralph_monitor.sh, setup.sh, ralph_import.sh, ralph_enable.sh, ralph_enable_ci.sh, migrate_to_ralph_folder.sh)
    - Copies `file:lib/` directory to `$out/lib/ralph/`
    - Copies `file:templates/` directory to `$out/share/ralph/templates/`
    - Creates wrapper scripts in `$out/bin/` for each command (ralph, ralph-monitor, ralph-setup, ralph-import, ralph-enable, ralph-enable-ci, ralph-migrate)
    - Uses `wrapProgram` from `pkgs.makeWrapper` to ensure all dependencies are in PATH
  - Set `meta` attributes: description, homepage, license (MIT), maintainers, platforms

### 2. Create Wrapper Scripts for Nix Installation

Modify the installation logic to work with Nix store paths:

- **Main wrapper script**: Create a template that sets `RALPH_HOME` to `$out/share/ralph` instead of `$HOME/.ralph`
- **Path adjustments**: Update all scripts to use Nix store paths when installed via Nix:
  - Check for `RALPH_NIX_INSTALL` environment variable to detect Nix installation
  - If Nix install: use `$out/lib/ralph/` for library scripts, `$out/share/ralph/templates/` for templates
  - If traditional install: use `$HOME/.ralph/lib/` and `$HOME/.ralph/templates/`
- **Wrapper generation**: In `installPhase`, create wrapper scripts that:
  - Set `RALPH_HOME` appropriately
  - Export `RALPH_NIX_INSTALL=1`
  - Call the actual script from `$out/bin/`
  - Use `substituteInPlace` to replace hardcoded paths in scripts

### 3. Add Development Shell

Add `devShells.default` output to `file:flake.nix`:

- **Build inputs**: Include all runtime dependencies plus development tools:
  - Runtime: `nodejs`, `jq`, `git`, `bash`, `coreutils`, `gnugrep`, `gnused`, `tmux`
  - Development: `bats` (testing framework), `shellcheck` (bash linting)
- **Shell hook**: Print welcome message with available commands and development workflow instructions
- **Environment variables**: Set `RALPH_DEV=1` to indicate development mode

### 4. Extend CI/CD for Nix Testing

Update `file:.github/workflows/test.yml` to include Nix build verification:

- **Add new job**: `nix-build` that runs after the existing `test` job
- **Install Nix**: Use `cachix/install-nix-action@v22` to install Nix in GitHub Actions
- **Enable flakes**: Configure Nix with `experimental-features = nix-command flakes`
- **Build package**: Run `nix build .#` to verify the package builds successfully
- **Test installation**: Run `nix shell .# -c ralph --help` to verify the package works
- **Test development shell**: Run `nix develop .# -c bash -c "which ralph && which bats"` to verify dev shell
- **Cache Nix store**: Use `cachix/cachix-action` to cache build artifacts for faster CI runs

### 5. Version Synchronization Strategy

Implement a mechanism to keep `file:flake.nix` in sync with `file:install.sh`:

- **Create VERSION file**: Add `file:VERSION` containing `0.11.2` at repository root
- **Update flake.nix**: Read version from `file:VERSION` using `builtins.readFile ./VERSION`
- **Update install.sh**: Add version check that reads from `file:VERSION`
- **Update README.md**: Reference `file:VERSION` for the version badge
- **CI validation**: Add a CI check that verifies version consistency across files:
  - Extract version from `file:VERSION`
  - Verify it matches the version in `file:flake.nix`
  - Verify it matches the badge in `file:README.md`

### 6. Documentation Updates

Update `file:README.md` with Nix-specific installation instructions:

- **Add "Installation via Nix" section** after the existing "Phase 1: Install Ralph" section:
  - **Instant usage**: `nix shell github:frankbria/ralph-claude-code`
  - **Permanent installation**: `nix profile install github:frankbria/ralph-claude-code`
  - **Development environment**: `nix develop github:frankbria/ralph-claude-code`
  - **NixOS system-wide**: Instructions for adding to `configuration.nix` (future enhancement)
- **Add "Nix Flake" subsection** to "System Requirements":
  - List Nix-specific benefits: reproducibility, declarative dependencies, no manual dependency installation
  - Note that Nix installation bundles all dependencies automatically
- **Update CONTRIBUTING.md**: Add section on testing with Nix:
  - How to build with `nix build`
  - How to enter dev shell with `nix develop`
  - How to test changes locally with Nix

### 7. Maintenance Documentation

Create `file:docs/nix-maintenance.md` with guidelines for maintaining the flake:

- **When to update flake.nix**:
  - Adding new bash scripts → Update `installPhase` to copy new scripts
  - Adding new dependencies → Update `buildInputs` in both package and devShell
  - Changing file structure → Update path references in wrapper scripts
  - Version bumps → Update `file:VERSION` file
- **Dependency version policy**:
  - Use nixpkgs-unstable for latest packages by default
  - Pin specific versions only if compatibility issues arise
  - Document any version constraints in comments
- **Testing checklist**:
  - Run `nix flake check` to validate flake structure
  - Run `nix build` to verify package builds
  - Run `nix shell .# -c ralph --help` to test installation
  - Run `nix develop` to verify dev shell
  - Test on both Linux and macOS if possible
- **Troubleshooting common issues**:
  - PATH issues → Check `wrapProgram` calls
  - Missing files → Verify `installPhase` copies all necessary files
  - Version mismatches → Check `file:VERSION` file consistency

### 8. Optional: NixOS Module

Create `file:nix/module.nix` for NixOS system-wide installation (future enhancement):

- **Module options**: Define `services.ralph.enable`, `services.ralph.package`, `services.ralph.config`
- **System packages**: Add ralph to `environment.systemPackages` when enabled
- **User configuration**: Allow users to specify `.ralphrc` settings via NixOS configuration
- **Update flake.nix**: Add `nixosModules.default` output pointing to `file:nix/module.nix`

## Architecture Diagram

```mermaid
graph TD
    A[flake.nix] --> B[Package Output]
    A --> C[Dev Shell Output]
    A --> D[NixOS Module]
    
    B --> E[Install Phase]
    E --> F[Copy Scripts to $out/bin]
    E --> G[Copy lib/ to $out/lib/ralph]
    E --> H[Copy templates/ to $out/share/ralph]
    E --> I[Create Wrappers with wrapProgram]
    
    I --> J[ralph wrapper]
    I --> K[ralph-monitor wrapper]
    I --> L[ralph-setup wrapper]
    I --> M[ralph-import wrapper]
    I --> N[ralph-enable wrapper]
    
    C --> O[Runtime Dependencies]
    C --> P[Dev Dependencies]
    O --> Q[nodejs, jq, git, bash, coreutils, tmux]
    P --> R[bats, shellcheck]
    
    S[CI/CD] --> T[Existing Tests]
    S --> U[Nix Build Job]
    U --> V[nix build]
    U --> W[nix shell test]
    U --> X[nix develop test]
```

## Maintenance Burden Mitigation

| Concern | Solution |
|---------|----------|
| **Dependency drift** | Use `file:VERSION` file as single source of truth; CI validates consistency |
| **Script changes** | Document in `file:docs/nix-maintenance.md` which flake sections to update |
| **Testing overhead** | Automated Nix build in CI catches issues early; no manual testing required |
| **Version bumps** | Single `file:VERSION` file update propagates to all locations |
| **Path changes** | Wrapper scripts abstract Nix vs traditional installation differences |

## Success Criteria

- Users can run `nix shell github:frankbria/ralph-claude-code` and immediately use Ralph
- All 452 tests pass in Nix-built package
- CI/CD includes Nix build verification
- Documentation clearly explains Nix installation option
- `file:VERSION` file keeps all version references synchronized
- Maintenance documentation exists for future contributors

---

Execution Information

Branch: main
Commit: 48ba86a

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#45 - feat: add dedicated uninstall.sh script [merged]
#148 - fix: update ralph_import.sh [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!