Arashi

Arashi is a Git worktree manager for meta-repositories.

It keeps related repositories aligned while you work on a feature branch across a shared workspace.

Documentation

Installation

Option 1: Install with curl (official direct install)

Prerequisites:

• curl
• bash
• A SHA-256 tool (shasum, sha256sum, or openssl)

curl -fsSL https://arashi.haphazard.dev/install | bash

Install a specific release:

curl -fsSL https://arashi.haphazard.dev/install | ARASHI_VERSION=1.4.0 bash

Verify install:

arashi --version

By default, the installer places arashi in ~/.arashi/bin, adds that path to your shell config, and in interactive installs offers to enable shell integration for arashi switch --cd.

If curl installation fails, use npm installation below or the manual release instructions in docs/INSTALLATION.md.

Option 2: Install with npm

npm install -g arashi

Verify install:

arashi --version

If npm is unavailable or fails, use the curl installer command above or the manual release instructions in docs/INSTALLATION.md.

Manual install from GitHub Releases

If you prefer not to use npm, download a platform binary from GitHub Releases and place it on your PATH.

macOS (Apple Silicon):

curl -L https://github.com/corwinm/arashi/releases/latest/download/arashi-macos-arm64 -o arashi
chmod +x arashi
sudo mv arashi /usr/local/bin/arashi

Linux (x64):

curl -L https://github.com/corwinm/arashi/releases/latest/download/arashi-linux-x64 -o arashi
chmod +x arashi
sudo mv arashi /usr/local/bin/arashi

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/corwinm/arashi/releases/latest/download/arashi-windows-x64.exe" -OutFile "arashi.exe"
# Move arashi.exe to a folder on your PATH

You can also build from source for local development:

bun install
bun run build

Command Surface

Arashi currently provides these commands:

• arashi init
• arashi add <git-url>
• arashi clone [--all]
• arashi create <branch>
• arashi list
• arashi status
• arashi remove <branch|path>
• arashi switch [filter] [--repos|--all] [--cd|--no-cd] [--sesh] [--no-default-launch]
• arashi shell init <bash|zsh|fish>
• arashi shell install
• arashi pull
• arashi sync
• arashi setup [--only <repo>] [--verbose]

Quick Example

arashi init
arashi add git@github.com:your-org/frontend.git
arashi add git@github.com:your-org/backend.git
arashi create feature-auth-refresh
arashi create feature-auth-refresh --launch
arashi create feature-auth-refresh --no-launch
arashi shell install
arashi status
arashi switch feature-auth-refresh          # parent repo worktrees
arashi switch --repos feature-auth-refresh  # child repo worktrees in current workspace
arashi switch --all feature-auth-refresh    # all repos
arashi switch --repos docs                  # repo-name matching in child repos
arashi switch --cd feature-auth-refresh     # parent-shell cd when shell integration is active
arashi switch --no-default-launch           # bypass configured launch mode defaults once

Workflow Guides

Use the docs site workflow guides when you want setup guidance by outcome instead of by individual command.

• Hooks and configuration defaults: arashi.haphazard.dev/workflows/hooks-and-config
• Integrations for VSCode, tmux, and tmux plus sesh: arashi.haphazard.dev/workflows/integrations
• Agent-assisted and spec-driven change flow: arashi.haphazard.dev/workflows/agents-and-specs

Shell Integration

Use shell integration when you want arashi switch to change the current shell directory instead of only opening a new terminal or editor context.

The official curl installer can offer this automatically. If you skip it or use npm, install it for the active shell with:

arashi shell install

Or print wrapper code for manual setup:

arashi shell init bash
arashi shell init zsh
arashi shell init fish

Once installed, you can use arashi switch --cd <filter> for one-off parent-shell switching or set .arashi/config.json defaults.switch.mode to "cd" or "auto".

If shell integration is inactive, arashi switch --cd warns and skips launch fallback for that invocation.

For automated installs, set ARASHI_SHELL_INTEGRATION=yes to enable it without prompting or ARASHI_SHELL_INTEGRATION=no to skip it.

Hooks

Arashi can run lifecycle hooks during arashi create and arashi remove.

