Skip to content
Back to search

squadrn

MarketplaceWorks with Claude CodeGitHub

Squadrn: run many coding agents in parallel across accounts and worktrees, with git guardrails.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/squadrn/squadrn-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/squadrn/squadrn-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/squadrn--squadrn-cli/badge.svg)](/listings/squadrn--squadrn-cli)

HTML

<a href="/listings/squadrn--squadrn-cli"><img src="/api/listings/squadrn--squadrn-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

macOS and Linux (needs `curl` or `wget`, `git` 2.31+ and `ssh-keygen`; no GitHub account):

curl -fsSL https://github.com/squadrn/squadrn-cli/releases/latest/download/install.sh | sh

`latest` points to the newest stable release; GitHub skips pre-releases there. Until a stable release exists, or for any other release, take that release's installer (it installs the release it was downloaded from; see [releases](https://github.com/squadrn/squadrn-cli/releases)):

curl -fsSL https://github.com/squadrn/squadrn-cli/releases/download/v1.0.0-rc.1/install.sh | sh

The default command is **`srn`** with the alias **`squadrn`**. If another program already uses a name (the npm package `srn` installs one), the installer says so; at a terminal it asks for other names (Enter keeps the default); or pass them up front (`--alias ''` installs no alias; `SQUADRN_COMMAND`, `SQUADRN_ALIASES` and `SQUADRN_VERSION` work too):

curl -fsSL https://github.com/squadrn/squadrn-cli/releases/latest/download/install.sh | sh -s -- --command ai --alias ''

The installer checks the release signature (`ssh-keygen`) and checksum, installs the binary to `~/.local/share/squadrn/bin/squadrn`, links your command name(s) from `~/.local/bin`, and installs the squadrn plugin into every Claude account. On the first install at a terminal it then runs `srn setup`: it finds the agent CLIs on PATH, asks for the default settings profile, offers to adopt existing `~/.claude-<name>` dirs and to track usage limits, and runs `srn doctor` (every step can be skipped; run it again any time). Without a terminal it prints what it found and the next steps. Releases also carry GitHub build provenance; verify an archive by hand with `gh attestation verify <archive> --repo squadrn/squadrn-cli`.

Windows (beta)

