# Arashi Full Documentation Export Generated from public Arashi docs pages. Canonical site: https://arashi.haphazard.dev Use this as broad agent context. For a shorter curated entrypoint, fetch `/llms.txt`. --- # Arashi Source: https://arashi.haphazard.dev/ Description: Arashi manages aligned worktrees across multiple repositories within a shared meta-repository. It streamlines creating, switching, and managing changes across your whole stack. import { TabItem, Tabs } from "@astrojs/starlight/components";

嵐 (Arashi) - The eye of the storm for your development workflow

Arashi manages aligned worktrees across multiple repositories within a shared meta-repository. It streamlines creating, switching, and managing changes across your whole stack. ```bash curl -fsSL https://arashi.haphazard.dev/install | bash ```

View install script

 ```powershell powershell -c "irm https://arashi.haphazard.dev/install.ps1 | iex" ```

View install.ps1

 ```bash npm install -g arashi arashi install ``` ```bash pnpm add -g arashi arashi install ``` ```bash bun add -g arashi arashi install ``` ```bash vp i -g arashi@latest arashi install ``` ## Choose Your Path - New to Arashi? Open [Getting Started](/getting-started/). - Need hooks or command defaults? Open [Hooks](/workflows/hooks/) or [Config](/workflows/config/). - Using VS Code? Open [VS Code](/workflows/vscode/). - Using tmux or `sesh`? Open [tmux and sesh](/workflows/tmux-and-sesh/). - Working with agents in a meta-repo? Open [Agents](/workflows/agents-and-specs/). - Looking for command behavior? Open [Commands](/commands/). - Contributing to Arashi? Open [Contributing](/contributing/). By default, `arashi create` places managed worktrees under `.arashi/worktrees`. You can also set default create/switch behavior in `.arashi/config.json` with `defaults.create` and `defaults.switch`, then choose workflow guides for hooks, editor or terminal setup, and agent-assisted change planning. --- # Getting Started Source: https://arashi.haphazard.dev/getting-started/ Description: Install Arashi, run core commands, and navigate to contributor guidance. Use this section when you are new to Arashi and need a quick setup and first workflow. ## Install Choose the install method for your platform and environment. ### Prerequisites - `git` available in your shell - `bash` and `curl` for the macOS/Linux installer path - Windows PowerShell for the Windows installer path - `node` and `npm` for the npm path ### Method 1: macOS/Linux installer ```bash curl -fsSL https://arashi.haphazard.dev/install | bash ``` Pin a specific version when needed: ```bash curl -fsSL https://arashi.haphazard.dev/install | ARASHI_VERSION=1.16.0 bash ``` Verify install: ```bash arashi --version ``` The installer defaults to `~/.arashi/bin`, updates your shell profile so `arashi` is available on `PATH` in new shells, and in interactive installs can offer shell integration for `arashi switch --cd`. It also runs a quick `arashi --version` smoke test before declaring success. For unattended installs, set `ARASHI_SHELL_INTEGRATION=yes` to enable that automatically or `ARASHI_SHELL_INTEGRATION=no` to skip it. ### Method 2: Windows PowerShell installer ```powershell powershell -c "irm https://arashi.haphazard.dev/install.ps1 | iex" ``` Inspect the script before running it: ```powershell irm https://arashi.haphazard.dev/install.ps1 ``` Pin a specific version when invoking a downloaded script: ```powershell .\install.ps1 -Version 1.16.0 ``` By default, the Windows installer places `arashi.bin.exe`, `arashi.ps1`, and `arashi.bat` in `%USERPROFILE%\.arashi\bin`, verifies them against `arashi-checksums.txt`, adds the install directory to the persistent user PATH, and tells you to open a new terminal. Use `-InstallDir` or `ARASHI_INSTALL_DIR` for a custom user-writable directory, and use `-NoModifyPath` or `ARASHI_NO_MODIFY_PATH=1` if you want to update PATH yourself. ### Method 3: npm global install ```bash npm install -g arashi ``` Arashi downloads the matching platform binary on first use. To preinstall it explicitly: ```bash arashi install ``` Verify install: ```bash arashi --version ``` ### Manual Windows fallback If you do not want to pipe a remote script into PowerShell, download these assets from the same [GitHub release](https://github.com/corwinm/arashi/releases/latest): - `arashi-windows-x64.exe` - `arashi.ps1` - `arashi.bat` - `arashi-checksums.txt` Verify each asset with `Get-FileHash -Algorithm SHA256`, rename `arashi-windows-x64.exe` to `arashi.bin.exe`, put all files in one directory on PATH, open a new terminal, and run `arashi --version`. ### Troubleshooting and fallback - `command not found`: install missing prerequisite (`curl`, `bash`, `npm`, `node`, or PowerShell) and rerun. - Permission errors writing to global paths: rerun the direct installer with a user-writable install directory or use a user-level npm prefix. - Network/download failures: retry once; for npm installs you can rerun `arashi install`, then switch to another install method if needed. - Checksum mismatch on direct installer paths: stop and use npm/manual fallback, then report the failure. - If `arashi --version` exits immediately or returns code `137`, rerun the direct installer with `ARASHI_VERSION=` or `-Version ` to pin a known-good release, or use npm/manual install while reporting the bad release artifact. - PATH changes may require a new terminal on Windows and POSIX shells. - If your environment blocks local `.ps1` scripts, inspect `install.ps1` first, then add `-ExecutionPolicy Bypass` to the `powershell` invocation for this one process or use the manual Windows fallback. ## First Workflow Start with the path that matches how you are adopting Arashi. ### 1. Create a new meta-repo Use this flow when you are starting fresh and want Arashi to initialize the workspace root. ```bash mkdir my-meta-repo cd my-meta-repo arashi init ``` When prompted for the repository target, enter `.` to initialize the current directory. ### 2. Add Arashi to an existing meta-repo Use this flow when you already have a repository that should become your Arashi workspace. ```bash cd path/to/existing-meta-repo arashi init ``` Run `arashi init` from the repository root you want Arashi to manage. Once `arashi init` completes, continue with the core workflow: ```bash arashi add git@github.com:your-org/frontend.git arashi create feature-docs-bootstrap arashi switch feature-docs-bootstrap arashi status ``` By default, new managed worktrees are created under `.arashi/worktrees`. Set command defaults in `.arashi/config.json` (`defaults.create`, `defaults.switch`) to define preferred switch and launch behavior, and use `arashi shell install` if you want `arashi switch` to support parent-shell `cd` behavior. If you install Arashi with the official POSIX installer, it can offer shell integration during install so `arashi switch --cd` works without an extra setup step. When the workspace is initialized, choose the workflow guide that matches what you need next: - [Hooks](/workflows/hooks/) for lifecycle automation after create and remove. - [Config](/workflows/config/) for command defaults and shell-aware switching behavior. - [VS Code](/workflows/vscode/) for editor-first worktree management. - [tmux and sesh](/workflows/tmux-and-sesh/) for terminal-native switching and session flows. - [Agents](/workflows/agents-and-specs/) for implementation boundaries and meta-repo guidance. ## Next Steps - Continue to [Commands](/commands/) for command-by-command behavior. - Continue to [Workflows](/workflows/) if you want setup guidance by workflow instead of by command. - Continue to [Contributing](/contributing/) if you want to make a project change. --- # Workflows Source: https://arashi.haphazard.dev/workflows/ Description: Choose guidance for hooks, configuration defaults, editor or terminal workflows, and working with agents in an Arashi workspace. Use this section after `arashi init` when you want workflow guidance instead of a command-by-command reference. ## Choose a Workflow - [Hooks](/workflows/hooks/) for lifecycle automation around create and remove. - [Config](/workflows/config/) for command defaults and post-init switch behavior. - [VS Code](/workflows/vscode/) for editor-first worktree management. - [tmux and sesh](/workflows/tmux-and-sesh/) for terminal-native switching and session workflows. - [Agents](/workflows/agents-and-specs/) for implementation boundaries and meta-repo guidance. - [JSON Automation](/workflows/json-automation/) for machine-readable output, envelope examples, and command support. ## Recommended Path After `arashi init` 1. Configure `defaults.create` and `defaults.switch` so worktree creation and switching match your preferred launch behavior. 2. Add lifecycle hooks if you need setup or cleanup automation around `create` and `remove`. 3. Choose how you want to open worktrees: VSCode, terminal-native tmux flows, or `sesh`-driven session switching. 4. If you work with agents, keep code changes in the affected project repo and shared context in the meta-repo. ## Related Commands - [create](/commands/create/) - [remove](/commands/remove/) - [switch](/commands/switch/) - [shell](/commands/shell/) - [setup](/commands/setup/) --- # Agents Source: https://arashi.haphazard.dev/workflows/agents-and-specs/ Description: Use agents effectively in an Arashi meta-repo by keeping implementation in child repos and shared context in the meta-repo. Use this guide when you want an agent to work safely inside an Arashi meta-repo. It is designed to stand alone as a bootstrap document you can paste into an agent session or link from `/llms.txt`. ## Quick Start For Agents If you are an agent entering an Arashi-managed workspace: 1. Start in the meta-repo root and run `arashi doctor` as a safe, non-mutating workspace-health diagnostic. 2. Read the root `AGENTS.md` or equivalent workspace instructions, then read the owning child repo's instructions before editing. 3. Identify which child repo owns the implementation. 4. Keep implementation, tests, and repo-specific docs in `repos//`. 5. Keep shared context, OpenSpec proposals, plans, and cross-repo coordination in the meta-repo. 6. Inspect detailed repository state with `arashi status` when `doctor` findings or the task require it. 7. Validate every affected repo before review or handoff. 8. Generate an `arashi handoff` report when pausing, switching agents, or leaving dirty work. 9. Use focused PRs and cross-link related PRs when work spans repositories. ## Core Idea Arashi works best with agents when the workspace has a clear split: - implementation belongs in the affected child repo under `repos//` - shared context, planning, and cross-repo documentation belong in the meta-repo That structure makes it much easier to tell an agent where to read, where to write, and what not to mix together. ## What To Tell The Agent When you give an agent work in this workspace, tell it: 1. which child repo owns the implementation 2. that implementation, tests, and repo-specific docs stay in `repos//` 3. that meta-repo context, planning notes, and cross-repo guidance stay in the meta-repo 4. which validation commands to run in the affected repo or repos If your workspace uses `AGENTS.md` files, point the agent at the root file first and then the file inside the child repo it is editing. ## Recommended `AGENTS.md` Use a root `AGENTS.md` to tell agents how your meta-repo is organized. A good default looks like this: ```md # Arashi Meta-Repo Agent Rules This repository is the meta-repo that coordinates work across the child repositories in `repos/`. ## Core Rule - Put implementation in the affected child repository under `repos//`. - Keep shared context, planning, cross-repo notes, and workspace-level guidance in this meta-repo. ## How To Work In This Workspace 1. Start in the child repo that owns the change. 2. Keep code, tests, and project-specific docs in that child repo. 3. Use the meta-repo for change context, coordination, OpenSpec artifacts, and cross-repo guidance. 4. When a change affects multiple repos, update each affected repo directly instead of mixing files into the wrong location. ## Multi-Repo Expectations - A single git commit cannot span multiple repositories. - If a feature changes both planning artifacts and project implementation, commit each affected repository separately. - When command behavior, configuration, or user workflow changes in `repos/arashi`, review companion updates in `repos/arashi-docs/` and `repos/arashi-skills/`. - When multiple repositories need PRs, include explicit cross-links between the PRs and reference the originating issue in each one. ## Repo-Specific Rules - `repos/arashi/AGENTS.md` - `repos/arashi-docs/AGENTS.md` - `repos/arashi-skills/AGENTS.md` - `repos/arashi-vscode/AGENTS.md` ``` Then add smaller `AGENTS.md` files inside the child repos so the agent can pick up repo-specific validation commands and editing rules. ## Recommended Workflow 1. decide which child repo owns the implementation 2. gather context in the meta-repo before making code changes 3. have the agent implement the change in the child repo 4. update related docs or coordination files in the meta-repo when needed 5. validate each affected repo before review or handoff 6. run `arashi handoff` with links, validation evidence, remaining work, risks, and next commands before pausing or transferring context For multi-repo work, do not try to make one commit span the whole workspace. Commit and open PRs from each affected repository, then cross-link those PRs so reviewers can follow the complete change. ## Handoff Reports Use `arashi handoff` to create a concise report when an agent is about to pause, switch with another agent, request review, or leave a dirty coordinated workspace. The command is read-only: it gathers current Arashi status and renders Markdown by default, but it does not run validations, write files, stage changes, commit, push, or delete worktrees. Include context Arashi cannot infer: ```bash arashi handoff \ --link https://github.com/corwinm/arashi-arashi/issues/186 \ --link https://github.com/corwinm/arashi/pull/123 \ --validation "bun run test — passed" \ --validation "bun run build — passed" \ --todo "watch CI" \ --risk "Windows matrix has not finished yet" \ --next-command "gh pr checks 123 --repo corwinm/arashi" ``` Use `--validation` only for commands and results that were actually run. If a check is pending or unverified, put it in `--todo` or `--risk` so the next worker does not mistake it for merge-ready evidence. Use `arashi handoff --json` when an agent or script needs to parse the report. JSON mode uses the standard single-document Arashi envelope and includes workspace metadata, current repository context, per-repository status records, supplied context arrays, warnings, and generated next-command hints. ## Specs Pair Well, But They Are Optional Arashi pairs well with a spec-driven development framework such as OpenSpec because it gives the agent a clean place for proposals, tasks, and design context. The important part is not a specific framework. The important part is keeping: - code in the child repo that owns it - context and coordination in the meta-repo - instructions clear enough that the agent does not need to guess If your assistant environment exposes them, `OpenSpec` commands such as `/opsx-propose` and `/opsx-apply` are a good fit for this workflow. ## Machine-Readable Command Output Agents should prefer `--json` when they need to inspect Arashi state or make decisions from command results. JSON mode keeps stdout reserved for one parseable result document and avoids brittle scraping of progress text, colors, tables, or prompts. Good agent-facing commands include: ```bash arashi doctor --json arashi status --json arashi list --json arashi exec --json -- git status --short arashi handoff --json --link https://github.com/corwinm/arashi-arashi/issues/186 arashi status --group docs --json arashi exec --only arashi-docs --json -- bun run validate arashi exec --group agents --json -- bun run validate arashi create feature-branch --no-launch --no-switch --json arashi clone --all --json arashi pull --group docs --json arashi setup --only api --json ``` In JSON mode, successful commands include `ok: true`, `command`, `schemaVersion`, `data`, and `warnings`. Command-level failures use `ok: false` plus a structured `error` object so agents can branch on `error.code` instead of parsing English text. See the [JSON automation reference](/workflows/json-automation/) for the full envelope contract, stdout/stderr guarantees, and command support matrix. Use `arashi doctor --json` as the first diagnostic command when troubleshooting workspace health. It is read-only and returns stable findings with `code`, `severity`, `category`, `scope`, `message`, and suggested follow-up commands. Treat `error` findings as blockers; use `warning` and `info` findings to guide lower-risk follow-up checks. Use `arashi exec` for repeated multi-repo inspection or validation commands that are not covered by a built-in Arashi command. The child command must follow `--` and runs from each selected repository as its working directory. Prefer `--group ` for known semantic sets such as `core`, `docs`, `extensions`, `agents`, or `infra`; use `--only ` for one-off repository lists. For mutating, expensive, network-heavy, or long-running commands, always apply an explicit `--group` or `--only` filter unless the user asked for every managed repository. When both filters are supplied, `--group` intersects with and narrows `--only`. JSON mode is non-interactive. If a command would normally prompt, launch an editor or terminal, emit shell integration code, or change the parent shell directory, pass explicit non-interactive flags or expect a structured unsupported-mode error such as `JSON_UNSUPPORTED_FOR_MODE`. ## Partial Coordinated Worktrees Arashi supports intentionally partial coordinated worktrees when a task only needs some child repositories. - Use `arashi create --interactive` to choose child repositories while still creating the parent/meta worktree. - Default and short `arashi status` output hide omitted child repositories so partial worktrees do not look broken during everyday checks. - Use `arashi status --verbose` or `arashi status --json` when an agent needs to inspect every configured repository, including missing child repositories. - From inside a partial worktree, use `arashi clone` or `arashi clone --all --json` to add missing child repositories on the current branch. ## Related References - [Curated LLM entrypoint](/llms.txt) - [Full Markdown export](/llms-full.txt) - [JSON automation reference](/workflows/json-automation/) - [Workflows overview](/workflows/) - [Contributing](/contributing/) - [Meta-repo AGENTS.md](https://github.com/corwinm/arashi-arashi/blob/main/AGENTS.md) --- # JSON Automation Source: https://arashi.haphazard.dev/workflows/json-automation/ Description: Arashi's machine-readable output contract, error envelope shape, and command support matrix. Use this reference when you are writing scripts, coding agents, CI checks, or integrations that need stable Arashi command output. Prefer command-specific pages for human workflow examples; use this page for the cross-command JSON contract. ## When To Use JSON Output Use `--json` when a tool needs to parse Arashi output or make decisions from it. JSON mode is designed for automation: - stdout contains one parseable JSON document and a trailing newline - human progress, spinners, prompts, colors, and tables are suppressed from stdout - stderr remains available for diagnostics from child commands or unexpected failures - interactive-only modes fail fast with a structured error instead of prompting Use human output when a person is reading the result directly, especially for exploratory `status`, `doctor`, or `exec` runs where tables and grouped summaries are easier to scan. ## Envelope Shape JSON-capable commands write a single envelope to stdout. ```json { "ok": true, "command": "status", "schemaVersion": 1, "data": { "summary": { "total": 5, "clean": 5, "dirty": 0 }, "repositories": [] }, "warnings": [] } ``` The common fields are: | Field | Meaning | | --- | --- | | `ok` | `true` for command success, `false` for command-level failure. | | `command` | The Arashi command that produced the envelope. | | `schemaVersion` | Version of the envelope contract. Treat new fields as additive unless a future schema version says otherwise. | | `data` | Command-specific result payload. See each command page for examples. | | `warnings` | Non-fatal warnings an agent or script should surface without treating the command as failed. | | `error` | Present when `ok` is `false`; contains structured failure details. | Command-specific `data` payloads may evolve as commands gain more diagnostics, filters, or result details. Consumers should read the fields they need and ignore unknown fields. ## Success Example ```json { "ok": true, "command": "pull", "schemaVersion": 1, "data": { "results": [ { "repository": "arashi-docs", "status": "updated", "durationMs": 812 }, { "repository": "arashi", "status": "skipped", "durationMs": 96 } ], "summary": { "total": 2, "updated": 1, "skipped": 1, "failed": 0, "overall": "success" } }, "warnings": [] } ``` For batch commands such as `pull`, `sync`, `setup`, and `exec`, inspect both the top-level `ok` field and the per-repository results. A command can complete while still reporting skipped repositories or warnings that matter to your workflow. ## Error Example ```json { "ok": false, "command": "remove", "schemaVersion": 1, "error": { "code": "JSON_UNSUPPORTED_FOR_MODE", "message": "JSON output is not supported for interactive-selection.", "details": { "mode": "interactive-selection" } }, "warnings": [] } ``` Prefer branching on `error.code` instead of parsing `message`. Messages are written for humans; codes and details are the stable automation surface. ## Stdout And Stderr Guarantees In JSON mode: - parse stdout as exactly one JSON document - do not expect banners, tables, spinners, progress lines, prompts, or shell snippets on stdout - treat a non-zero process exit plus `ok: false` as a command-level failure - keep stderr for diagnostics, child command output, or unexpected runtime errors - pass explicit flags such as `--all`, `--only`, `--group`, `--no-launch`, or `--no-switch` when a command would otherwise ask a question or launch an external tool If stdout contains human text in JSON mode, that is a bug because it breaks tool consumers. ## Command Support Matrix | Command | JSON support | Notes | | --- | --- | --- | | `add` | Supported | Adds repository configuration and returns a structured result. | | `clone` | Supported with `--all` | `arashi clone --json` requires `--all`; interactive selection is not JSON-compatible. | | `create` | Supported for non-interactive create operations | Use explicit flags such as `--only`, `--group`, `--no-launch`, and `--no-switch`. Interactive selection, launch, or shell switching modes are not JSON-compatible. | | `doctor` | Supported | Best first diagnostic for agents because it is non-mutating and returns stable findings. | | `exec` | Supported | Runs the child command after `--` and returns per-repository stdout, stderr, exit status, and summary data. | | `init` | Supported | Use `--dry-run --json` to preview initialization without writing files. | | `list` | Supported | Also accepts `-j`; useful for discovering coordinated worktrees. | | `move` | Supported | Returns moved, skipped, restored, and failed repository details. | | `pull` | Supported | Use `--only` or `--group` to limit network operations when appropriate. | | `prune` | Supported | Pair with `--dry-run` for non-mutating stale worktree metadata inspection. | | `remove` | Supported with an explicit target | JSON mode does not perform interactive branch selection. Use `--dry-run --json` to preview destructive worktree and branch cleanup. | | `setup` | Supported | Use `--only` or `--group` when setup should not run everywhere. | | `shell init` | Unsupported by design | `--json` returns `JSON_UNSUPPORTED_FOR_MODE` because normal output is shell code. | | `shell install` | No JSON mode | Installs shell integration into a startup file. Use human output. | | `status` | Supported | Prefer this for current repository state when `doctor` says deeper inspection is needed. | | `switch` | Unsupported by design | `--json` returns a structured unsupported-mode error instead of opening terminals, editors, or changing the parent shell. | | `sync` | Supported | Use `--only` or `--group` to limit branch alignment work when appropriate. | | `update` | Supported for check and preview flows | Use `--check --json` or `--dry-run --json`. Applying an installer update with `--yes --json` returns an unsupported-mode error. | ## Stable Unsupported Modes Some commands exist to prompt, launch tools, print shell code, or change the parent shell. Those modes are intentionally not JSON-compatible. When JSON mode is available for an unsupported flow, Arashi returns a structured failure with: - `ok: false` - `error.code: "JSON_UNSUPPORTED_FOR_MODE"` - `error.details.mode` naming the unsupported flow, such as `interactive-selection`, `shell-code`, `terminal-launch`, or `installer-apply` Automation should respond by passing a non-interactive flag, choosing a different command, or falling back to human output for that workflow. ## Agent Guidance Agents should prefer this sequence: ```bash arashi doctor --json arashi status --json arashi list --json ``` Then choose targeted commands based on the task: ```bash arashi exec --only arashi-docs --json -- bun run validate arashi pull --group docs --json arashi create docs/update-reference --no-launch --no-switch --json arashi remove docs/update-reference --dry-run --json ``` For mutating, expensive, or network-heavy commands, use `--only` or `--group` unless the user explicitly asked for every managed repository. ## Command-Specific Examples - [doctor](/commands/doctor/) for structured health findings - [status](/commands/status/) for repository state envelopes - [exec](/commands/exec/) for per-repository child command results - [create](/commands/create/) for non-interactive coordinated worktree creation - [remove](/commands/remove/) for dry-run cleanup previews and explicit target removal - [pull](/commands/pull/) and [sync](/commands/sync/) for coordinated repository updates - [update](/commands/update/) for check and dry-run installer flows --- # Config Source: https://arashi.haphazard.dev/workflows/config/ Description: Set command defaults so Arashi creates and switches worktrees the way your team expects. Use this guide after `arashi init` when you want Arashi to create and switch worktrees in a repeatable way without repeating flags on every command. ## Command Defaults Set defaults in `.arashi/config.json` when you want consistent behavior without repeating flags. ```json { "defaults": { "create": { "switch": true, "launch": true, "launchMode": "sesh" }, "switch": { "mode": "auto", "launchMode": "sesh" } } } ``` - `defaults.create.switch` controls whether Arashi switches into the new worktree after `create`. - `defaults.create.launch` and `defaults.create.launchMode` control how create opens the new context. - `defaults.switch.mode` chooses between launch behavior, parent-shell `cd`, or automatic detection. - `defaults.switch.launchMode` controls how `arashi switch` opens when launch behavior is used. Install shell integration with `arashi shell install` if you want `defaults.switch.mode: "cd"` or `"auto"` to support parent-shell directory changes. ## Suggested Setup Sequence 1. Start with `defaults.create` and `defaults.switch` so the default behavior matches your team. 2. Enable shell integration if you want `arashi switch --cd` behavior. 3. Add hooks after you confirm the create and switch flow you want to automate. 4. Keep shared defaults in config and move environment-specific setup into hooks. ## Repository Groups Add optional `groups` arrays to entries under `repos.` when your workspace has semantic repository sets that you target together. Groups are stored on each repository entry, so there is no separate group registry to keep in sync. ```json { "repos": { "arashi": { "path": "repos/arashi", "gitUrl": "git@github.com:example/arashi.git", "groups": ["core"] }, "arashi-docs": { "path": "repos/arashi-docs", "gitUrl": "git@github.com:example/arashi-docs.git", "groups": ["docs"] }, "arashi-vscode": { "path": "repos/arashi-vscode", "groups": ["extensions"] }, "arashi-skills": { "path": "repos/arashi-skills", "groups": ["agents", "docs"] }, "deploy": { "path": "repos/deploy", "groups": ["infra"] } } } ``` Common layouts use groups such as: - `core` for the primary CLI, API, or shared libraries. - `docs` for documentation sites, examples, and content exports. - `extensions` for editor extensions or optional integrations. - `agents` for skill packages, agent instructions, and automation-facing references. - `infra` for deployment, CI, infrastructure, or operations repositories. A repository can belong to more than one group when it serves multiple roles. Repositories without `groups` remain valid and are treated as ungrouped. Use `--group ` with repo-selecting commands to target a semantic set without enumerating repository names: ```bash arashi status --group docs arashi create feat/update-docs --group docs --no-launch --no-switch arashi exec --group agents -- bun run validate ``` When `--group` and `--only` are supplied together, Arashi intersects the filters: `--group` narrows the explicit repository list instead of broadening it. For example, `arashi exec --only arashi,arashi-docs --group docs -- bun run validate` runs only in `arashi-docs` if that is the only selected repository in the `docs` group. Unknown groups and valid filters that produce an empty intersection are reported as selection errors before mutating commands run. ## Related References - [create command](/commands/create/) - [switch command](/commands/switch/) - [shell command](/commands/shell/) - [Hooks workflow guide](/workflows/hooks/) - [Full configuration reference](https://github.com/corwinm/arashi/blob/main/docs/configuration.md) --- # Hooks Source: https://arashi.haphazard.dev/workflows/hooks/ Description: Use lifecycle hooks to automate setup and cleanup around Arashi create and remove workflows. Use this guide after `arashi init` when your workspace needs setup or cleanup automation around `create` and `remove`. ## Create Hooks - `.arashi/hooks/pre-create.sh` - `.arashi/hooks/post-create.sh` - `.arashi/hooks/pre-create..sh` - `.arashi/hooks/post-create..sh` ## Remove Hooks - `repos//.arashi/hooks/pre-remove.sh` - `repos//.arashi/hooks/post-remove.sh` - `.arashi/hooks/pre-remove.sh` - `.arashi/hooks/post-remove.sh` - `~/.arashi/hooks//pre-remove.sh` - `~/.arashi/hooks//post-remove.sh` - `~/.arashi/hooks/pre-remove.sh` - `~/.arashi/hooks/post-remove.sh` Typical uses: - run repository bootstrap after worktree creation - stop tmux sessions before worktree removal - clear generated files after branch cleanup - apply repository-specific setup without hard-coding it into every workflow command ## `post-create` Examples Create hooks are useful when every new worktree needs the same local setup. Make the hook executable with `chmod +x` after you create it. Useful create-hook variables include: - `ARASHI_WORKTREE_PATH` for the new worktree path - `ARASHI_MAIN_REPO_PATH` for the main workspace path - `ARASHI_BRANCH` for the new branch name - `ARASHI_BASE_BRANCH` for the base branch used to create the worktree ### Install Node Dependencies With `pnpm` Use a repo-specific hook when only one child repo needs package install. File: `.arashi/hooks/post-create.web.sh` ```bash #!/bin/sh set -eu cd "$ARASHI_WORKTREE_PATH" pnpm install --frozen-lockfile ``` ### Create a Python Virtual Environment With `uv` File: `.arashi/hooks/post-create.api.sh` ```bash #!/bin/sh set -eu cd "$ARASHI_WORKTREE_PATH" uv venv uv sync ``` ### Create a Python Virtual Environment With `pip` File: `.arashi/hooks/post-create.api.sh` ```bash #!/bin/sh set -eu cd "$ARASHI_WORKTREE_PATH" python3 -m venv .venv . .venv/bin/activate pip install -r requirements.txt ``` ### Copy a Local `.env` File From the Main Worktree This is useful when your team keeps uncommitted local environment files in the main worktree and wants each new worktree to start with the same local config. File: `.arashi/hooks/post-create.web.sh` ```bash #!/bin/sh set -eu MAIN_ENV="$ARASHI_MAIN_REPO_PATH/repos/web/.env" WORKTREE_ENV="$ARASHI_WORKTREE_PATH/.env" if [ -f "$MAIN_ENV" ] && [ ! -f "$WORKTREE_ENV" ]; then cp "$MAIN_ENV" "$WORKTREE_ENV" fi ``` If you want one shared hook for multiple child repos, use `.arashi/hooks/post-create.sh` and branch inside the script based on the target repository or the files present in `ARASHI_WORKTREE_PATH`. ## Suggested Setup Sequence 1. Confirm the create and remove flow you want first. 2. Add workspace-level hooks only after you know which steps should be automatic. 3. Add repository-scoped or global hooks only for trusted scripts and narrow use cases. 4. Keep hooks focused on environment setup and cleanup, not on core project behavior. ## Related References - [create command](/commands/create/) - [remove command](/commands/remove/) - [Config workflow guide](/workflows/config/) - [Full hooks reference](https://github.com/corwinm/arashi/blob/main/docs/hooks.md) --- # VS Code Source: https://arashi.haphazard.dev/workflows/vscode/ Description: Open and manage Arashi worktrees from VS Code with the CLI or the Arashi extension. Use this guide when VS Code or a VS Code-based editor is your primary destination for opening and managing Arashi worktrees. Cursor and Kiro are VS Code forks, so the same editor-first workflow generally applies there as well. This page focuses on VS Code because the Arashi extension is published through the standard VS Code extension ecosystems. ## Open a Worktree in VS Code Use the CLI when you are already in the terminal and want to open a specific worktree immediately. ```bash arashi switch --vscode feature-auth ``` - Best for editor-first workflows where the terminal is secondary. - Good default when your team reviews changes primarily inside VS Code. - Useful when you want a one-off editor launch without changing workspace defaults. ## Install the VS Code Extension Install the Arashi extension when you want Arashi controls inside the editor, not just a one-off CLI launch. - VS Code Marketplace: [haphazarddev.arashi-vscode](https://marketplace.visualstudio.com/items?itemName=haphazarddev.arashi-vscode) - Open VSX: [haphazarddev.arashi-vscode](https://open-vsx.org/extension/haphazarddev/arashi-vscode) With the extension installed, you can: - run core Arashi commands from the command palette, including `init`, `add`, `clone`, `create`, `pull`, `sync`, `switch`, and `remove` - browse available worktrees in the **Arashi Worktrees** Explorer view grouped by repository, including repo, branch, path, and change status - use panel title actions to create worktrees and refresh the current view without leaving the editor - use inline worktree actions to switch or remove a selected worktree with the exact clicked target - open the workspace root or a related repository in a new editor window from the panel or command palette - review command diagnostics in the **Arashi** output channel when setup or command execution fails - respond to startup warnings in-editor, including a shortcut to run `Arashi: Init Workspace` If the panel is not immediately visible, open the Explorer sidebar and reveal the **Arashi Worktrees** view from the Explorer view menu. ## Recommended Usage Pattern - Use `arashi switch --vscode ` when you are already in the terminal and want VS Code to open a specific worktree immediately. - Use the extension when VS Code is your primary shell for day-to-day worktree management and you want a persistent worktree panel. - Set `arashi.binaryPath`, `arashi.workspaceRoot`, or `arashi.commandTimeoutMs` in VS Code settings when the editor should target a specific binary or workspace root. - Use `--cursor` or `--kiro` when you want the same VS Code-style workflow in those editors. ## Related References - [switch command](/commands/switch/) - [shell command](/commands/shell/) - [tmux and sesh workflow guide](/workflows/tmux-and-sesh/) --- # tmux and sesh Source: https://arashi.haphazard.dev/workflows/tmux-and-sesh/ Description: Use tmux and sesh to keep Arashi worktree switching inside terminal-native session workflows. Use this guide when terminal windows, panes, and sessions are the main way you move between Arashi worktrees. ## tmux Use tmux when you want terminal-native switching and multiple worktrees open at once. ```bash arashi switch feature-auth arashi switch --cd feature-auth ``` - `arashi switch` can open a new tmux window when Arashi detects a tmux session. - `arashi switch --cd` is useful when you want to keep the current shell and jump directly into the worktree path. - Combine tmux with `defaults.switch.mode` when your team wants a consistent terminal flow. ## sesh Use `sesh` when you want tmux session selection to be part of your default worktree navigation. ```bash arashi switch --sesh feature-auth ``` - Good for teams that treat each worktree as a session-oriented workspace. - Works well with `defaults.create.launchMode` or `defaults.switch.launchMode` set to `"sesh"`. - Pair with shortcut flows such as `sesh connect "$(arashi list | fzf)"` when you want faster session selection. ## Choosing Between Them - Pick tmux when you want worktree switching to stay inside terminal windows or panes. - Pick `tmux` plus `sesh` when you want session-aware switching and consistent multi-window navigation. - Use `--cd` when you want Arashi to prepare the target path without opening a new terminal context. ## Related References - [switch command](/commands/switch/) - [shell command](/commands/shell/) - [Config workflow guide](/workflows/config/) - [VS Code workflow guide](/workflows/vscode/) - [Session shortcuts in the skill package](https://github.com/corwinm/arashi-skills/blob/main/skills/arashi/references/session-shortcuts.md) --- # Commands Source: https://arashi.haphazard.dev/commands/ Description: What each Arashi command is for and what it does. Use this section when you want command-level guidance. ## Command Pages - [init](/commands/init/) - initialize a workspace. - [add](/commands/add/) - add a repository to management. - [clone](/commands/clone/) - clone missing configured repositories. - [create](/commands/create/) - create coordinated worktrees. - [move](/commands/move/) - move uncommitted changes between coordinated worktrees. - [doctor](/commands/doctor/) - diagnose workspace health without making changes. - [exec](/commands/exec/) - run an arbitrary command across selected managed repositories. - [handoff](/commands/handoff/) - generate a Markdown or JSON handoff report for coordinated work. - [list](/commands/list/) - list worktree paths. - [status](/commands/status/) - inspect repository state. - [update](/commands/update/) - check for and apply CLI updates. - [switch](/commands/switch/) - open a terminal context for a worktree. - [shell](/commands/shell/) - install shell integration and helpers. - [remove](/commands/remove/) - remove worktrees and branches. - [prune](/commands/prune/) - clean stale Git worktree metadata. - [pull](/commands/pull/) - pull remote updates across repos. - [push](/commands/push/) - publish coordinated branches across repos. - [sync](/commands/sync/) - align child repos to parent branch. - [setup](/commands/setup/) - run setup scripts across repos. ## Typical Flow ```bash arashi init arashi add git@github.com:your-org/frontend.git arashi create feature-branch-name arashi doctor arashi status arashi exec -- git status --short arashi handoff --link https://github.com/your-org/project/issues/123 arashi switch ``` ## Related - [JSON Automation](/workflows/json-automation/) - [Getting Started](/getting-started/) - [Workflows](/workflows/) - [Contributing](/contributing/) --- # status Command Source: https://arashi.haphazard.dev/commands/status/ Description: Inspect workspace and repository state for a branch. ## What It's For Understand branch and repository state before pulling, syncing, or removing worktrees. ## What It Does - Summarizes repository and worktree status across the workspace. - Highlights mismatches and potential issues. - Keeps intentionally omitted child repositories out of the default and short human views for partial coordinated worktrees. - Provides a quick health check for current feature work. ## Usage ```bash arashi status [options] ``` ## Key Options - `-v, --verbose` show full `git status` output for each repository. - `-s, --short` show one-line summaries per repository. - `--group ` inspect only repositories in the requested group. Repeat for multiple groups. - `--json` output machine-readable workspace status. ## Examples ```bash # Default colorized status view arashi status # Full details per repository arashi status --verbose # Compact one-line summary arashi status --short # Inspect documentation repositories only arashi status --group docs # Emit structured status for automation arashi status --json ``` ## Notes - `--verbose` and `--short` are mutually exclusive. - Default and short human output hide configured child repositories that are missing from a partial coordinated worktree. - `--group` filters status to repositories in the requested semantic group, such as `docs`, `core`, or `infra`. - Use `--verbose` or `--json` when you need to see every configured repository, including omitted or missing child repositories. - Non-zero exit codes are returned if repository status checks fail. - JSON mode is useful for agents and scripts that need to decide whether repositories are clean, dirty, behind, or ahead without scraping text. ## Agent Notes - Run `arashi status` before creating, pulling, syncing, removing, or handing off work. - Prefer `arashi status --json` when an agent needs to branch on clean, dirty, ahead, or behind state. - Prefer `arashi status --json` or `arashi status --verbose` before deciding whether to complete a partial workspace with [`arashi clone`](/commands/clone/). - Do not assume a workspace is safe to edit or merge until status confirms the affected repositories are in the expected state. ## Related Commands - [pull](/commands/pull/) - [sync](/commands/sync/) --- # create Command Source: https://arashi.haphazard.dev/commands/create/ Description: Create a feature branch worktree across workspace repositories. ## What It's For Start feature work across multiple repositories from a single command. ## What It Does - Creates a worktree for the target branch in each configured repository. - Ensures repositories are aligned to the same branch name. - In interactive mode, always creates the parent/meta worktree and prompts only for optional child repositories. - Runs configured lifecycle hooks when present. ## Usage ```bash arashi create [options] ``` ## Key Options - `--only ` limit creation to comma-separated repository names. - `--group ` create worktrees only for repositories in the requested group. Repeat for multiple groups. - `-i, --interactive` pick repositories interactively. - `--switch` switch to the created parent worktree after create. - `--no-switch` disable configured create switch defaults for one invocation. - `--launch` open a terminal/editor context after create. - `--no-launch` disable configured create launch defaults for one invocation. - `--sesh` force sesh launch mode (implies launch behavior). - `--conflict ` preselect conflict handling (`ABORT`, `REUSE_EXISTING`). - `--no-hooks` disable hook execution. - `--no-progress` hide progress indicators. - `--dry-run` generate a plan without creating worktrees. - `--move-changes` move compatible uncommitted changes from the current workspace into the new worktree after create. - `--json` output machine-readable create results or structured unsupported-mode errors. ## Examples ```bash # Create branch worktrees across the workspace arashi create feature-auth-refresh # Create in specific repositories only arashi create feature-auth-refresh --only api,web # Create worktrees for the core repository group arashi create feature-auth-refresh --group core # Pick child repositories interactively while always creating the parent worktree arashi create feature-auth-refresh --interactive # Force launch for this run arashi create feature-auth-refresh --launch # Disable configured launch default for this run arashi create feature-auth-refresh --no-launch # Review the plan first arashi create feature-auth-refresh --dry-run # Create worktrees and emit JSON for automation arashi create feature-auth-refresh --no-launch --no-switch --json # Create worktrees and move current uncommitted work into them arashi create feature-auth-refresh --move-changes ``` ## Notes - `create` validates branch names and repository readiness. - On failure, coordinated operations can roll back to keep repos consistent. - Interactive `create` treats the parent/meta repository as the required anchor for the coordinated worktree; the selection prompt only controls child repositories. - `--group` targets configured semantic sets such as `core`, `docs`, `extensions`, `agents`, or `infra`. - When combined with `--only`, `--group` narrows the explicit repository list by intersection. Empty intersections fail before creating worktrees. - A partial coordinated worktree is valid. Add omitted child repositories later with [`arashi clone`](/commands/clone/) from inside that worktree. - Configure defaults in `.arashi/config.json` under `defaults.create` (`switch`, `launch`, `launchMode`). - Precedence for launch/switch behavior is: explicit flag > opt-out flag > config default > built-in default. - JSON mode is intended for non-interactive automation. Launch modes that would open another app or session return a structured unsupported-mode error instead of mixing launch output with JSON. - When the source workspace has uncommitted changes, create output includes guidance for moving compatible changes with [`arashi move`](/commands/move/). In JSON mode, that guidance is returned as structured data instead of human text. ## Agent Notes - Check `arashi status` and `arashi list` before creating a branch so you do not duplicate an existing coordinated worktree. - Use `--no-launch --no-switch` for unattended agent runs unless the user explicitly wants an editor or shell session opened. - Prefer `--json` with explicit non-interactive flags when automation needs to verify created worktree paths. - Use `--interactive` when a task only needs some child repositories; the parent worktree is still present, so shared metadata and coordination remain available. - Prefer `--group ` over a long `--only` list when a known semantic group matches the task scope. ## Related Commands - [status](/commands/status/) - [remove](/commands/remove/) --- # move Command Source: https://arashi.haphazard.dev/commands/move/ Description: Move uncommitted changes between coordinated worktrees. ## What It's For Carry in-progress edits from one Arashi workspace into another after work started in the wrong place. ## What It Does - Finds dirty repositories in the source coordinated workspace. - Matches each dirty source repository to the same repository in the target workspace. - Moves changes with a stash-backed transfer that includes staged and untracked files. - Refuses to apply changes into a target repository that already has uncommitted changes. - Preserves recovery guidance if a move cannot be completed safely. ## Usage ```bash arashi move [options] ``` ## Key Options - `--from ` source branch, worktree name, or full worktree path. - `--to ` target branch, worktree name, or full worktree path. - `--json` output machine-readable move results or structured unsupported-mode errors. When `--from` is omitted, Arashi uses the current dirty workspace when it can. When `--to` is omitted, Arashi prompts for a target workspace. JSON mode requires enough flags to avoid prompts. ## Examples ```bash # Move current workspace changes into a feature workspace arashi move --to feature-auth-refresh # Move changes between two named coordinated workspaces arashi move --from main --to feature-auth-refresh # Use exact worktree paths when branch names are ambiguous arashi move --from /path/to/source --to /path/to/target # Emit structured output for automation arashi move --from main --to feature-auth-refresh --json ``` ## Notes - `move` only moves uncommitted changes. It does not move commits or rename branches. - Target repositories must be clean before receiving changes. - Clean source repositories are skipped. - If target apply fails, Arashi attempts to restore the source and reports a recovery command when manual recovery is needed. - `arashi create` can suggest this command when it detects uncommitted changes in the source workspace. Use `arashi create --move-changes` to move compatible changes immediately after creating the target worktree. ## Agent Notes - Prefer `arashi create --move-changes --json --no-launch --no-switch` when a user explicitly wants to create a worktree and carry current uncommitted work into it. - Use `arashi move --from --to --json` for unattended automation. - Do not use `move` when the target workspace is intentionally dirty; ask the user how to reconcile the target edits first. - Preserve and surface any recovery command exactly as printed. ## Related Commands - [create](/commands/create/) - [list](/commands/list/) - [status](/commands/status/) --- # exec Command Source: https://arashi.haphazard.dev/commands/exec/ Description: Run an arbitrary command across selected managed repositories. ## What It's For Run the same ad hoc command in every selected managed repository without writing a shell loop. `arashi exec` is useful for repeated inspection, validation, tests, and maintenance commands across an Arashi workspace. Each child command runs with its current working directory set to the selected repository path, not the meta-repo root. ## Usage ```bash arashi exec [options] -- [args...] ``` The `--` delimiter is required before the child command. Arashi parses options before `--`; everything after `--` is passed to the child command without being interpreted as Arashi options. ## Options - `--only ` run only the named managed repositories. Use a comma-separated list for multiple repositories. - `--group ` run only repositories in the requested group. Repeat for multiple groups. - `--dirty` run only in selected repositories that have local working-tree changes. - `--jobs ` run up to `n` repositories concurrently. The default is serial execution. - `--fail-fast` stop scheduling additional repositories after the first child-command failure. Already-running jobs may finish and be reported. - `--json` emit one machine-readable JSON envelope instead of grouped human output. ## Examples ```bash # inspect all locally present managed repositories arashi exec -- git status --short # validate one repository arashi exec --only arashi-docs -- bun run validate # validate all documentation repositories arashi exec --group docs -- bun run validate # inspect two repositories arashi exec --only arashi,arashi-docs -- git status --short # show diffs only for repositories with local changes arashi exec --dirty -- git diff --stat # run tests with bounded parallelism arashi exec --jobs 4 -- bun run test # stop starting new test jobs after the first failure arashi exec --jobs 4 --fail-fast -- bun run test # pass child-command flags after the delimiter arashi exec -- bun run test -- --watch=false # capture per-repository stdout, stderr, status, and totals for automation arashi exec --json -- git status --short ``` ## Output And Exit Behavior Human output is grouped by repository so stdout, stderr, and failures remain attributable even when `--jobs` runs commands in parallel. The final summary reports successful, failed, and skipped or not-started repositories. `arashi exec` exits with status code `0` when every executed child command succeeds. If any executed child command exits non-zero, the Arashi process exits non-zero and identifies the failing repository or repositories. When `--dirty` matches no repositories, `arashi exec` exits successfully and reports that no dirty repositories matched. ## JSON Mode Use `--json` when automation needs to inspect results. JSON mode suppresses grouped human output and writes a single parseable document to stdout using the standard Arashi JSON envelope. On full success, the result data includes the child command arguments, effective execution options, selected repositories, per-repository stdout and stderr, exit status, duration, and aggregate totals. If any selected repository fails, the JSON envelope uses `ok: false` and includes the same per-repository result details under the structured error details. The Arashi process exits non-zero when any selected repository fails. ## Notes - Use explicit filters for expensive or mutating commands. Prefer `--group ` for known semantic sets and `--only ` for one-off repository lists. - When combined with `--only`, `--group` narrows the explicit repository list by intersection. - Prefer serial execution for commands that contend for shared resources or produce large output. - `--jobs ` must be a positive integer. - `arashi exec` is intended for non-interactive fan-out commands; avoid child commands that require a TTY prompt or editor. - Missing or unknown repositories named by `--only` are reported as errors instead of silently ignored. ## Related - [status](/commands/status/) for built-in workspace state inspection. - [setup](/commands/setup/) for configured repository setup scripts. - [Agents workflow](/workflows/agents-and-specs/) for automation guidance. --- # pull Command Source: https://arashi.haphazard.dev/commands/pull/ Description: Pull the latest changes across workspace repositories. ## What It's For Update repositories in your workspace without entering each one manually. ## What It Does - Runs pull operations across managed repositories. - Brings local branches up to date with remote changes. - Reports which repositories succeeded or failed. ## Usage ```bash arashi pull [options] ``` ## Key Options - `--only ` limit pull to specific repositories (repeatable). - `--group ` pull only repositories in the requested group (repeatable). - `-v, --verbose` print full git output. - `--json` output machine-readable pull results. ## Examples ```bash # Pull all eligible repositories arashi pull # Pull selected repositories only arashi pull --only api --only web # Pull infrastructure repositories only arashi pull --group infra # Pull with detailed command output arashi pull --verbose # Pull selected repositories and emit JSON arashi pull --only api --json ``` ## Notes - Repositories with no remote changes are skipped. - `--group` targets configured semantic sets; with `--only`, it narrows the explicit repository selection by intersection. - Pull failures or manual-update states return a non-zero exit code. - In JSON mode, stdout contains one result document; verbose diagnostics stay out of stdout. ## Agent Notes - Use `arashi pull` before starting a new coordinated worktree when `arashi status` shows repositories are behind. - Prefer `--group ` when the user has scoped work to a known semantic set, or `--only ` when the work is limited to one repository. - Re-run `arashi status` after pulling to confirm the workspace is ready for edits. ## Related Commands - [sync](/commands/sync/) - [status](/commands/status/) --- # push Command Source: https://arashi.haphazard.dev/commands/push/ Description: Publish coordinated branches across repositories. ## What It's For Publish the current coordinated branch before opening related PRs across the parent repo and any changed child repositories. ## What It Does - Evaluates the current branch in the parent workspace and configured child repositories. - Pushes repositories with publishable local branch commits. - Skips untouched, already up-to-date, detached, or unconfigured repositories with clear reasons. - Avoids creating remote branches for child repositories that were intentionally untouched. ## Usage ```bash arashi push [options] ``` ## Key Options - `--only ` include only a named repository. Repeat it to select multiple repositories. - `--group ` include only repositories in the requested group. Repeat for multiple groups. - `--set-upstream` publish new branches and configure upstream tracking. - `--dry-run` preview planned pushes without updating remotes. - `--json` output a single machine-readable result envelope. ## Examples ```bash # Publish eligible repositories with existing upstreams arashi push # Publish a new coordinated branch arashi push --set-upstream # Publish only the CLI repo arashi push --only arashi --set-upstream # Publish changed documentation repositories only arashi push --group docs --set-upstream # Preview before publishing arashi push --set-upstream --dry-run # Use automation-safe output arashi push --set-upstream --json ``` ## Notes - `push` does not open pull requests; it only publishes branches. - Repositories without upstream tracking are skipped unless `--set-upstream` is supplied. - Dry-run is a local preview and does not contact or mutate remotes. - `--group` narrows publishing to configured semantic sets; when combined with `--only`, both filters must match. - JSON mode keeps stdout parseable as one envelope and reports skipped repositories as structured warnings. ## Agent Notes - Use `arashi push --set-upstream` after committing implementation changes and before opening related PRs. - Use `--group ` for known semantic sets and `--only ` for focused child-repo PRs instead of pushing every coordinated worktree. - Do not manufacture remote branches for clean, untouched child repositories just because the coordinated branch exists locally. ## Related Commands - [pull](/commands/pull/) - [sync](/commands/sync/) - [status](/commands/status/) --- # sync Command Source: https://arashi.haphazard.dev/commands/sync/ Description: Synchronize workspace repositories and worktree state. ## What It's For Reconcile workspace state when repositories drift or after branch lifecycle changes. ## What It Does - Checks configured repositories against expected workspace metadata. - Refreshes repository/worktree alignment. - Surfaces mismatches so maintainers can resolve them quickly. ## Usage ```bash arashi sync [options] ``` ## Key Options - `--only ` sync comma-separated repository names only. - `--group ` sync only repositories in the requested group. Repeat for multiple groups. - `-v, --verbose` show detailed per-repository sync output. - `--json` output machine-readable sync results. ## Examples ```bash # Sync all managed repositories arashi sync # Sync selected repositories arashi sync --only api,web # Sync agent-support repositories arashi sync --group agents # Sync with per-repo details arashi sync --verbose # Sync selected repositories and emit JSON arashi sync --only api,web --json ``` ## Notes - `sync` aligns repositories to the parent repository's current branch. - When needed, it can create missing target branches in child repositories. - `--group` targets configured semantic sets; with `--only`, it narrows the explicit repository selection by intersection. - JSON mode keeps stdout parseable as a single result document for programmatic callers. ## Agent Notes - Use `arashi sync` when branch/worktree state has drifted and you need the child repos aligned to the current parent branch. - Prefer `--group ` when only a known semantic set should be synchronized. - Inspect `arashi status` before and after sync so any remaining mismatches are visible before implementation or handoff. - Avoid using sync as a substitute for understanding dirty worktrees; resolve or preserve local changes deliberately. ## Related Commands - [pull](/commands/pull/) - [push](/commands/push/) - [status](/commands/status/) --- # remove Command Source: https://arashi.haphazard.dev/commands/remove/ Description: Remove worktrees and optionally delete associated branches. ## What It's For Clean up feature branches and worktrees when work is done or abandoned. ## What It Does - Removes matching worktree directories from the workspace. - Can also delete corresponding Git branches. - Supports safety checks for dirty worktrees and optional force behavior. ## Usage ```bash arashi remove [target] [options] ``` ## Key Options - `--no-check-dirty` skip uncommitted changes checks. - `--keep-worktrees` delete branches but keep worktree directories. - `--keep-branches` remove worktrees but keep branches. - `-f, --force` skip confirmation prompts. - `--dry-run` preview planned removals without changing worktrees, branches, or lifecycle hooks. - `--path` treat `target` as a worktree path. - `--json` output machine-readable results. ## Examples ```bash # Remove a branch across managed repositories arashi remove feature-login # Interactive selection mode arashi remove # Remove by path arashi remove ./repos/api/feature-login --path # Preview the removal plan without changing files or branches arashi remove feature-login --dry-run # Emit a machine-readable non-mutating plan for agents and scripts arashi remove feature-login --dry-run --json # Remove non-interactively and emit JSON arashi remove feature-login --force --json ``` ## Notes - Main worktrees are skipped automatically. - If both `--keep-worktrees` and `--keep-branches` are set, no operation is performed. - Dirty worktrees require explicit confirmation unless `--no-check-dirty` is used. - `--dry-run` suppresses confirmation prompts and reports the planned worktree removals, branch deletions, dirty-worktree blockers, skipped main worktrees, missing branches, and configured remove hooks without mutating anything. - `arashi remove --dry-run --json` returns a single JSON envelope whose `data` includes `dryRun: true`, pending operations, effective options, blockers, and hook previews for automation. - Stale Git-prunable worktree records are excluded from `remove`; use `arashi prune` to clean stale metadata. - JSON mode does not prompt; pass explicit safety flags such as `--force` or `--no-check-dirty` when appropriate. ## Agent Notes - Treat `remove` as destructive: confirm the target branch/worktree and inspect `arashi status` before running it. - Prefer `arashi remove --force --json` only after the user has asked for cleanup and the relevant work is merged or intentionally abandoned. - Do not bypass dirty checks unless the user explicitly accepts losing or preserving those changes another way. ## Lifecycle Hooks `remove` supports scoped `pre-remove.sh` and `post-remove.sh` hooks. Hook discovery order for each targeted repository: 1. `repos//.arashi/hooks/.sh` 2. `.arashi/hooks/.sh` 3. `~/.arashi/hooks//.sh` 4. `~/.arashi/hooks/.sh` Behavior: - Any failing `pre-remove` hook aborts destructive remove actions. - Dry-run mode reports hooks that would be considered but never executes `pre-remove` or `post-remove` scripts. - `post-remove` hooks still run after partial remove failures. - Any failing `post-remove` hook returns a non-zero command exit status. - Hooks receive scope metadata via `ARASHI_HOOK_SCOPE` and `ARASHI_HOOK_SOURCE_PATH`. ## Related Commands - [list](/commands/list/) - [create](/commands/create/) - [prune](/commands/prune/) --- # prune Command Source: https://arashi.haphazard.dev/commands/prune/ Description: Clean stale Git worktree metadata across an Arashi workspace. ## What It's For Clean up stale Git worktree metadata when a worktree directory was deleted manually or Git's worktree records otherwise get out of sync. Use `prune` for stale metadata. Use [`remove`](/commands/remove/) when you want to delete real worktree directories and optionally delete branches. ## What It Does - Finds worktree records that Git marks as prunable across the main repository and configured child repositories. - Reports stale entries without changing anything when run with `--dry-run`. - Runs Git worktree pruning for affected repositories in mutating mode. - Supports JSON output for automation and agent workflows. ## Usage ```bash arashi prune [options] ``` ## Key Options - `--dry-run` report stale worktree metadata without pruning it. - `--expire