Skip to content
Arashi logoArashi

Config

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

Section titled “Command Defaults”

Set defaults in .arashi/config.json when you want consistent behavior without repeating flags.

{
  "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

Section titled “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

Section titled “Repository Groups”

Add optional groups arrays to entries under repos.<name> 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.

{
  "repos": {
    "arashi": {
      "path": "repos/arashi",
      "gitUrl": "[email protected]:example/arashi.git",
      "groups": ["core"]
    },
    "arashi-docs": {
      "path": "repos/arashi-docs",
      "gitUrl": "[email protected]: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 <group> with repo-selecting commands to target a semantic set without enumerating repository names:

Terminal window
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.

Section titled “Related References”