Requires [Git for Windows](https://git-scm.com/download/win) 2.31+. In PowerShell:

irm https://github.com/squadrn/squadrn-cli/releases/latest/download/install.ps1 | iex

`latest` is the newest stable release; for a pre-release, or any other release, use its own installer:

irm https://github.com/squadrn/squadrn-cli/releases/download/v1.0.0-rc.1/install.ps1 | iex

`| iex` cannot pass options: set `$env:SQUADRN_COMMAND`, `$env:SQUADRN_ALIASES` or `$env:SQUADRN_VERSION` first, or use the script block form:

& ([scriptblock]::Create((irm https://github.com/squadrn/squadrn-cli/releases/latest/download/install.ps1))) -Command ai -Alias '' -AddToProfile

A failed install prints the reason in red and leaves the window open. `-AddToProfile` loads tab completion from your PowerShell profile; `self-uninstall` removes that line again.

Everything above works the same, with these differences: - `grid`, `ps` and `swap` inside a pane need tmux and are not available; run each agent with `srn wt <name>` in its own terminal tab. `swap` outside a grid works. - Command names are copies of `squadrn.exe` in `%USERPROFILE%\.local\bin`, refreshed on update. - Shared settings use symbolic links with Developer Mode enabled; without it, directories become junctions and files hash-checked copies (an edit in a secondary account is reported, never overwritten). - The push guard covers both the Bash (Git Bash) and PowerShell tools of Claude Code. - Until releases are code-signed, SmartScreen may warn on first run.

Updates

Like Claude Code, squadrn tells you about a new release and never installs it by itself. Once a day it checks in the background (never delaying a command) and, at a terminal, shows one line:

✦ squadrn v1.1.0 is available (you have v1.0.0) · srn self-update · what's new: srn self-update --check
srn self-update --check       # what is new (release notes)
srn self-update               # install it: signature, checksum, then the plugin in every account
srn self-update --rollback    # back to the release installed before (run again to go forward)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "squadrn",
  3. "owner": {
  4. "name": "Squadrn"
  5. },
  6. "description": "Squadrn: run many coding agents in parallel across accounts and worktrees, with git guardrails.",
  7. "plugins": [
  8. {
  9. "name": "squadrn",
  10. "source": "./plugin",
  11. "description": "Guardrails and helpers for parallel coding agents."
  12. }
  13. ]
  14. }
README.md · README · 490 lines · 5 findings marked
  1. # Squadrn
  2. Squadrn — command `srn` (also `squadrn`).
  3. *A squadron of coding agents. Any provider, any account, in parallel.*
  4. Run many coding agents in parallel on one machine — across several accounts and isolated git
  5. worktrees — with a guard that stops agents from force-pushing or pushing to protected branches.
  6. Providers: Claude Code and OpenAI Codex CLI (`claude/…`, `codex/…` accounts); the account model
  7. is ready for more.
  8. Platforms: macOS and Linux (amd64, arm64); Windows 10 21H2+/11 (amd64, arm64) in beta, without
  9. `grid` (ADR 0008).
  10. ## Install
  11. macOS and Linux (needs `curl` or `wget`, `git` 2.31+ and `ssh-keygen`; no GitHub account):
  12. ```sh
  13. curl -fsSL https://github.com/squadrn/squadrn-cli/releases/latest/download/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 20 on GitHub
  14. ```
  15. `latest` points to the newest stable release; GitHub skips pre-releases there. Until a stable
  16. release exists, or for any other release, take that release's installer (it installs the release
  17. it was downloaded from; see [releases](https://github.com/squadrn/squadrn-cli/releases)):
  18. ```sh
  19. curl -fsSL https://github.com/squadrn/squadrn-cli/releases/download/v1.0.0-rc.1/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 28 on GitHub
  20. ```
  21. The default command is **`srn`** with the alias **`squadrn`**. If another program already
  22. uses a name (the npm package `srn` installs one), the installer says so; at a terminal it asks for
  23. other names (Enter keeps the default); or pass them up front (`--alias ''` installs no
  24. alias; `SQUADRN_COMMAND`, `SQUADRN_ALIASES` and `SQUADRN_VERSION` work too):
  25. ```sh
  26. curl -fsSL https://github.com/squadrn/squadrn-cli/releases/latest/download/install.sh | sh -s -- --command ai --alias ''
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 37 on GitHub
  27. ```
  28. The installer checks the release signature (`ssh-keygen`) and checksum, installs the binary to
  29. `~/.local/share/squadrn/bin/squadrn`, links your command name(s) from `~/.local/bin`, and installs
  30. the squadrn plugin into every Claude account. On the first install at a terminal it then runs
  31. `srn setup`: it finds the agent CLIs on PATH, asks for the default settings profile, offers to adopt
  32. existing `~/.claude-<name>` dirs and to track usage limits, and runs `srn doctor` (every step can be
  33. skipped; run it again any time). Without a terminal it prints what it found and the next steps.
  34. Releases also carry GitHub build provenance; verify
  35. an archive by hand with `gh attestation verify <archive> --repo squadrn/squadrn-cli`.
  36. ### Windows (beta)
  37. Requires [Git for Windows](https://git-scm.com/download/win) 2.31+. In PowerShell:
  38. ```powershell
  39. irm https://github.com/squadrn/squadrn-cli/releases/latest/download/install.ps1 | iex
  40. ```
  41. `latest` is the newest stable release; for a pre-release, or any other release, use its own installer:
  42. ```powershell
  43. irm https://github.com/squadrn/squadrn-cli/releases/download/v1.0.0-rc.1/install.ps1 | iex
  44. ```
  45. `| iex` cannot pass options: set `$env:SQUADRN_COMMAND`, `$env:SQUADRN_ALIASES` or
  46. `$env:SQUADRN_VERSION` first, or use the script block form:
  47. ```powershell
  48. & ([scriptblock]::Create((irm https://github.com/squadrn/squadrn-cli/releases/latest/download/install.ps1))) -Command ai -Alias '' -AddToProfile
  49. ```
  50. A failed install prints the reason in red and leaves the window open. `-AddToProfile` loads tab
  51. completion from your PowerShell profile; `self-uninstall` removes that line again.
  52. Everything above works the same, with these differences:
  53. - `grid`, `ps` and `swap` inside a pane need tmux and are not available; run each agent with
  54. `srn wt <name>` in its own terminal tab. `swap` outside a grid works.
  55. - Command names are copies of `squadrn.exe` in `%USERPROFILE%\.local\bin`, refreshed on update.
  56. - Shared settings use symbolic links with Developer Mode enabled; without it, directories become
  57. junctions and files hash-checked copies (an edit in a secondary account is reported, never
  58. overwritten).
  59. - The push guard covers both the Bash (Git Bash) and PowerShell tools of Claude Code.
  60. - Until releases are code-signed, SmartScreen may warn on first run.
  61. ### Updates
  62. Like Claude Code, squadrn tells you about a new release and never installs it by itself. Once a day
  63. it checks in the background (never delaying a command) and, at a terminal, shows one line:
  64. ```
  65. ✦ squadrn v1.1.0 is available (you have v1.0.0) · srn self-update · what's new: srn self-update --check
  66. ```
  67. ```sh
  68. srn self-update --check # what is new (release notes)
  69. srn self-update # install it: signature, checksum, then the plugin in every account
  70. srn self-update --rollback # back to the release installed before (run again to go forward)
  71. srn self-update --tag v1.2.0 # a specific release
  72. srn config set update_channel beta # also pre-releases; stable is the default
  73. srn config set update_check false # no checks, no notices (also: SQUADRN_NO_UPDATE_CHECK=1)
  74. ```
  75. Updates keep your command names, refuse to downgrade unless `--allow-downgrade`, and refuse any
  76. release not signed by a key built into the copy you have. No notice is shown in CI, with `--json`
  77. or outside a terminal. `srn doctor` mentions a pending update too.
  78. To remove squadrn: `srn self-uninstall` (plugin from every account, command links, completions,
  79. installed files; accounts are kept). `--purge` also removes the config, guard log and caches.
  80. ### Names and completions
  81. ```sh
  82. <command> config set command ai # relinks ~/.local/bin and the shell completions
  83. <command> config set aliases srn,sx
  84. ```
  85. Completions for zsh (`~/.zsh/completions`), bash (`~/.local/share/bash-completion/completions`)
  86. and fish (`~/.config/fish/completions`) are written when those directories exist; otherwise
  87. `srn completion zsh|bash|fish` prints them.
  88. Requirements: `claude` (native build), `git` 2.31 or newer; `tmux` for `grid`/`ps`.
  89. Optional: `gh` (PR detection in `gc`, the branch protection check in `doctor`, build provenance).
  90. Updates read the public GitHub API; set `GH_TOKEN` or `GITHUB_TOKEN` (or log in with `gh`) only if
  91. you hit its rate limit. Examples below use `srn`; `squadrn` works the same.
  92. ## Use within Anthropic's terms
  93. Squadrn runs Claude Code under accounts you own — for example your work organization's account
  94. and your personal one — and keeps them apart. It is not a way to share an account with other
  95. people or to get around usage limits: each account stays bound by its own plan, limits and the
  96. [terms](https://www.anthropic.com/legal/consumer-terms) of the organization it belongs to.
  97. `usage` and `swap` help you continue a conversation on the right one of your accounts.
  98. ## Accounts
  99. An account is a provider's config dir, written `provider/name`: `claude/main` is `~/.claude`,
  100. `claude/personal` is `~/.claude-personal`. A bare name works when it is unique across providers;
  101. `main` always means the default provider's main account. `CLAUDE.md`, agents, commands, rules,
  102. output styles, hooks and skills are shared from the provider's main account through symlinks;
  103. logins, history and plugins stay per account. Each account has its own `settings.json`, built from
  104. main's plus a profile and kept in step with main before every session; a key you change in the
  105. account (`/model`) stays yours and is reported once ([ADR 0011](docs/adr/0011-provider-model-v2.md)).
  106. New accounts get a settings profile: `minimal` (secrets denied), `standard` (the default: secrets
  107. and other accounts' credentials denied, asks before `git push`, `git reset --hard` and `rm -rf`,
  108. 30-day history) or `strict` (also sandboxed, reads limited to the project, 14-day history).
  109. `--with privacy` turns telemetry off, `--with no-attribution` drops AI attribution; neither is on
  110. by default, and the model, effort and permission mode are left to the CLI.
  111. ```sh
  112. srn # pick an account interactively (offers login when needed)
  113. srn personal # run as claude/personal (also: claude/personal, -a personal)
  114. srn personal -p "summarize" # agent flags go to the agent CLI unchanged
  115. srn personal -- "fix the bug" # a prompt goes after --
  116. srn personal mcp list # agent subcommands pass through
  117. srn setup # guided first run (CLIs, profile, adopt, usage, doctor)
  118. srn account add # guided: provider, name, settings, review, then the login
  119. srn account add work # create claude/work (asks profile, usage, login)
  120. srn account add work -p codex --profile strict --with privacy,no-attribution --usage --login -y
  121. srn account add work --dry-run # print the plan, change nothing (--json: one result object)
  122. srn account add other --adopt # make an existing ~/.claude-other an account and set it up
  123. srn account repair work # bring claude/work up to date (--all: every account)
  124. srn account default work # a bare srn runs claude/work (--unset: main again)
  125. srn account login work
  126. srn account ls [--json]
  127. srn account logout work
  128. srn account rename work job # logs work out first; log in again as job
  129. srn account rm work # logs out and moves the dir to the trash (macOS ~/.Trash)
  130. ```
  131. `srn account rm work --purge` deletes the dir permanently instead of trashing it and removes every
  132. record squadrn keeps of the account: its usage record, its entries in the handoff ledger, its
  133. in-use records (in its dir and in the repositories its records name) and its cached login status.
  134. It prints exactly what it removed. Links inside the dir are removed, never followed; a dir that is
  135. itself a link is refused. At a terminal you confirm by typing the account (`claude/work`), unless
  136. you pass `-y`; scripts without a terminal pass `--purge --yes`. If something cannot be deleted (a file
  137. another program holds open on Windows), the account and its records stay and the same command
  138. finishes the job.
  139. A word that is neither a squadrn command, an account nor an agent subcommand is a usage error with
  140. a suggestion (`srn acount` → *did you mean account?*), so a typo never becomes a prompt.
  141. Global options before the command: `-a <account>`, `-C <dir>`, `--no-color` (also `NO_COLOR=1`).
  142. A dir named like an account but not made by squadrn (no `.squadrn-account` marker) is not an
  143. account: `account ls` lists it as unmanaged and `account add <name> --adopt` makes it one.
  144. `account add` only creates: on an existing account it fails and names `account repair`, which
  145. brings an account up to date (shared links, settings, push guard, usage tracking, `--relink`); the
  146. installer, `self-update` and `doctor` point at it. `account default <account>` stores
  147. `default_account` in the config: a bare `srn` (and an agent subcommand such as `srn mcp list`)
  148. then runs that account instead of the default provider's main account.
  149. Account names: `^[a-z][a-z0-9-]{1,23}$`, e.g. `personal`, `acme-2`. squadrn's own commands
  150. (`wt`, `grid`, …) are rejected; an agent subcommand name (`mcp`) is fine, and such an account is
  151. matched before the subcommand. Account dirs are created private (`0700`).
  152. ### Several providers
  153. Every provider has its own accounts, dirs and CLI; `provider/name` picks one. Codex CLI
  154. accounts are `CODEX_HOME` dirs: `codex/main` is `~/.codex` (Codex's default, nothing set) and
  155. `codex/work` is `~/.codex-work`. Install Codex first (`npm install -g @openai/codex`); `doctor`
  156. only requires a provider's CLI once you have accounts for it.
  157. ```sh
  158. srn account add codex/work # ~/.codex-work, push guard hook, AGENTS.md/skills/rules from codex/main
  159. srn account login codex/work # codex login with CODEX_HOME=~/.codex-work
  160. srn codex/work # start Codex as that account (srn work when the name is unique)
  161. srn work exec "fix the tests" # codex subcommands pass through: exec, resume, mcp, review, …
  162. srn work resume <session-id> # resume a conversation of that account
  163. srn doctor # login, guard hook trust and credential store per account
  164. ```
  165. Each Codex account keeps its login in its own `auth.json`: squadrn sets
  166. `cli_auth_credentials_store = "file"` in the account's `config.toml` (the OS keyring would be
  167. shared) and restores it whenever it runs Codex for the account. MCP servers listed in
  168. `shared_mcp` are copied from `codex/main` with `codex mcp add`. Claude-only for now: `swap`
  169. (Codex's session store is not documented), `wt` and `grid` worktrees (`codex --worktree` takes
  170. no name), usage limits in the status line (`srn usage` asks Codex for them instead, at most every
  171. 5 minutes unless `--refresh`).
  172. Codex profiles map to `config.toml`: `minimal` keeps credentials per account and secret
  173. environment variables out of commands; `standard` (default) adds a workspace-write sandbox without
  174. network that asks before leaving it; `strict` makes the workspace **read-only** — use it for
  175. review-only accounts, and `standard` for daily work.
  176. ## Usage limits
  177. Claude Code reports a subscription's 5-hour and 7-day usage to its status line, and runs a
  178. `StopFailure` hook when a turn stops on a usage limit. squadrn records both per account, so you
  179. can see where each of your accounts stands and continue on the right one.
  180. ```sh
  181. srn usage # every account: plan, org, 5h/7d used and reset times, state
  182. srn usage work # details, including the last limit hit and handoff
  183. srn usage --json # stable JSON (below)
  184. srn usage --refresh # also re-query login, plan and organization
  185. srn usage --watch # redraw every 5 seconds
  186. srn usage setup [work|--all] # record usage through the status line (asks; -y skips)
  187. srn usage setup --undo # restore the previous status line
  188. ```
  189. `usage setup` wraps the status line command in `settings.json`: squadrn records what it receives, then
  190. runs your own command with the same input and shows its output unchanged (without one, it shows
  191. `work · 5h 42% · 7d 18%`). Each account's own `settings.json` is set up on its own. `account add` offers it once (`--usage`/`--no-usage` decide without asking);
  192. `self-uninstall` restores the previous command; `doctor` shows whether each account is tracked.
  193. When a session hits its limit, the plugin's hook records it and notifies
  194. *"Usage limit · resets 15:45 · srn swap"* (see [Notifications](#notifications)).
  195. Usage is only known for claude.ai subscriptions (Pro, Max, …), after a session's first reply, and
  196. only as fresh as the last status line update. States: `ok`, `high` (5h ≥ 80% or 7d ≥ 90%),
  197. `limited`, `reset` (a limit or high window has reset since), `stale` (older than 6 hours),
  198. `nodata`, `metered` (API billing), `loggedout`, `na` (provider does not report usage). The footer
  199. names the best account for the current repository, the current account included: the same
  200. provider, not limited, known headroom (`ok`, `reset`) before `nodata`/`stale`, then lowest 5h and
  201. 7d use. Reset times show the weekday when they are not today (`Thu 15:45`). Logged-out accounts are
  202. not listed as untracked. Records live in `~/.local/state/squadrn/usage/` (private).
  203. ## Swap
  204. `swap` moves a conversation to another of your accounts and resumes it there, in the directory it
  205. was started in.
  206. ```sh
  207. srn swap # the conversation that just hit its limit here; pick the target
  208. srn swap --to personal # same, to claude/personal
  209. srn swap --session <id> --to work # any conversation, by session ID
  210. srn swap --worktree feat-a --to personal # latest conversation of worktree feat-a
  211. ```
  212. Without `--session`, the conversation is the one that last hit its limit in the current directory
  213. or below it, or a session running there (several: a picker; without a terminal, an error listing
  214. their `--session` values). Without `--to`, the target is picked from the accounts ranked like
  215. `srn usage` (without a terminal, `--to` is required). A logged-out target is refused, moving to
  216. another organization asks, and an Opus conversation moving to a Pro account warns.
  217. A session still running the conversation is stopped first, so it never has two writers: inside a
  218. grid its pane is restarted in place; elsewhere squadrn asks, interrupts it (ctrl-c) and, if it is
  219. still running after 10 seconds, asks again and terminates it (`-y` answers yes). On Windows a
  220. session in another terminal cannot be interrupted, so it is terminated after you agree.
  221. The transcript, its subagent and tool-result dir and its file checkpoints are copied (the copy is
  222. checked against the source). When the target already has the conversation and it went on there,
  223. the swap is refused unless `--force` overwrites that copy. Every handoff is appended to
  224. `~/.local/state/squadrn/handoffs.jsonl`.
  225. `--json` prints `{"accounts": [...], "from": "...", "best": "...", "next_reset": "..."}` (`from`:
  226. the account last limited or active in this directory; `next_reset`: when every account is limited,
  227. the first reset). Each account (also printed alone by `usage <account> --json`):
  228. ```json
  229. {
  230. "account": "claude/work", "plan": "max", "org": "Acme", "email": "me@example.com",
  231. "logged_in": true, "state": "limited", "tracking": true,
  232. "five_hour": {"used_pct": 100, "resets_at": "2026-11-18T15:45:00+01:00"},
  233. "seven_day": {"used_pct": 41, "resets_at": "2026-11-23T00:00:00+01:00"},
  234. "spend": {"used_pct": 63, "resets_at": "…", "used_usd": 314.12, "limit_usd": 500, "period": "monthly"},
  235. "observed_at": "2026-11-18T13:02:11+01:00",
  236. "last_limit": {"at": "…", "session": "…", "cwd": "/repo", "resets_at": "…"},
  237. "error": "login status unavailable (only when it is)"
  238. }
  239. ```
  240. Missing values are left out; `logged_in` is `null` when the login status is unavailable. No data is
  241. not an error: the command exits 0.
  242. ## Parallel agents
  243. ```sh
  244. srn wt feat-login # agent in .claude/worktrees/feat-login
  245. srn wt ls [--json] # worktrees, modified or not, running as whom
  246. srn wt rm feat-login [--force] # remove one (branch only if merged)
  247. srn wt rm feat-login --force-branch # also delete an unmerged branch (asks; -y)
  248. srn grid ~/repo feat-a personal:fix-b # tmux grid, one agent per pane
  249. srn grid ~/repo feat-a claude/personal:fix-b # account as provider/name
  250. srn grid ~/repo feat-1 feat-2 feat-3 --spread # spread over logged-in accounts
  251. srn grid ~/repo personal:chore-c # add a pane to the running grid
  252. srn grid ls | attach [repo] | stop [repo] # manage running grids
  253. srn ps [--json] # every running agent: account, worktree, state
  254. srn next # jump to the tmux pane that waits for you
  255. srn deps feat-a # install dependencies (exit status passes through)
  256. srn gc [--json] # merged/empty worktrees; --yes removes them
  257. srn gc --yes --force # also those git refuses (submodules)
  258. ```
  259. `wt rm` refuses a worktree a running session uses (`--force` removes it anyway) and keeps an
  260. unmerged branch unless `--force-branch` is given.
  261. Worktree names are `<type>-<slug>` (`feat-otp-login`, `fix-cart-total`); Claude Code creates branch
  262. `worktree-<name>`. `swap` moves conversations between accounts of the same provider (see [Swap](#swap)).
  263. ## Notifications
  264. Squadrn tells you when an agent needs you, failed or finished, and stays quiet while you are
  265. looking at it:
  266. | Event | When | Example |
  267. |---|---|---|
  268. | `input` | an approval, a question, a reply it waits for | *Needs approval: Bash* · *Waiting for your reply* |
  269. | `failed` | the turn stopped on an error | *Usage limit · resets 15:45 · srn swap* · *Login expired · srn account login claude/work* |
  270. | `done` | the turn finished (no background work left) | *Done* |
  271. | `info` | logged in, auto-resume, plugin messages (off by default) | |
  272. The title names the agent, the account and where it works: *Claude Code · work · api/fix-auth*.
  273. The agent's own text (your prompt, its reply) is never shown unless `notify.preview = true`.
  274. `input` and `failed` play a sound; nothing is shown while the session's tmux pane is in view, and
  275. `done` is left out while its terminal is the frontmost app (macOS). One session gets at most one
  276. notification every 30 seconds (except `input`), a newer one replaces the older, and an idle prompt
  277. right after *Done* is not repeated.
  278. ```sh
  279. srn notify status # settings, the notifier in use and why, the last notifications
  280. srn notify test [input|failed|done]
  281. srn config set notify.quiet_hours 22:00-08:00
  282. srn config set notify.enabled false
  283. ```
  284. | OS | Notifier |
  285. |---|---|
  286. | macOS | [`terminal-notifier`](https://github.com/julienXX/terminal-notifier) when installed (`brew install terminal-notifier`: grouped per session, click brings the terminal forward), else `osascript` (shown as Script Editor, which needs notification permission in System Settings) |
  287. | Linux | `notify-send` (libnotify), else `gdbus`; `input` is urgent and stays until dismissed |
  288. | Windows | a toast through Windows PowerShell 5.1, under the app id `Squadrn` registered by `self-install` |
  289. Terminals that show notifications themselves get them from the agent instead of the desktop:
  290. iTerm2 and WezTerm (OSC 9), Ghostty and Warp (OSC 777), kitty (OSC 99), for `input` and `failed`
  291. outside tmux. In tmux, each agent's pane records its state (`working`, `input`, `failed`, `done`;
  292. a grid's pane border shows it), the bell rings for `input` and `failed`, `srn ps` lists the state
  293. and `srn next` jumps to the first pane that needs input, else the first that failed. With
  294. `terminal-notifier`, a click on a notification switches tmux to the session's pane and brings its
  295. terminal forward. `notify.method` picks one channel: `terminal`, `desktop`, `tmux` (default `auto`).
  296. Do Not Disturb and Focus modes apply as for any app. While squadrn's notifications are on, account
  297. profiles turn Claude Code's own off (`preferredNotifChannel: "notifications_disabled"`), so you do
  298. not get both; your own value in an account's `settings.json` wins.
  299. Codex accounts get the same notifications: approvals from a `PermissionRequest` hook, finished
  300. turns from the `Stop` hook and Codex's `notify` program, the agent's state from its prompt and tool
  301. hooks. `srn account add codex/<name>` installs and trusts these hooks like the push guard and sets
  302. `notify` and `[tui] notifications = false` in the account's `config.toml` (your own values win). Deliveries are logged (titles,
  303. never agent text) in `~/.local/state/squadrn/notify.log`.
  304. ## Git push guard
  305. The guard is a safety net against agents' mistakes, not a sandbox: it does not contain a hostile
  306. process. Three layers keep agents from force-pushing or pushing to protected branches:
  307. 1. **Pre-tool hook.** The squadrn plugin (Claude Code), or a `PreToolUse` hook in
  308. `$CODEX_HOME/hooks.json` that squadrn installs and marks trusted (Codex), runs
  309. `squadrn hook guard-git` before every shell command an agent runs. It parses the command as shell — pipelines, `$(…)`, `bash -c`, `eval`, here-documents
  310. and here-strings, `sudo`/`env`/`timeout`/`script`/`watch`/`find -exec` wrappers, `cd`, `git -C`,
  311. quoting tricks (`pu''sh`), case (`GIT PUSH`), git's option prefixes (`--forc`), `-c alias.*` and
  312. repository aliases — and resolves a bare `git push` the way git does (`push.default`,
  313. `remote.*.push`, upstream). It **denies** force pushes, `--all`/`--mirror`/`--prune`,
  314. `--no-verify`, pushes or deletions targeting a protected branch, `gh api` writes to branch refs
  315. or protection, `gh pr merge --admin`, and agents changing the guard's own policy
  316. (`srn config set protected_branches|git_hooks`, writes to its config file or git hooks);
  317. **asks** when the target is only known at runtime (`$BRANCH`, `xargs`, `python -c …`, a shell
  318. reading stdin), for git aliases or subcommands it cannot see, settings or `GIT_*` variables that
  319. make git run a program or use another repository, and other GitHub writes; **allows** the
  320. rest. Any failure or timeout asks, never allows. Codex hooks cannot ask (Codex lets the
  321. command run), so for Codex accounts the guard denies instead and tells you to run the command
  322. yourself. On Windows Codex starts `squadrn.exe` through `cmd.exe` and lets the command run
  323. when the hook cannot start or fails, so there layer 1 fails open for Codex (`doctor` says so);
  324. layers 2 and 3 still hold.
  325. 2. **git pre-push hook.** Sessions squadrn starts (`srn`, `wt`, `grid`, `swap`) get
  326. `core.hooksPath` pointed at `~/.local/share/squadrn/git-hooks` through `GIT_CONFIG_*`. Git's
  327. pre-push hook sees the exact refs, so pushes layer 1 cannot see (scripts, interpreters) are
  328. checked too, including non-fast-forward updates. The repository's own hooks (husky, lefthook,
  329. pre-commit) still run after the check. The hook reads the protected list from the config file
  330. fixed at install, not from the pushing process's environment. Turn it off with
  331. `srn config set git_hooks false` (in your own terminal: agents are not allowed to).
  332. 3. **The server.** Only branch protection on the remote stops pushes made outside squadrn.
  333. `srn doctor` checks it for the current GitHub repository (classic protection or a ruleset
  334. that blocks force pushes and deletion).
  335. Protected branches default to `main master develop release/*`; set your own list with
  336. `srn config set protected_branches …`. A repository can add branches — never remove them:
  337. ```sh
  338. git config squadrn.protectedBranches "production staging"
  339. ```
  340. Known limit: layer 1 denies `--no-verify`, but when it cannot see the command (a script or an
  341. interpreter runs git), git's `--no-verify` skips layer 2's pre-push hook. Branch protection on
  342. the server is the real backstop; turn it on for every branch that matters.
  343. Decisions other than allow are logged to `~/.local/state/squadrn/guard.log` (`0600`, credentials
  344. masked) with the layer that made them. `srn doctor` also suggests `permissions.deny` rules so
  345. agents cannot edit squadrn's own files with their file tools (`Edit(…)` rules, which cover every
  346. file-editing tool).
  347. ## Configuration
  348. `~/.config/squadrn/config.toml` (unknown keys and invalid values are errors):
  349. ```toml
  350. schema = 1
  351. command = "ai" # set at install; change with: config set command
  352. aliases = ["srn"]
  353. default_provider = "claude"
  354. shared_mcp = ["codegraph"] # MCP servers copied from main into new accounts
  355. protected_branches = ["main", "release/*"] # repositories can only add to this list
  356. git_hooks = true # layer 2 of the push guard
  357. update_check = true # daily background check, notice only
  358. update_channel = "stable" # or "beta" for pre-releases
  359. [notify]
  360. enabled = true
  361. events = ["input", "failed", "done"] # and "info"
  362. sound = "input" # input (input and failed) | all | none
  363. when = "unfocused" # or "always"
  364. quiet_hours = "" # e.g. "22:00-08:00"
  365. preview = false # show the agent's text
  366. method = "auto" # auto | desktop | off
  367. ```
  368. `srn config [--json]` shows every setting; `srn config get|set <key> [value]` reads or
  369. changes one. In JSON, lists (`aliases`, `shared_mcp`, `protected_branches`) are arrays and
  370. `git_hooks`/`update_check` are booleans. Notification settings are `notify.<key>`
  371. (`srn config set notify.sound none`).
  372. MCP servers whose config has a non-empty `env` or `headers` are never copied; add those per account.
  373. | Path | Contents |
  374. |---|---|
  375. | `~/.local/share/squadrn/` | binary, plugin, local plugin marketplace, `git-hooks/`, `previous/` (rollback) |
  376. | `~/.local/state/squadrn/` | guard log, usage records, notification state and log |
  377. | `~/.cache/squadrn/` | login status cache, update check |
  378. ## Exit codes
  379. `0` ok · `1` error, or "no" at a confirmation · `2` usage or invalid input · `130` cancelled
  380. (ctrl-c, esc) · running the agent (`srn [<account>]`, `wt`, `swap`) passes the agent's exit
  381. status through, as `deps` does the package manager's. Commands with `--json` print
  382. machine-readable output on stdout, with snake_case keys: `grid ls --json` gives
  383. `[{"name", "repo", "panes", "attached"}]`, `ps --json` gives
  384. `[{"id", "session", "account", "name", "command"}]`.
  385. ## Development
  386. ```sh
  387. make build # bin/squadrn
  388. make check # lint, race tests, coverage gates, plugin validation
  389. make vuln # govulncheck
  390. ```
  391. Architecture: [docs/architecture.md](docs/architecture.md) · decisions: [docs/adr](docs/adr) ·
  392. [CHANGELOG](CHANGELOG.md). Actions are pinned by commit.
  393. ## License
  394. [Apache License 2.0](LICENSE); see [NOTICE](NOTICE). Contributions: [CONTRIBUTING.md](CONTRIBUTING.md);
  395. security reports: [SECURITY.md](SECURITY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.