git:20250815.f0f3f1e to git:20251125.dbaaaa3

- # CLAUDE.md

-

- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

-

- ## Common Development Commands

-

- ### Building and Testing

-

- ```bash

- # Enter development shell

- nix develop

-

- # Build a specific package

- nix build .#claude-code

- nix build .#opencode

-

- # Build all packages

- nix flake check

-

- # Run a tool without installing

- nix run .#claude-code -- --help

- nix run .#gemini-cli -- --help

-

- # Format code - always run before committing

- nix fmt

-

- # Regenerate README package documentation

- mdsh

-

- # Update packages - each package can be updated individually

- # using either its custom update script or nix-update

-

- # For packages with custom update scripts:

- ./packages/<package-name>/update.sh

-

- # For packages without custom scripts:

- nix-update --flake --version=branch <package-name>

- ```

-

- ### Package Development

-

- When adding a new AI tool package:

-

- 1. Create directory: `packages/<tool-name>/`

- 1. Add `package.nix` using existing packages as templates:

- - Node.js tools use `buildNpmPackage`

- - Rust tools use `rustPlatform.buildRustPackage`

- - Pre-built binaries use `stdenv.mkDerivation` with `fetchurl`

- 1. Add `default.nix` that imports the package

- 1. Create `update.sh` if the package needs custom update logic

- 1. **Important**: Use `git add` on new package files for Nix flakes to recognize them

- 1. The package will be automatically discovered by blueprint

-

- ### Testing Individual Packages

-

- ```bash

- # Build and verify package

- nix build .#<package-name>

-

- # Run package checks

- nix build .#checks.x86_64-linux.pkgs-<package-name>

- ```

-

- ## High-Level Architecture

-

- This repository uses the **blueprint** framework for flake organization, which automatically discovers and builds packages from the `packages/` directory.

-

- ### Core Components

-

- 1. **Package Structure**: Each AI tool in `packages/` follows a consistent pattern:

-

- - `package.nix`: Main package definition (usually `buildNpmPackage` for Node.js tools)

- - `default.nix`: Simple wrapper that imports package.nix

- - `update.sh`: Custom update script for packages with special requirements

- - `package-lock.json`: For Node.js packages requiring dependency locking

-

- 1. **Update System**: Package updates are handled by GitHub Actions:

-

- - Automatically discovers all packages with a `version` attribute

- - Uses custom `update.sh` scripts when available

- - Falls back to `nix-update` for standard packages

- - Creates individual PRs for each update

-

- 1. **Security Experiments**: The `claudebox` package demonstrates sandboxed AI execution:

-

- - Uses bubblewrap for containerization

- - Provides tmux-based monitoring interface

- - Restricts file system and network access

-

- 1. **Provider Abstraction**: `claude-code-router` allows switching between LLM backends:

-

- - Supports multiple AI providers (Claude, OpenAI, etc.)

- - Provides unified interface for different models

-

- 1. **Development Environment**: Minimal shell with formatter integration:

-

- - treefmt configuration includes nixfmt, deadnix, shellcheck, shfmt, mdformat, yamlfmt, taplo

- - All formatting rules defined in `packages/formatter/treefmt.nix`

-

- ### Platform Support

-

- The flake supports: x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin

-

- ### Key Design Principles

-

- - **Reproducibility**: All packages use exact version pinning and hash verification

- - **Modularity**: Each tool is independently packaged and versioned

- - **Automation**: Update scripts handle version bumps and hash recalculation

- - **Security**: Experimental sandboxing for AI tool execution

-

- ### Common Issues and Solutions

-

- 1. **Rust packages with git dependencies**: May fail during cargo vendoring if dependencies have workspace inheritance issues. Consider using pre-built binaries as a workaround.

-

- 1. **Binary packages**: When packaging pre-built binaries:

-

- - Use `dontUnpack = true` if the download is a single executable file

- - Use `autoPatchelfHook` on Linux to handle dynamic library dependencies

- - Common missing libraries: `gcc-unwrapped.lib` for libgcc_s.so.1

-

- 1. **Update scripts**: Follow shellcheck recommendations - declare and assign variables separately to avoid masking return values.

-