A self-contained, reproducible polyglot development environment for rapid prototyping and experimentation.

Skunkworks is a general-purpose project template that provides:

• Version-pinned toolchains - Go, Python, Node.js, Bun, and TypeScript with locked versions
• Isolated installation - Everything lives in ~/.skunkworks by default, no system contamination
• Cross-platform - Works on macOS and Linux (both x64 and ARM64)
• Reproducible builds - Exact same tool versions across machines and time
• Fast setup - Automated installation scripts for all dependencies

Perfect for prototypes, experiments, and projects that need a stable, self-contained development environment.

# Clone the repo (or use as template)
git clone <your-repo> skunkworks
cd skunkworks

# Set up the environment
source env.sh
bin/setup

# You're ready to go!
# The environment is now configured with all tools

Important: Always run source env.sh at the start of each session to configure your shell environment.

For convenience, use direnv to automatically source the environment when entering the directory:

# The .envrc file is already configured
direnv allow

• Formatting + Type Checking:
  • JavaScript/TypeScript: Prettier + TypeScript compiler
  • Python: Ruff (format + lint) + basedpyright
  • Shell: shfmt
• Package Managers: Bun, npm, uv (Python), go modules

Note: Formatters automatically run type checking - you don't need separate type check commands in normal workflow.

All versions are defined in versions.sh for easy updates.

# Format all code + run all type checkers
bin/format

# Format + type check specific languages
bin/format-js        # Prettier + TypeScript type checker
bin/format-python    # Ruff format + Ruff lint + basedpyright type checker
bin/format-shell     # shfmt (bash scripts)

Important: The format commands automatically run type checking. This is the standard workflow - you get formatting, linting, and type checking in one step.

# TypeScript only (without formatting)
bun run typecheck

# Python only (without formatting)
basedpyright

# Note: There's no standalone command for both - just use bin/format

Use these only if you want to check types without formatting. In practice, just use the format commands above.

bin/setup      # Full setup (all languages)
bin/install-python   # Just Python
bin/install-node     # Just Node.js and Bun
bin/install-go       # Just Go

skunkworks/
├── bin/                    # Utility scripts
│   ├── format*             # Code formatters
│   ├── install-*           # Language installers
│   └── setup               # Full environment setup
├── env.sh                  # Environment configuration (source this!)
├── versions.sh             # Pinned tool versions
├── package.json            # Node.js/Bun dependencies
├── requirements.txt        # Python dependencies
├── tsconfig.json           # TypeScript configuration
└── ~/.skunkworks/          # Installation directory
    ├── opt/                # Language toolchains
    │   ├── goroot/         # Go installation
    │   ├── go/             # GOPATH
    │   ├── venv/           # Python virtual environment
    │   ├── python/         # Python installations
    │   ├── node*/          # Node.js
    │   └── bun/            # Bun runtime
    └── 3rdparty/           # Third-party dependencies

1. Clone or fork this repository as your project base
2. Run setup: source env.sh && bin/setup
3. Add your code: Write Go, Python, TypeScript, or anything else
4. Format & check: Run bin/format frequently (formats code and runs type checkers)
5. Add dependencies:
   • Node: bun add <package> or edit package.json
   • Python: Add to requirements.txt and run bin/install-python
   • Go: Use go get (GOPATH is configured)

The typical development workflow:

# Start your session (or use direnv)
source env.sh

# Write some code...

# Format and type check everything
bin/format

# Or format specific languages as you work
bin/format-python    # Formats, lints, and type checks Python
bin/format-js        # Formats and type checks TypeScript/JS

All format commands automatically run the appropriate type checkers, so you get immediate feedback on type errors without running separate commands.

Edit bin/update-3rdparty-deps and add:

github_update <user> <repo> <commit-sha>

Dependencies are downloaded to ~/.skunkworks/3rdparty/<repo> at the exact commit.

Edit versions.sh to change versions:

export GO_VERSION=1.25.4
export PYTHON_VERSION=3.12.12
export NODE_VERSION=24.11.1
# ... etc

Then re-run the relevant installer:

source env.sh
bin/install-go       # Updates Go to new version
bin/install-python   # Updates Python
bin/install-node     # Updates Node/Bun

By default, everything installs to ~/.skunkworks. To change this:

export DEPLOY_PREFIX=/path/to/custom/location
source env.sh
bin/setup

• Virtual environment: ~/.skunkworks/opt/venv
• Package manager: uv (fast pip replacement)
• Formatter/linter: Ruff
• Type checker: basedpyright (community fork of pyright)
• Integrated workflow: bin/format-python runs formatting, linting, and type checking automatically

• Runtime: Bun (primary) and Node.js
• Package manager: Bun
• Module system: ESNext with bundler resolution
• Strict mode enabled
• Formatter: Prettier (semicolons, single quotes, trailing commas)
• Type checker: TypeScript compiler (tsc)
• Integrated workflow: bin/format-js runs Prettier formatting and TypeScript type checking automatically

• Module mode enabled
• GOPATH: ~/.skunkworks/opt/go
• Tools installed to $GOPATH/bin (automatically in PATH)

• Formatted with shfmt
• All scripts in bin/ are executable and added to PATH

When you source env.sh, these are configured:

PROJECT_ROOT          # Repository root directory
HOMEDIR_STORE         # ~/.skunkworks (or $DEPLOY_PREFIX/.skunkworks)
THIRD_PARTY_DIR       # $HOMEDIR_STORE/3rdparty
OPT_DIR               # $HOMEDIR_STORE/opt

GOROOT                # Go installation directory
GOPATH                # Go workspace

VIRTUAL_ENV           # Python venv
PYTHONPATH            # Includes $PROJECT_ROOT and venv site-packages

BUN_INSTALL           # Bun installation directory
PATH                  # Updated to include all tools

• Use direnv: Automatically sources env.sh when you cd into the directory
• Secrets management: Create a secrets.sh file for API keys and tokens (gitignored, auto-sourced)
• IDE integration: Point your IDE to the virtualenv at ~/.skunkworks/opt/venv
• Multiple projects: Each project can have its own skunkworks setup without conflicts

The term "skunkworks" refers to a small, loosely structured group working on advanced or secret projects. This repo embodies that spirit - a flexible, self-contained environment for rapid development and experimentation without dependencies on system installations or corporate infrastructure.

This is a template/starter repository. Use it however you want for your projects.