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.

For contributors working on Arashi itself, the project planning workflow in the arashi-arashi meta-repo now uses OpenSpec. Older SpecKit-oriented references in legacy planning artifacts are historical context only.

• 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