• Global hooks in .arashi/hooks/:
  • pre-create.sh
  • post-create.sh
  • pre-remove.sh
  • post-remove.sh
• Repository-specific hooks:
  • pre-create.<repo>.sh
  • post-create.<repo>.sh
• Scoped remove hooks:
  • repository scope: repos/<repo>/.arashi/hooks/pre-remove.sh and post-remove.sh
  • global shared: ~/.arashi/hooks/pre-remove.sh and post-remove.sh
  • global targeted: ~/.arashi/hooks/<repo>/pre-remove.sh and post-remove.sh

For arashi remove, hook execution order is: repository scope -> workspace-root scope -> global targeted scope -> global shared scope.

pre-remove.sh is useful for teardown before deletion (for example, stopping tmux sessions), and post-remove.sh can run final cleanup after remove operations complete.

See docs/hooks.md for hook behavior, environment variables, and examples.

Workflow Shortcuts

Use arashi list with fzf and optional keybinds to speed up daily navigation.

Jump to a worktree (cd)

# One-off jump
cd "$(arashi list | fzf)"

# Bash keybind (Ctrl+G)
bind '"\C-g":"cd \$(arashi list | fzf)\n"'

# Zsh keybind (Ctrl+G)
bindkey -s '^g' 'cd $(arashi list | fzf)\n'

Open or switch tmux sessions with sesh

# One-off session connect
sesh connect "$(arashi list | fzf)"

# Bash keybind (Ctrl+S)
bind '"\C-s":"sesh connect \$(arashi list | fzf)\n"'

# Zsh keybind (Ctrl+S)
bindkey -s '^s' 'sesh connect $(arashi list | fzf)\n'

You can also use arashi switch --sesh directly inside tmux to open the selected worktree in a new tmux window.

arashi switch also detects tmux, Kitty, Ghostty, WezTerm, and iTerm2 contexts and prefers terminal-native launch behavior when available.

Fast remove selection

# Select and remove a worktree quickly
arashi remove -f "$(arashi list | fzf)"

If you prefer the term delete, create a shell alias:

alias arashi-delete='arashi remove -f'

Configuration Schema

Arashi publishes a JSON Schema for .arashi/config.json so editors can validate and autocomplete your config.

• Stable URL: https://unpkg.com/arashi/schema/config.schema.json
• Version-pinned URL: https://unpkg.com/arashi@1.7.0/schema/config.schema.json

Example config header:

{
  "$schema": "https://unpkg.com/arashi/schema/config.schema.json",
  "version": "1.0.0",
  "reposDir": "./repos",
  "defaults": {
    "create": {
      "switch": true,
      "launch": true,
      "launchMode": "sesh"
    },
    "switch": {
      "mode": "auto",
      "launchMode": "sesh"
    }
  },
  "repos": {}
}

defaults.switch.mode accepts "launch", "cd", or "auto". "auto" prefers parent-shell switching only when shell integration is active.

Defaults precedence for create/switch behavior: explicit CLI flag > opt-out flag > config default > built-in default.

skills.sh Integration

Arashi also ships a dedicated skills.sh integration package for guided installation, workflow examples, and troubleshooting.

• Skill repository: repos/arashi-skills
• Canonical skill manifest: repos/arashi-skills/skills/arashi/SKILL.md
• Workflow catalog: repos/arashi-skills/skills/arashi/references/workflows.md
• Session shortcuts: repos/arashi-skills/skills/arashi/references/session-shortcuts.md

Documentation

• Installation details: docs/INSTALLATION.md
• Configuration details: docs/configuration.md
• Clone command details: docs/commands/clone.md
• Hook behavior: docs/hooks.md
• Workflow guides: https://arashi.haphazard.dev/workflows/
• Shell integration details: docs/commands/shell.md
• Setup command details: docs/commands/setup.md
• Switch command details: docs/commands/switch.md
• Remove command details: docs/commands/remove.md
• FZF integration: docs/FZF_COMPATIBILITY.md

Contributing

Use the canonical guide: CONTRIBUTING.md.

For specs and planning workflow, see the specs repository: github.com/corwinm/arashi-arashi.

License

MIT