{"id":48419259,"url":"https://github.com/squarewavesystems/squarebox","last_synced_at":"2026-07-08T14:00:38.697Z","repository":{"id":349081155,"uuid":"1200985419","full_name":"SquareWaveSystems/squarebox","owner":"SquareWaveSystems","description":"A curated set of modern CLI/TUI tools and AI coding assistants in a container. Batteries included.","archived":false,"fork":false,"pushed_at":"2026-07-07T03:39:33.000Z","size":1217,"stargazers_count":67,"open_issues_count":0,"forks_count":9,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-07T05:13:40.727Z","etag":null,"topics":["ai","ai-tools","claude-code","cli","codex","codex-cli","dev","docker","gemini","gemini-cli","opencode","tui"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SquareWaveSystems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T04:09:33.000Z","updated_at":"2026-07-07T03:37:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SquareWaveSystems/squarebox","commit_stats":null,"previous_names":["brettkinny/tui-devbox","brettkinny/squarebox","squarewavesystems/squarebox"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/SquareWaveSystems/squarebox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SquareWaveSystems%2Fsquarebox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SquareWaveSystems%2Fsquarebox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SquareWaveSystems%2Fsquarebox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SquareWaveSystems%2Fsquarebox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SquareWaveSystems","download_url":"https://codeload.github.com/SquareWaveSystems/squarebox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SquareWaveSystems%2Fsquarebox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35266857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-tools","claude-code","cli","codex","codex-cli","dev","docker","gemini","gemini-cli","opencode","tui"],"created_at":"2026-04-06T08:00:37.777Z","updated_at":"2026-07-08T14:00:38.683Z","avatar_url":"https://github.com/SquareWaveSystems.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🟧📦 squarebox\n\n**A curated set of modern CLI/TUI tools and AI coding assistants in a container. Batteries included.**\n\n*For developers who live in the terminal but need to work across\nmultiple platforms and devices.*\n\n**squarebox** packages a complete terminal-based development environment\ninto a single container (Docker; Podman experimental): modern CLI tools, AI coding\nassistants, language SDKs, and an opinionated set of shell aliases. Run the\nsame box anywhere (desktop, VPS, or Codespace) and SSH in from your laptop,\ntablet, or phone (please don't).\n\nThe goal is to make modern terminal tooling easy and accessible. One-line\ninstall, interactive first-run setup, sensible defaults (thanks [omarchy](https://omarchy.org)).\n\n![squarebox first-run setup](https://raw.githubusercontent.com/SquareWaveSystems/squarebox/demo/demo/squarebox-setup.gif)\n*(Actual setup may involve more staring at the screen.)*\n\nPrerequisites\n-------------\n\n- [Docker](https://docs.docker.com/get-docker/) or [Podman](https://podman.io/getting-started/installation) (experimental — see one-line install below if you don't have either)\n- [Git](https://git-scm.com/) - on Windows, install [Git for Windows](https://gitforwindows.org/)\n\nThe installer auto-detects which runtime is available. If both are installed, it\nasks which to use. Override with `SQUAREBOX_RUNTIME=docker` or\n`SQUAREBOX_RUNTIME=podman`.\n\n\u003e **Podman (Experimental):** Docker is the primary tested runtime; Podman may\n\u003e have rough edges around volume mounts, SSH agent forwarding, or rebuild\n\u003e flows — please file an issue if you hit one.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDon't have Docker or Podman? One-line install\u003c/strong\u003e\u003c/summary\u003e\n\n**macOS** (via [Homebrew](https://brew.sh)):\n\n    brew install --cask docker-desktop\n\n**Linux** (official convenience script - inspect it first at [get.docker.com](https://get.docker.com)):\n\n    curl -fsSL https://get.docker.com | sh \u0026\u0026 sudo usermod -aG docker $USER\n\nLog out and back in (or run `newgrp docker`) so your shell picks up the new group.\n\n**Windows** (via [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/), in PowerShell 7+):\n\n    winget install --id Docker.DockerDesktop -e\n\nOn macOS and Windows, start Docker Desktop once after install so the daemon is\nrunning before you continue.\n\n\u003c/details\u003e\n\nInstall\n-------\n\nThese commands install squarebox and drop you into the container (if possible).\nBy default they **pull a prebuilt image** from GHCR — no local Docker build, no\nbuild toolchain — then clone the repo into `~/squarebox` for the config files\nand the `sqrbx` helper commands. On first login, a setup script runs\nautomatically to configure git (pulling your name and email from the host's\nglobal git config if available), optionally sign in to GitHub CLI, your choice\nof AI coding assistant, and language SDKs.\n\n**Stable**\n\n    curl -fsSL https://github.com/SquareWaveSystems/squarebox/releases/latest/download/install.sh | bash\n\n**Edge**\n\n    curl -fsSL https://github.com/SquareWaveSystems/squarebox/releases/latest/download/install.sh | bash -s -- --edge\n\nStable pulls the prebuilt image for the latest tagged release (pre-release tags\nlike `-rc` are skipped). Edge builds from the latest commit on `main` — no image\nis published for unreleased commits, so edge always builds from source. To build\nthe released version from source instead of pulling, pass `--build`. The install\nscript itself is published as a release asset, so the URL is pinned to a tagged\nversion of the script — pushes to `main` won't break new installs until a\nrelease is cut.\n\nIf the install fails or you want to see the full build/pull and git output,\nre-run with `--verbose`.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAdvanced install options (flags \u0026amp; environment variables)\u003c/strong\u003e\u003c/summary\u003e\n\nFlags: `--build` (build from source instead of pulling), `--edge` (latest\n`main`), `--verbose`.\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `SQUAREBOX_DIR` | `~/squarebox` | Install location (repo + workspace). Point at durable storage on hosts where `$HOME` is volatile — e.g. Unraid `/mnt/user/appdata/squarebox`. |\n| `SQUAREBOX_WORKSPACE` | `$SQUAREBOX_DIR/workspace` | Host path mounted as `/workspace`. |\n| `SQUAREBOX_TAG` | matched release / `latest` | Image tag to pull (e.g. `v1.0.0-rc1` to test a pre-release). |\n| `SQUAREBOX_IMAGE` | `ghcr.io/squarewavesystems/squarebox` | Image repository to pull from. |\n| `SQUAREBOX_BUILD` | `0` | `1` is equivalent to `--build`. |\n| `PUID` / `PGID` | `1000` / `1000` | Host uid/gid that should own bind-mounted files. Unraid/NAS: `99` / `100`. |\n| `SQUAREBOX_RUNTIME` | auto | Force `docker` or `podman`. |\n| `SQUAREBOX_HOME_VOLUME` | `squarebox-home` | Name of the named volume backing `/home/dev`. |\n| `SQUAREBOX_EDGE` | `0` | `1` is equivalent to `--edge`. |\n\n**Non-interactive provisioning** — set any of these to a comma-separated list to\npre-select a toolset and install it without prompts (handy for servers and\nscripted installs). Values use the same keys as `sqrbx-setup`:\n\n| Variable | Selects |\n|----------|---------|\n| `SQUAREBOX_AI` | AI assistants (`claude,copilot,gemini,codex,opencode,pi,paseo`) |\n| `SQUAREBOX_SDKS` | language SDKs (`node,python,go,dotnet,rust`) |\n| `SQUAREBOX_EDITORS` | editors (`micro,edit,fresh,nvim`) |\n| `SQUAREBOX_TUIS` | TUI tools (`lazygit,gh-dash,yazi`) |\n| `SQUAREBOX_MULTIPLEXERS` | multiplexers (`tmux,zellij`) |\n| `SQUAREBOX_GIT_NAME` / `SQUAREBOX_GIT_EMAIL` | git identity (when no host gitconfig) |\n\nExample: `SQUAREBOX_AI=claude SQUAREBOX_SDKS=node,python curl -fsSL …/install.sh | bash`\n\n\u003c/details\u003e\n\n**Windows (PowerShell 7+)**\n\nWindows users can install directly from PowerShell - no Git Bash required.\nThis handles clone, build, container creation, and PowerShell aliases\n(`sqrbx`, `squarebox`, etc.) natively:\n\n    irm https://github.com/SquareWaveSystems/squarebox/releases/latest/download/install.ps1 | iex\n\nOnce installed, you can re-run or pass flags from the local copy:\n\n    .\\install.ps1              # re-install / update\n    .\\install.ps1 -Edge        # latest main instead of latest release\n    .\\install.ps1 -Verbose     # show full build output\n\n\u003e **Note:** `irm ... | iex` does not support flags - PowerShell interprets them\n\u003e as arguments to `Invoke-Expression`, not the script. Use the local\n\u003e `.\\install.ps1` form for `-Edge` or `-Verbose`.\n\nStart\n-----\n\n    squarebox        # or: sqrbx\n\nThese are shell functions wrapping `docker start -ai squarebox` (or\n`podman start -ai squarebox`), added automatically for Bash, Zsh, and\nPowerShell 7+.\n\nThe container is persistent: it suspends on exit and resumes on start, keeping\ninstalled packages, config, and shell history intact between sessions. Your\ncode lives on the host at `~/squarebox/workspace` (bind-mounted), and per-user\nstate — shell history, GitHub CLI auth, claude-code data, mise toolchains —\nlives in a named Docker volume (`squarebox-home`) that survives container\nrecreation. Image-managed config like `.bashrc` is bind-mounted from the repo\nso updates flow through to the running container.\n\nRun as a long-lived server (Unraid / NAS / VPS)\n-----------------------------------------------\n\nThe `curl | bash` installer is built around an interactive desktop shell. To run\nsquarebox as a persistent server container you attach into on demand — on\nUnraid, a NAS, or a VPS — use the prebuilt image directly with the bundled\n`docker-compose.yml`:\n\n    cp .env.example .env        # set PUID/PGID, the workspace path, and a tag\n    docker compose up -d\n    docker compose exec -u dev squarebox bash\n\nSet `PUID`/`PGID` in `.env` to match your host so files squarebox writes to the\nworkspace mount are owned correctly — on Unraid that's `99` / `100`. The `-u dev`\non `exec` is needed because the container starts as root (to apply PUID/PGID)\nthen drops to the `dev` user; `exec` bypasses that, so `-u dev` lands you where\nyou want to be.\n\nPer-user state (shell history, gh auth, mise toolchains, AI-assistant state)\nlives in the `squarebox-home` named volume and survives image updates; your code\nlives on the host at the workspace path. To update, pull a newer tag and\n`docker compose up -d`. The published image is multi-arch (amd64 + arm64), so it\nalso runs on ARM NAS/VPS hosts.\n\n\u003e **Unraid note:** the host's `/root` is tmpfs and wiped on reboot, so a raw\n\u003e `curl | bash` install there won't persist. Either use compose (above) with the\n\u003e workspace path under `/mnt/user/appdata`, or run the installer with\n\u003e `SQUAREBOX_DIR` and `SQUAREBOX_WORKSPACE` pointed at appdata.\n\nWhat's included\n---------------\n\n### CLI Tools\n\n| Name | Language | Description |\n|------|----------|-------------|\n| [bat](https://github.com/sharkdp/bat) | Rust | Cat clone with syntax highlighting |\n| [curl](https://github.com/curl/curl) | C | URL data transfer |\n| [delta](https://github.com/dandavison/delta) | Rust | Syntax-highlighting pager for git diffs |\n| [difftastic](https://github.com/Wilfred/difftastic) | Rust | Syntax-aware structural diff tool (`difft`) |\n| [eza](https://github.com/eza-community/eza) | Rust | Modern ls replacement |\n| [fd](https://github.com/sharkdp/fd) | Rust | Fast, user-friendly find alternative |\n| [fzf](https://github.com/junegunn/fzf) | Go | Fuzzy finder |\n| [gh](https://github.com/cli/cli) | Go | GitHub CLI |\n| [glow](https://github.com/charmbracelet/glow) | Go | Terminal markdown renderer |\n| [gum](https://github.com/charmbracelet/gum) | Go | Tool for shell scripts and dotfiles |\n| [jq](https://github.com/jqlang/jq) | C | JSON processor |\n| [just](https://github.com/casey/just) | Rust | Command runner / modern make alternative |\n| [nano](https://nano-editor.org) | C | Default text editor |\n| [ripgrep](https://github.com/BurntSushi/ripgrep) | Rust | Fast recursive grep |\n| [starship](https://github.com/starship/starship) | Rust | Cross-shell prompt |\n| [xh](https://github.com/ducaale/xh) | Rust | Friendly HTTP client |\n| [yq](https://github.com/mikefarah/yq) | Go | YAML/JSON/XML processor |\n| [zoxide](https://github.com/ajeetdsouza/zoxide) | Rust | Smarter cd command |\n\nWhat's optional\n----------------\n\nSelected during first-run setup. Choose any combination, all, or none.\nSelections are saved under `/workspace/.squarebox` (on the host workspace bind\nmount) and reused automatically on container rebuilds. They can also be\npre-selected non-interactively via the `SQUAREBOX_AI`/`SQUAREBOX_SDKS`/… env vars\n(see *Advanced install options* above).\n\n### AI Coding Assistants\n\n| Name | Language | Description |\n|------|----------|-------------|\n| [Claude Code](https://github.com/anthropics/claude-code) | TypeScript | AI coding assistant |\n| [GitHub Copilot CLI](https://github.com/githubnext/github-copilot-cli) | TypeScript | GitHub Copilot in the terminal * |\n| [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) | TypeScript | Google Gemini in the terminal * |\n| [OpenAI Codex CLI](https://github.com/openai/codex) | TypeScript | OpenAI Codex in the terminal * |\n| [opencode](https://github.com/anomalyco/opencode) | Go | AI coding TUI |\n| [Pi Coding Agent](https://github.com/earendil-works/pi) | TypeScript | Minimal terminal coding harness (Earendil) * |\n| [Paseo](https://paseo.sh) | TypeScript | Remote control for AI CLI agents * |\n\n\\* Requires Node.js (auto-installed if needed).\n\n### Text Editors\n\nNano is always available as the default editor.\n\n| Name | Language | Description |\n|------|----------|-------------|\n| [micro](https://github.com/micro-editor/micro) | Go | Modern, intuitive terminal editor |\n| [edit](https://github.com/microsoft/edit) | Rust | Terminal text editor (Microsoft) |\n| [fresh](https://github.com/sinelaw/fresh) | Rust | Modern terminal text editor |\n| [helix](https://github.com/helix-editor/helix) | Rust | Modal editor (Kakoune-inspired) - *coming soon* |\n| [nvim](https://github.com/neovim/neovim) | C/Lua | Neovim |\n\nSelecting **nvim** offers to install the [LazyVim](https://www.lazyvim.org/) starter config to `~/.config/nvim`, turning Neovim into a preconfigured IDE. Plugins sync on first launch and persist in the `squarebox-home` volume. A Nerd Font in your terminal is recommended for icons; the starter is skipped if `~/.config/nvim` already exists, so your own config is never overwritten.\n\n### TUI Tools\n\nInstalled during first-run setup. Choose any combination:\n\n| Name | Language | Description |\n|------|----------|-------------|\n| [lazygit](https://github.com/jesseduffield/lazygit) | Go | Git terminal UI |\n| [gh-dash](https://github.com/dlvhdr/gh-dash) | Go | GitHub dashboard for the terminal |\n| [yazi](https://github.com/sxyazi/yazi) | Rust | Terminal file manager |\n\n### Terminal Multiplexers\n\nInstalled during first-run setup. Choose either, both, or neither:\n\n| Name | Description |\n|------|-------------|\n| [tmux](https://github.com/tmux/tmux) | Classic terminal multiplexer |\n| [zellij](https://github.com/zellij-org/zellij) | Friendly terminal workspace |\n\n### Shell (Experimental)\n\nBy default, squarebox uses Bash. During first-run setup you can opt in to\n**Zsh** or **Fish** instead.\n\n**Zsh** installs:\n\n| Name | Description |\n|------|-------------|\n| [zsh](https://www.zsh.org) | Z shell (via apt) |\n| [Oh My Zsh](https://ohmyz.sh) | Community framework for managing zsh config |\n| [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions) | Fish-like history-based suggestions |\n| [zsh-syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting) | Inline command syntax highlighting |\n\nThe generated `~/.zshrc` mirrors the default bashrc — same aliases, starship\nprompt, zoxide, and AI/editor/SDK sourcing — layered on top of Oh My Zsh.\n\n**Fish** installs [fish](https://fishshell.com) (via apt), which ships with\nautosuggestions and syntax highlighting built in. The generated\n`~/.config/fish/config.fish` mirrors the default bashrc in fish-native syntax;\nAI/editor/TUI/SDK selections are translated from their bash files into\n`~/.config/fish/conf.d/squarebox-selections.fish` at setup time.\n\n\u003e **Experimental:** the marker file `~/.squarebox-use-zsh` (or\n\u003e `~/.squarebox-use-fish`) causes `~/.bashrc` to `exec` the chosen shell on\n\u003e every interactive login, so the next shell start picks up the new shell.\n\u003e Set `SQUAREBOX_NO_ZSH=1` or `SQUAREBOX_NO_FISH=1` to force bash for a single\n\u003e session, or re-run `sqrbx-setup shell` to switch back permanently. Tooling\n\u003e is primarily tested against bash, so a few edge cases may need polish —\n\u003e please file an issue if you hit one. SDK shims are wired into all three\n\u003e shells via `mise activate {bash,zsh,fish}`.\n\n### SDKs\n\nAll SDKs are managed by [mise](https://github.com/jdx/mise) — a single\npolyglot version manager. Selections are written to `~/.config/mise/config.toml`\nand `mise activate` wires up shims and PATH automatically across bash, zsh,\nand fish.\n\n| SDK   | mise tool |\n|-------|-----------|\n| Node.js | `node` |\n| Python  | `python` |\n| Go      | `go` |\n| .NET    | `dotnet` |\n| Rust    | `rust` |\n\n### Learning mode (beta)\n\nOptional. When enabled during first-run setup (or via `sqrbx-setup learn`),\nthe container ships an interactive guide to every tool in the toolkit —\nhistory, why-it-exists, and skill-level-adapted \"try it\" examples.\n\n    sqrbx-learn               # open the menu\n    sqrbx-learn rg            # jump straight to a tool's lesson\n    sqrbx-learn ask \"...\"     # one-shot toolkit question to your AI CLI\n    sqrbx-learn explain '...' # explain a command flag-by-flag\n    sqrbx-learn recap         # review the commands your agent has been running\n    sqrbx-learn --progress    # show what you've completed\n    sqrbx-learn --reset       # wipe progress AND skill level\n\nThe top menu entry, **Learn hands-on with your AI agent**, launches your\nconfigured AI CLI — Claude Code, OpenCode, Gemini CLI, or Codex CLI — in a\ncoaching mode for the session: instead of doing the work for you, it explains\neach step, hands you the exact command and the reason for the tool choice,\nand asks you to run it yourself. Say \"just do it\" at any point to let it take\nover. Claude Code gets the coaching persona via `--append-system-prompt`; the\nothers receive it as a session-opening instruction. Either way it's\nsession-scoped and never touches your workspace's own `CLAUDE.md`/`AGENTS.md`.\n(No AI CLI yet? Add one with `sqrbx-setup ai`.)\n\n`ask` and `explain` use the same AI CLI non-interactively: `ask` answers a\ntoolkit question with the exact command to run, and `explain` breaks down a\ncommand flag-by-flag (defaulting to the last one in your shell history) and\nsuggests the modern squarebox equivalent when you fed it a legacy tool. Both\nrun on your own agent auth and cost tokens, so they only fire on demand.\n\n`recap` reverses the direction — learn from what your agent does. After\n`sqrbx-learn recap --enable` registers a Claude Code `PostToolUse` hook, every\nsquarebox toolkit command the agent runs while working is logged to\n`/workspace/.squarebox/agent-tool-log`. `sqrbx-learn recap` then shows\nper-tool counts with real examples from your own tasks, and can hand the\nrecent log to your AI CLI for a debrief of what those commands actually did.\n`recap --disable` removes the hook.\n\nThe first launch asks for a skill level (beginner / intermediate / expert)\nto scale both the examples and the agent's coaching; you can change it later\nfrom the menu. Lessons render through `glow` when available so the markdown\nbodies display properly.\n\nGetting help\n------------\n\nRun `sqrbx-help` inside the container for a one-screen overview of the\n`sqrbx-*` commands plus the fzf (`Ctrl+R`/`Ctrl+T`/`Alt+C`/`**\u003cTab\u003e`) and\nzoxide (`z`/`zi`) keyboard shortcuts. The MOTD points to it on every shell\nstart.\n\nReconfiguring\n-------------\n\nRe-run the first-run wizard at any time from inside the container with\n`sqrbx-setup`. With no arguments it walks every section; pass one or more\nsection names to reconfigure just those: `git`, `github`, `ai`, `editors`,\n`tuis`, `multiplexers`, `sdks`, `shell`, `learn`. `sqrbx-setup --list` shows your\ncurrent selections and `sqrbx-setup --help` the usage.\n\nAliases\n-------\n\n| Alias | Command | Description |\n|-------|---------|-------------|\n| `ls` | `eza --icons` | Modern ls with icons |\n| `ll` | `eza -la --icons` | Long listing with icons |\n| `lsa` | `ls -a` (resolves to `eza --icons -a`) | List all including hidden files |\n| `lt` | `eza --tree --level=2 --long --icons --git` | Tree view with git status |\n| `lta` | `lt -a` | Tree view including hidden files |\n| `cat` | `bat --paging=never` | Syntax-highlighted cat |\n| `ff` | `fzf --preview 'bat ...'` | Fuzzy find with preview |\n| `eff` | `$EDITOR \"$(ff)\"` | Fuzzy find and edit |\n| `..` | `cd ..` | Go up one directory |\n| `...` | `cd ../..` | Go up two directories |\n| `....` | `cd ../../..` | Go up three directories |\n| `c` | first selected AI tool | Launch selected AI assistant |\n| `g` | `git` | Git shorthand |\n| `gcm` | `git commit -m` | Commit with message |\n| `gcam` | `git commit -a -m` | Stage all and commit |\n| `gcad` | `git commit -a --amend` | Stage all and amend |\n| `lg` | `lazygit` | Launch lazygit (if installed) |\n| `claude-yolo` | `claude --dangerously-skip-permissions` | Claude without prompts |\n| `opencode-yolo` | `opencode --dangerously-skip-permissions` | OpenCode without prompts |\n\n### Multiplexer Keybindings (Experimental)\n\nBoth tmux and zellij ship with Omarchy-inspired defaults and matching keybindings:\n\n| Feature | Tmux | Zellij |\n|---------|------|--------|\n| Config path | `~/.config/tmux/tmux.conf` | `~/.config/zellij/config.kdl` |\n| Prefix | `Ctrl+Space` | `Ctrl+Space` (Tmux mode) |\n| Pane navigation | `Ctrl+Alt+Arrow` | `Ctrl+Alt+Arrow` |\n| Pane resizing | `Ctrl+Alt+Shift+Arrow` | `Ctrl+Alt+Shift+Arrow` |\n| Tab/window select | `Alt+1-9` | `Alt+1-9` |\n| Tab/window cycle | `Alt+Left/Right` | `Alt+Left/Right` |\n| Split horizontal | `prefix h` | `prefix h` |\n| Split vertical | `prefix v` | `prefix v` |\n| Scrollback | 50,000 lines | 50,000 lines |\n| Copy mode | Vi keys | Vi-style scroll |\n| Theme | Blue accent, top bar | Blue accent, compact layout |\n\nUpdate\n------\n\n### Quick update (from inside the container)\n\n    sqrbx-update\n\nChecks all GitHub-released tools against latest versions and updates them\nin-place. No rebuild required. Your container state, SDKs, and config are\npreserved.\n\n    sqrbx-update              # show available updates (dry run)\n    sqrbx-update --apply      # download and install all updates\n    sqrbx-update lazygit      # update a single tool\n    sqrbx-update --list       # list all tools and current versions\n\n### Full rebuild (from the host)\n\n    sqrbx-rebuild\n\nPulls the latest changes, rebuilds the image, and replaces the container.\nYour code in ~/squarebox/workspace is safe since it lives on the host. Most\nin-container state (shell history, GitHub auth, SDK toolchains) survives\nbecause /home/dev is backed by the `squarebox-home` named Docker volume.\nManually installed apt packages are still lost, since the image is rebuilt.\n\n#### What survives a rebuild\n\n| Survives | Lost |\n|----------|------|\n| Code in ~/squarebox/workspace (host bind mount) | Manually installed apt packages |\n| /home/dev (squarebox-home named volume): shell history, GitHub CLI auth, claude-code data, mise toolchains | |\n| Starship, lazygit, .bashrc (bind-mounted from repo, picks up updates) | |\n| AI tool / editor / SDK selections (in /workspace/.squarebox) | |\n| SSH keys (on host, forwarded via agent) | |\n\nTo wipe per-user state and start fresh, remove the named volume:\n`docker volume rm squarebox-home`.\n\n\u003e **Tip:** Use `sqrbx-update` from inside the container to update tools without\n\u003e rebuilding. Only use `sqrbx-rebuild` when the base image itself needs to\n\u003e change (new apt packages, new base tools, Dockerfile changes).\n\nDisk usage\n----------\n\nThe base image (CLI tools only, no optional components) is **~370 MB** on disk.\n\nFirst-run selections add to that:\n\n| Component | Adds |\n|-----------|------|\n| Claude Code | ~300 MB |\n| GitHub Copilot CLI | ~50 MB |\n| Google Gemini CLI | ~50 MB |\n| OpenAI Codex CLI | ~50 MB |\n| OpenCode | ~30 MB |\n| Pi Coding Agent | ~50 MB |\n| lazygit / gh-dash / yazi | ~10 / ~10 / ~10 MB |\n| micro / edit | ~12 / ~7 MB |\n| fresh / nvim | ~10 / ~45 MB |\n| Node.js | ~90 MB |\n| Python | ~50 MB |\n| Go | ~500 MB |\n| .NET | ~800 MB |\n\nA typical setup (Claude Code + Node.js + one editor) lands around **~800 MB**.\nSizes are approximate and will vary as tools are updated.\n\nSecurity\n--------\n\nBase image tools are pinned to specific versions and verified against SHA256\nchecksums when the Docker image is built, so `docker build` is reproducible.\n\nOptional tools selected during first-run setup (editors, TUIs, OpenCode,\nzellij) install the latest upstream release at the time you run setup. The\ntrust model is the same as running each tool's installer yourself: HTTPS\ndownloads from the project's official GitHub release (or upstream server). You\nget new features without waiting for a squarebox release, at the cost of\nbuild-time pinning for that tier.\n\nSDKs (Node, Python, Go, .NET, Rust) are installed by [mise](https://github.com/jdx/mise),\nwhich is itself a Dockerfile-tier pinned binary. mise downloads each SDK\ntoolchain from its upstream over HTTPS using its own integrity checks. npm-based\nAI tools (Copilot CLI, Gemini CLI, Codex CLI, Pi) use npm's built-in integrity verification.\n\nFor the full trust model (what `install.sh` does on your machine, how each\nlayer is verified, and how to inspect the script before running it) see\n[SECURITY.md](SECURITY.md).\n\nDevcontainer / Codespaces\n-------------------------\n\nOpen this repo in VS Code with the\n[Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers),\nor launch it in [GitHub Codespaces](https://github.com/features/codespaces).\nThe included `.devcontainer/devcontainer.json` builds the full **squarebox** image\nautomatically and opens the cloned repo at `/workspaces/\u003crepo\u003e`.\n\nThe interactive first-run wizard can't run in devcontainer mode (no TTY at\ncreate time), so a default toolset — **Claude Code + Node.js** — is installed\nnon-interactively by `postCreateCommand`. Override the defaults with these\ncontainer environment variables (set to an empty string to opt out of a tier):\n\n| Variable | Default | Selects |\n|----------|---------|---------|\n| `SQUAREBOX_DC_AI` | `claude` | AI assistants (`claude,copilot,gemini,codex,opencode,pi`) |\n| `SQUAREBOX_DC_SDKS` | `node` | SDKs (`node,python,go,dotnet,rust`) |\n| `SQUAREBOX_DC_EDITORS` | _(none)_ | Editors (`micro,edit,fresh,nvim`) |\n| `SQUAREBOX_DC_TUIS` | _(none)_ | TUI tools (`lazygit,gh-dash,yazi`) |\n\nTo add or change tools after the fact, run `sqrbx-setup` from the integrated\nterminal.\n\nYou can also attach to a running codespace directly from your local terminal\nusing `gh codespace ssh`.\n\nUninstall\n---------\n\n    sqrbx-uninstall\n\nRemoves the container, image, and shell integration but **keeps**\n`~/squarebox` (including `workspace/`) and the `squarebox-home` named volume\n(shell history, gh auth, mise toolchains) so your code and per-user state are\nsafe by default. Pass `--purge` to also remove both:\n\n    sqrbx-uninstall --purge\n\nA second confirmation is required if `~/squarebox/workspace` is non-empty.\nPass `-y` (or `-Yes` on PowerShell) to skip all prompts for scripting.\nIdempotent: safe to re-run once uninstalled.\n\n**Windows (PowerShell 7+):**\n\n    sqrbx-uninstall                # keep ~/squarebox\n    sqrbx-uninstall -Purge         # also remove ~/squarebox\n    sqrbx-uninstall -Yes           # skip confirmations\n\n**Broken-state recovery** (e.g. shell functions are missing, or after partial\ninstall): run the script directly from the install directory:\n\n    ~/squarebox/uninstall.sh              # Linux / macOS / Git Bash\n    ~/squarebox/uninstall.ps1             # Windows PowerShell\n\nStart a new shell afterwards (or `exec bash` / `exec zsh`) so the `sqrbx` and\n`squarebox` functions are dropped from the current session.\n\nMake it your own\n-----------------\n\n**squarebox** is meant to be a starting point, not a finished product. Fork it,\nswap out tools, add your own dotfiles, change the theme - build the dev\nenvironment that fits the way you work. The Dockerfile is intentionally\nstraightforward and the tool registry (`scripts/lib/tools.yaml`) makes it easy\nto add or remove tools. Use it as a base, take what's useful, and make it yours.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquarewavesystems%2Fsquarebox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsquarewavesystems%2Fsquarebox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquarewavesystems%2Fsquarebox/lists"}