@clipboard-health/groundcrew 4.48.3 → 4.48.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +17 -6
- package/clearance-allow-hosts +4 -0
- package/crew.config.example.ts +8 -4
- package/dist/commands/doctor.d.ts.map +1 -1
- package/dist/commands/doctor.js +2 -1
- package/dist/commands/init.d.ts +1 -1
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +3 -3
- package/dist/lib/config.d.ts +4 -3
- package/dist/lib/config.d.ts.map +1 -1
- package/dist/lib/config.js +10 -0
- package/docs/commands.md +1 -1
- package/docs/configuration.md +9 -6
- package/docs/credentials.md +24 -0
- package/docs/runners.md +29 -0
- package/docs/spec/v2-design.md +1 -1
- package/docs/troubleshooting.md +3 -1
- package/package.json +12 -12
package/README.md
CHANGED
|
@@ -22,11 +22,11 @@ Groundcrew watches assigned tasks, creates isolated worktrees, launches agent CL
|
|
|
22
22
|
## Why
|
|
23
23
|
|
|
24
24
|
- **Local.** Agents run on your machine with your tools, shell, and credentials. That makes them more steerable than remote agents, and easy to nudge when they drift.
|
|
25
|
-
- **Interactive.** Each task launches the real `claude`, `codex`,
|
|
25
|
+
- **Interactive.** Each task launches the real `claude`, `codex`, `cursor-agent`, or `pi` CLI in its own terminal pane, not a wrapper that approximates it. Watch any session live and take over when you need to.
|
|
26
26
|
- **One worktree per task.** Agents work in parallel without stepping on each other.
|
|
27
27
|
- **Sandboxed by default.** Safehouse or Docker Sandboxes isolate each agent on the host; `none` is an explicit escape hatch.
|
|
28
28
|
- **Pluggable task sources.** Linear by default; Jira and local files via [task sources](./docs/task-sources.md).
|
|
29
|
-
- **Multi-agent routing.** Ships `claude`, `codex`,
|
|
29
|
+
- **Multi-agent routing.** Ships `claude`, `codex`, `cursor` (plus a `cursor-grok` variant), and `pi` presets; bring your own CLI in config.
|
|
30
30
|
|
|
31
31
|
## Prerequisites
|
|
32
32
|
|
|
@@ -35,7 +35,7 @@ Groundcrew watches assigned tasks, creates isolated worktrees, launches agent CL
|
|
|
35
35
|
- **Node >= 24:** [nvm](https://github.com/nvm-sh/nvm): `nvm install 24`.
|
|
36
36
|
- **git:** e.g., `brew install git`, `apt install git`.
|
|
37
37
|
- **A terminal multiplexer:** [tmux](https://github.com/tmux/tmux/wiki/Installing) (cross-platform), [cmux](https://cmux.com/) (macOS), or [zellij](https://zellij.dev/).
|
|
38
|
-
- **An agent CLI:** [Claude Code](https://code.claude.com/docs/en/quickstart), [Codex](https://developers.openai.com/codex/quickstart?setup=cli),
|
|
38
|
+
- **An agent CLI:** [Claude Code](https://code.claude.com/docs/en/quickstart), [Codex](https://developers.openai.com/codex/quickstart?setup=cli), the [Cursor CLI](https://docs.cursor.com/en/cli/overview) (`cursor-agent`, for the `cursor` and `cursor-grok` presets), and/or [Pi](https://pi.dev/).
|
|
39
39
|
- **A sandbox runner:** [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) (cross-platform) or [Safehouse](https://agent-safehouse.dev/) on macOS. Skip only with `--runner none`.
|
|
40
40
|
|
|
41
41
|
## Quickstart
|
|
@@ -61,7 +61,18 @@ crew doctor
|
|
|
61
61
|
crew run --watch
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
-
`crew init --global` writes config to `${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/`. Pass `--repo` more than once for multiple repos. `--agent claude`, `--agent codex`, or `--agent
|
|
64
|
+
`crew init --global` writes config to `${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/`. Pass `--repo` more than once for multiple repos. `--agent claude`, `--agent codex`, `--agent cursor`, or `--agent pi` chooses the single built-in agent preset to enable in the generated config.
|
|
65
|
+
|
|
66
|
+
Pi needs credentials only for the provider its selected model uses—not every provider. Authenticate that provider before unattended use; see [Pi provider authentication](./docs/credentials.md#pi-provider-authentication).
|
|
67
|
+
|
|
68
|
+
When using Pi through tmux 3.5 or later, add the following to `~/.tmux.conf` so tmux preserves modified keys such as `Shift+Enter` and `Ctrl+Enter`:
|
|
69
|
+
|
|
70
|
+
```tmux
|
|
71
|
+
set -g extended-keys on
|
|
72
|
+
set -g extended-keys-format csi-u
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Stop or finish every active Groundcrew task and save work in every other tmux session before running `tmux kill-server`; it terminates the entire shared tmux server, including unrelated user sessions. The change takes effect the next time tmux starts. These are server-wide options, so Groundcrew deliberately does not change them for you. With tmux 3.2–3.4, omit `extended-keys-format`; see [Pi's tmux setup](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/tmux.md).
|
|
65
76
|
|
|
66
77
|
## Task Pickup
|
|
67
78
|
|
|
@@ -69,7 +80,7 @@ crew run --watch
|
|
|
69
80
|
|
|
70
81
|
Linear works out of the box: assign tasks to yourself and add an `agent-*` label.
|
|
71
82
|
|
|
72
|
-
- `agent-claude`, `agent-codex`, or `agent-<name>` routes to that enabled launch profile.
|
|
83
|
+
- `agent-claude`, `agent-codex`, `agent-pi`, or `agent-<name>` routes to that enabled launch profile.
|
|
73
84
|
- `agent-any` routes to the enabled agent with the most session headroom, after skipping agents over their session limit or weekly paced budget.
|
|
74
85
|
- Tasks without an `agent-*` label are ignored by `crew run`; dispatch one manually with `crew start <TASK>`.
|
|
75
86
|
|
|
@@ -93,7 +104,7 @@ Write tasks as complete agent instructions: the goal, the context and constraint
|
|
|
93
104
|
```bash
|
|
94
105
|
crew init [--global | --local] [--force] [--dry-run] # create a crew.config.ts
|
|
95
106
|
[--project-dir <dir>] [--repo <repo>]...
|
|
96
|
-
[--runner <auto|safehouse|sdx|none>] [--agent <claude|codex|cursor>]
|
|
107
|
+
[--runner <auto|safehouse|sdx|none>] [--agent <claude|codex|cursor|pi>]
|
|
97
108
|
crew doctor # check setup
|
|
98
109
|
crew source list|verify [<source>] # inspect configured task sources
|
|
99
110
|
crew task list [--source <name>] # list tasks across sources
|
package/clearance-allow-hosts
CHANGED
|
@@ -11,10 +11,14 @@
|
|
|
11
11
|
ab.chatgpt.com
|
|
12
12
|
api.anthropic.com
|
|
13
13
|
api.openai.com
|
|
14
|
+
auth.openai.com
|
|
14
15
|
chatgpt.com
|
|
16
|
+
claude.ai
|
|
17
|
+
console.anthropic.com
|
|
15
18
|
docs.anthropic.com
|
|
16
19
|
docs.claude.com
|
|
17
20
|
downloads.claude.ai
|
|
21
|
+
pi.dev
|
|
18
22
|
platform.claude.com
|
|
19
23
|
|
|
20
24
|
# Cursor (cursor-agent: composer, grok models). Wildcard covers the numbered API hosts
|
package/crew.config.example.ts
CHANGED
|
@@ -64,8 +64,10 @@ export default {
|
|
|
64
64
|
default: "claude",
|
|
65
65
|
// `definitions` is the enabled launch profile set. Built-in keys can use
|
|
66
66
|
// `{}` to opt into the shipped command/color/usage preset. Add
|
|
67
|
-
// `codex: {}`, `cursor: {}`,
|
|
68
|
-
// agents (`cursor` runs Cursor's composer-2.5, `cursor-grok` runs
|
|
67
|
+
// `codex: {}`, `cursor: {}`, `"cursor-grok": {}`, or `pi: {}` for the other
|
|
68
|
+
// shipped agents (`cursor` runs Cursor's composer-2.5, `cursor-grok` runs
|
|
69
|
+
// grok-4.5). Pi authenticates only the selected model's provider; see
|
|
70
|
+
// docs/credentials.md#pi-provider-authentication.
|
|
69
71
|
// Agent names are launch profiles: add custom entries such as `claude-fable`
|
|
70
72
|
// or `claude-opus` to pin a model per task, then tag tasks with `agent-<name>`.
|
|
71
73
|
definitions: {
|
|
@@ -73,6 +75,7 @@ export default {
|
|
|
73
75
|
// codex: {},
|
|
74
76
|
// cursor: {},
|
|
75
77
|
// "cursor-grok": {},
|
|
78
|
+
// pi: {},
|
|
76
79
|
// "claude-fable": {
|
|
77
80
|
// cmd: "claude --model claude-fable-5 --permission-mode auto",
|
|
78
81
|
// color: "#C15F3C",
|
|
@@ -162,8 +165,9 @@ export default {
|
|
|
162
165
|
// sandbox: { agent: "claude" },
|
|
163
166
|
// // Args appended on `crew resume` so the agent reopens its previous
|
|
164
167
|
// // conversation in the worktree (`crew resume --new` starts fresh). The
|
|
165
|
-
// // built-in claude/codex presets default this ("--continue" /
|
|
166
|
-
// // --last"); set it for custom agents or to
|
|
168
|
+
// // built-in claude/codex/pi presets default this ("--continue" /
|
|
169
|
+
// // "resume --last" / "--continue"); set it for custom agents or to
|
|
170
|
+
// // override the preset default.
|
|
167
171
|
// resumeArgs: "--continue",
|
|
168
172
|
// },
|
|
169
173
|
//
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;
|
|
1
|
+
{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2SH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAyF/C"}
|
package/dist/commands/doctor.js
CHANGED
|
@@ -15,7 +15,7 @@ import { resolveWorkspaceKind } from "../lib/workspaces.js";
|
|
|
15
15
|
// Tokenization stops after this many non-flag tokens. Two is enough to
|
|
16
16
|
// catch wrapper + wrapped CLI commands like `safehouse claude --foo`.
|
|
17
17
|
const MAX_TOKENS_PER_CMD = 2;
|
|
18
|
-
const BUILT_IN_AGENT_NAMES = ["claude", "codex", "cursor", "cursor-grok"];
|
|
18
|
+
const BUILT_IN_AGENT_NAMES = ["claude", "codex", "cursor", "cursor-grok", "pi"];
|
|
19
19
|
// Primary CLI binary probed on PATH for each built-in agent. Usually equal to
|
|
20
20
|
// the agent name, but the cursor and cursor-grok presets both launch Cursor's
|
|
21
21
|
// `cursor-agent`, so the missing-CLI hint must key on the binary, not the name.
|
|
@@ -24,6 +24,7 @@ const BUILT_IN_AGENT_BINARIES = {
|
|
|
24
24
|
codex: "codex",
|
|
25
25
|
cursor: "cursor-agent",
|
|
26
26
|
"cursor-grok": "cursor-agent",
|
|
27
|
+
pi: "pi",
|
|
27
28
|
};
|
|
28
29
|
const CONFIG_SOURCE_LABELS = {
|
|
29
30
|
env: "GROUNDCREW_CONFIG",
|
package/dist/commands/init.d.ts
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* `cp` dance documented in the README.
|
|
6
6
|
*/
|
|
7
7
|
import { type LocalRunnerSetting } from "../lib/config.ts";
|
|
8
|
-
export declare const INIT_AGENTS: readonly ["claude", "codex", "cursor"];
|
|
8
|
+
export declare const INIT_AGENTS: readonly ["claude", "codex", "cursor", "pi"];
|
|
9
9
|
type InitConfigScope = "global" | "local";
|
|
10
10
|
type InitAgent = (typeof INIT_AGENTS)[number];
|
|
11
11
|
interface InitConfigOptions {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAYlF,eAAO,MAAM,WAAW,YAAI,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;
|
|
1
|
+
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAYlF,eAAO,MAAM,WAAW,YAAI,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAU,CAAC;AAExE,KAAK,eAAe,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC1C,KAAK,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,UAAU,iBAAiB;IACzB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,qDAAqD;IACrD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,KAAK,iBAAiB,GAAG,qBAAqB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpE,UAAU,gBAAgB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAoB5E;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAWjE"}
|
package/dist/commands/init.js
CHANGED
|
@@ -13,10 +13,10 @@ import { xdgConfigPath } from "../lib/xdg.js";
|
|
|
13
13
|
const CONFIG_FILE_NAME = "crew.config.ts";
|
|
14
14
|
const EXAMPLE_FILE_NAME = "crew.config.example.ts";
|
|
15
15
|
const DEFAULT_EXAMPLE_PROJECT_DIR = "~/dev/groundcrew";
|
|
16
|
-
const INIT_USAGE = "Usage: crew init [--global | --local] [--force] [--dry-run] [--project-dir <dir>] [--repo <owner/repo>]... [--runner <auto|safehouse|sdx|none>] [--agent <claude|codex|cursor>]";
|
|
16
|
+
const INIT_USAGE = "Usage: crew init [--global | --local] [--force] [--dry-run] [--project-dir <dir>] [--repo <owner/repo>]... [--runner <auto|safehouse|sdx|none>] [--agent <claude|codex|cursor|pi>]";
|
|
17
17
|
// Model-variant presets with hyphens (e.g. `cursor-grok`) are enabled via
|
|
18
18
|
// config, not `init`: renderConfig would emit an unquoted, invalid TS key.
|
|
19
|
-
export const INIT_AGENTS = ["claude", "codex", "cursor"];
|
|
19
|
+
export const INIT_AGENTS = ["claude", "codex", "cursor", "pi"];
|
|
20
20
|
export function initConfig(options = {}) {
|
|
21
21
|
const scope = options.scope ?? "local";
|
|
22
22
|
const cwd = options.cwd ?? process.cwd();
|
|
@@ -149,7 +149,7 @@ function isLocalRunnerSetting(value) {
|
|
|
149
149
|
return value === "auto" || value === "safehouse" || value === "sdx" || value === "none";
|
|
150
150
|
}
|
|
151
151
|
function isInitAgent(value) {
|
|
152
|
-
return value === "claude" || value === "codex" || value === "cursor";
|
|
152
|
+
return value === "claude" || value === "codex" || value === "cursor" || value === "pi";
|
|
153
153
|
}
|
|
154
154
|
function tsString(value) {
|
|
155
155
|
return JSON.stringify(value);
|
package/dist/lib/config.d.ts
CHANGED
|
@@ -140,8 +140,9 @@ export interface AgentDefinition {
|
|
|
140
140
|
resumeArgs?: string;
|
|
141
141
|
}
|
|
142
142
|
/**
|
|
143
|
-
* User-facing agent entry shape. Built-in agent names (`claude`, `codex
|
|
144
|
-
* accept empty or partial entries because they
|
|
143
|
+
* User-facing agent entry shape. Built-in agent names (`claude`, `codex`,
|
|
144
|
+
* `cursor`, `cursor-grok`, `pi`) accept empty or partial entries because they
|
|
145
|
+
* merge over built-in presets.
|
|
145
146
|
* Brand-new agent names must supply enough fields to satisfy `validate()`.
|
|
146
147
|
*
|
|
147
148
|
* `usage` accepts an extra `{ disabled: true }` sentinel that strips the
|
|
@@ -277,7 +278,7 @@ export interface Config {
|
|
|
277
278
|
default?: string;
|
|
278
279
|
/**
|
|
279
280
|
* Explicit enabled agent set. Built-in keys (`claude`, `codex`, `cursor`,
|
|
280
|
-
* `cursor-grok`) merge over their presets, so `{ claude: {} }` enables
|
|
281
|
+
* `cursor-grok`, `pi`) merge over their presets, so `{ claude: {} }` enables
|
|
281
282
|
* Claude with the shipped command/color/usage. Brand-new agent names must
|
|
282
283
|
* supply enough fields to satisfy `validate()`.
|
|
283
284
|
*/
|
package/dist/lib/config.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAO1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACpB,mBAAmB,GACnB,kBAAkB,GAClB,oBAAoB,GACpB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,QAAQ,CAAC;AAE/B;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvE,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAKzD,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,KAAK,GAAG,MAAM,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,MAAM,CAAC;AAEtD,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAKrD,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,MAAM,CAAC;AAE1D,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAGzD,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QACN,QAAQ,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACjD,CAAC;IACF;;;;OAIG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}
|
package/dist/lib/config.js
CHANGED
|
@@ -125,6 +125,16 @@ const BUILT_IN_AGENT_DEFINITIONS = {
|
|
|
125
125
|
// No `usage`: cursor-agent has no codexbar provider.
|
|
126
126
|
resumeArgs: "--continue",
|
|
127
127
|
},
|
|
128
|
+
pi: {
|
|
129
|
+
// Groundcrew worktrees are unattended. Pi's project trust prompt would
|
|
130
|
+
// otherwise stop the initial positional prompt before the agent can act.
|
|
131
|
+
// `--approve` trusts project-local Pi resources for this launch; the
|
|
132
|
+
// groundcrew runner remains the filesystem/network security boundary.
|
|
133
|
+
cmd: "pi --approve",
|
|
134
|
+
color: "#6B7280",
|
|
135
|
+
// Pi stores sessions by working directory, matching the one-worktree-per-task model.
|
|
136
|
+
resumeArgs: "--continue",
|
|
137
|
+
},
|
|
128
138
|
};
|
|
129
139
|
const MODEL_DEFINITIONS_MIGRATION_MESSAGE = [
|
|
130
140
|
"configuration migration required: agents are no longer enabled by default.",
|
package/docs/commands.md
CHANGED
|
@@ -147,7 +147,7 @@ The command closes the cmux/tmux/zellij workspace if present, records local run
|
|
|
147
147
|
|
|
148
148
|
The resume prompt tells the agent to inspect git status and diff before editing, includes the previous interrupt reason when recorded, and reuses the recorded agent, repository, branch, runner, sandbox, and workspace backend. When no run-state file exists but a worktree does, resume falls back to Linear resolution for the agent and task context.
|
|
149
149
|
|
|
150
|
-
`crew resume <TASK>` reopens the agent's previous conversation in the worktree by default — the built-in `claude`, `codex`, `cursor`,
|
|
150
|
+
`crew resume <TASK>` reopens the agent's previous conversation in the worktree by default — the built-in `claude`, `codex`, `cursor`, `cursor-grok`, and `pi` presets ship a [`resumeArgs`](./configuration.md#resuming-the-agents-conversation) default (`--continue`, `resume --last`, `--continue`, `--continue`, `--continue`) that groundcrew appends to the agent's command. `crew resume --new <TASK>` ignores `resumeArgs` and forces a fresh conversation. Custom agents cold-start unless they set `resumeArgs`. groundcrew stores no session id — it relies on one conversation per worktree.
|
|
151
151
|
|
|
152
152
|
## Open
|
|
153
153
|
|
package/docs/configuration.md
CHANGED
|
@@ -94,7 +94,7 @@ The "Loaded config from ..." line at startup tells you which config won.
|
|
|
94
94
|
|
|
95
95
|
## Agent Label Routing
|
|
96
96
|
|
|
97
|
-
- `agent-claude`, `agent-codex`, `agent-<name>` routes to that enabled launch profile.
|
|
97
|
+
- `agent-claude`, `agent-codex`, `agent-pi`, or `agent-<name>` routes to that enabled launch profile.
|
|
98
98
|
- `agent-any` routes to the agent with the most session headroom, after skipping agents over their session limit or weekly paced budget.
|
|
99
99
|
- Unknown `agent-<name>` falls back to `agents.default`.
|
|
100
100
|
- A built-in `agent-<name>` label whose agent is not enabled falls back to `agents.default` with a warning.
|
|
@@ -167,7 +167,7 @@ export default {
|
|
|
167
167
|
|
|
168
168
|
## Enabling Agent Presets
|
|
169
169
|
|
|
170
|
-
Groundcrew ships built-in presets for `claude`, `codex`, `cursor` (Cursor's composer-2.5),
|
|
170
|
+
Groundcrew ships built-in presets for `claude`, `codex`, `cursor` (Cursor's composer-2.5), `cursor-grok` (grok-4.5), and `pi`, but agents are not enabled by default. List the agents you want in `agents.definitions`:
|
|
171
171
|
|
|
172
172
|
```ts
|
|
173
173
|
export default {
|
|
@@ -180,7 +180,7 @@ export default {
|
|
|
180
180
|
};
|
|
181
181
|
```
|
|
182
182
|
|
|
183
|
-
To
|
|
183
|
+
To enable several shipped presets:
|
|
184
184
|
|
|
185
185
|
```ts
|
|
186
186
|
export default {
|
|
@@ -189,6 +189,7 @@ export default {
|
|
|
189
189
|
definitions: {
|
|
190
190
|
claude: {},
|
|
191
191
|
codex: {},
|
|
192
|
+
pi: {},
|
|
192
193
|
},
|
|
193
194
|
},
|
|
194
195
|
};
|
|
@@ -198,13 +199,15 @@ Rules:
|
|
|
198
199
|
|
|
199
200
|
- `agents.definitions` is the enabled launch profile set; `crew doctor` only probes listed profiles.
|
|
200
201
|
- Built-in entries can be `{}` or partial overrides such as `{ cmd: "..." }`.
|
|
202
|
+
- The Pi preset runs `pi --approve`, which prevents project trust from blocking an unattended launch. If you override its `cmd`, retain either `--approve` (load project-local Pi resources) or `--no-approve` (ignore them).
|
|
203
|
+
- Pi needs authentication only for the selected model's provider, not every supported provider. Authenticate before unattended use as described in [Pi Provider Authentication](./credentials.md#pi-provider-authentication).
|
|
201
204
|
- Custom launch profile names must provide `cmd` and `color`.
|
|
202
205
|
- `agents.default` must point at an enabled agent.
|
|
203
206
|
- Legacy agent entries like `codex: { disabled: true }` are rejected with migration guidance; remove unwanted entries instead.
|
|
204
207
|
|
|
205
208
|
## Resuming the agent's conversation
|
|
206
209
|
|
|
207
|
-
`crew resume` reopens the agent's previous conversation in the worktree — **no config required** for the built-in agents. The shipped `claude`, `codex`, `cursor`,
|
|
210
|
+
`crew resume` reopens the agent's previous conversation in the worktree — **no config required** for the built-in agents. The shipped `claude`, `codex`, `cursor`, `cursor-grok`, and `pi` presets carry a `resumeArgs` default (`--continue`, `resume --last`, `--continue`, `--continue`, `--continue`), which groundcrew appends to the agent's command on resume.
|
|
208
211
|
|
|
209
212
|
How it works:
|
|
210
213
|
|
|
@@ -328,14 +331,14 @@ and hook contract.
|
|
|
328
331
|
| `orchestrator.pollIntervalMilliseconds` | `120_000` | Poll interval in `--watch` mode. |
|
|
329
332
|
| `orchestrator.sessionLimitPercentage` | `85` | Number in `(0, 100]`. An agent whose codexbar session window exceeds this percentage is skipped that tick. Agents are also skipped when codexbar reports weekly usage over the current weekly paced budget. |
|
|
330
333
|
| `agents.default` | `"claude"` | Tiebreak for `agent-any` resolution and fallback for explicit but unknown `agent-*` labels. Also used by `crew start <TASK>` for unlabeled tasks. `crew run` ignores unlabeled tasks and does not apply this default. Must exist in `agents.definitions`. If you enable only `codex`, set `default: "codex"`. |
|
|
331
|
-
| `agents.definitions` | **required** | Enabled launch profile set. Built-in keys (`claude`, `codex`, `cursor`, `cursor-grok`) can use `{}` to opt into the shipped preset. Custom profile names must provide `cmd` and `color`; use custom profiles such as `claude-fable` and `claude-opus` to select model-specific commands per task.
|
|
334
|
+
| `agents.definitions` | **required** | Enabled launch profile set. Built-in keys (`claude`, `codex`, `cursor`, `cursor-grok`, `pi`) can use `{}` to opt into the shipped preset. Custom profile names must provide `cmd` and `color`; use custom profiles such as `claude-fable` and `claude-opus` to select model-specific commands per task. |
|
|
332
335
|
| `agents.definitions.<name>.cmd` | preset for built-ins | Shell command launched for the agent. Required for custom profiles. Runs in the worktree through the resolved `local.runner`. `{{worktree}}` is replaced before launch; `{{sandbox}}` expands to the sbx sandbox name under the sdx runner and an empty string otherwise. |
|
|
333
336
|
| `agents.definitions.<name>.color` | preset for built-ins | Color for the workspace status pill (cmux only; tmux and zellij silently drop it). Required for custom profiles. |
|
|
334
337
|
| `agents.definitions.<name>.usage` | preset for built-ins | If set, codexbar usage is fetched for this agent and gated by `sessionLimitPercentage` plus the weekly paced budget when codexbar exposes a weekly window. When `usage.codexbar.source` is omitted, groundcrew uses `oauth` for Codex/Claude on macOS, `auto` for other macOS providers, and `cli` elsewhere. Set to `{ disabled: true }` to disable usage gating while keeping the agent enabled. |
|
|
335
338
|
| `agents.definitions.<name>.sandbox` | optional | Docker Sandboxes binding for the agent. Required at launch when `local.runner` resolves to `sdx`. Field: `agent` (required sbx agent name). Groundcrew assumes the `groundcrew-<agent>` sandbox already exists. |
|
|
336
339
|
| `agents.definitions.<name>.preLaunch` | optional | Host-only shell snippet run before the agent exec and outside Safehouse/sdx. Exports survive into the launch shell; under the default `safehouse` runner they are only forwarded to the agent when listed via `preLaunchEnv` or when `cmd` includes its own `safehouse --env-pass=NAMES`. `{{worktree}}` is substituted. A non-zero exit aborts launch. Not supported when `local.runner` resolves to `sdx` in v1. |
|
|
337
340
|
| `agents.definitions.<name>.preLaunchEnv` | optional | Companion to `preLaunch`: list of env var names to append to groundcrew's Safehouse `--env-pass=` flag, so `preLaunch` exports reach the agent without overriding `cmd`. Each entry must match `[A-Za-z_][A-Za-z0-9_]*`. Under `runner: "none"` exports already inherit and `preLaunchEnv` is a no-op. An empty array is a uniform no-op in every runner; a non-empty list is rejected when `cmd` already starts with `safehouse` or when `runner` resolves to `sdx`. |
|
|
338
|
-
| `agents.definitions.<name>.resumeArgs` | preset default | Shell args appended to `cmd` on `crew resume` so the agent [reopens its previous conversation](#resuming-the-agents-conversation) in the worktree. Defaults to `"--continue"` (claude, cursor, cursor-grok) and `"resume --last"` (codex) on the built-in presets; set it for custom agents or to override. `crew resume --new` ignores it and cold-starts. No session id is stored.
|
|
341
|
+
| `agents.definitions.<name>.resumeArgs` | preset default | Shell args appended to `cmd` on `crew resume` so the agent [reopens its previous conversation](#resuming-the-agents-conversation) in the worktree. Defaults to `"--continue"` (claude, cursor, cursor-grok, pi) and `"resume --last"` (codex) on the built-in presets; set it for custom agents or to override. `crew resume --new` ignores it and cold-starts. No session id is stored. |
|
|
339
342
|
| `prompts.initial` | unattended template | First message sent to the agent: the execution wrapper around each task. The task description is the task-specific prompt. Placeholders: `{{task}}`, `{{worktree}}`, `{{title}}`, `{{description}}`. Override only to change the execution contract for every task, such as team-wide review rules or tool conventions. Mutually exclusive with `prompts.promptFile`. |
|
|
340
343
|
| `prompts.promptFile` | optional | Path to a UTF-8 file whose contents become `prompts.initial`, read at load time. Resolved relative to the config file's directory; `~` is expanded and absolute paths are used as-is. The JSON-friendly alternative to inlining a large prompt or `readFileSync`. Mutually exclusive with `prompts.initial`. |
|
|
341
344
|
| `workspaceKind` | `"auto"` | Terminal session manager. `"auto"` picks `cmux` when on PATH, else `tmux`. Set to `"cmux"`, `"tmux"`, or `"zellij"` to fail loudly when the chosen backend is missing. |
|
package/docs/credentials.md
CHANGED
|
@@ -16,6 +16,30 @@ echo "GROUNDCREW_LINEAR_API_KEY='op://<vault>/LINEAR_API_KEY/credential'" > .env
|
|
|
16
16
|
op run --env-file .env.1password -- crew doctor
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
+
## Pi Provider Authentication
|
|
20
|
+
|
|
21
|
+
Pi does **not** require authentication with every provider it supports. It only needs credentials for the provider used by the selected model. The built-in Groundcrew preset does not force a provider or model, so Pi uses the defaults from its own settings.
|
|
22
|
+
|
|
23
|
+
Authenticate the provider before the first unattended launch:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pi
|
|
27
|
+
# In Pi: /login, select and authenticate the provider Groundcrew tasks will use,
|
|
28
|
+
# then /quit.
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
By default, Pi stores provider API keys and subscription tokens in `~/.pi/agent/auth.json`; `PI_CODING_AGENT_DIR` changes that base directory. You can authenticate several providers for interactive model switching, but a fixed Pi launch profile only needs its configured provider. `crew doctor` verifies that the `pi` executable exists; it cannot verify provider credentials without making a model request.
|
|
32
|
+
|
|
33
|
+
If you use a Claude Pro/Max subscription, Pi's [provider documentation](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md#claude-promax) warns that third-party harness usage is billed as extra usage per token rather than against normal plan limits.
|
|
34
|
+
|
|
35
|
+
Credential handling depends on the runner:
|
|
36
|
+
|
|
37
|
+
- `none`: Pi uses the host's auth file. Ambient provider API-key environment variables are also inherited.
|
|
38
|
+
- `safehouse`: current Safehouse releases include a Pi profile that grants access to the default `~/.pi` directory. Authenticate on the host first and keep the default directory when using that profile. To pass an ambient provider API key instead, list its name in the Pi definition's `preLaunchEnv`; Safehouse otherwise sanitizes it. See [Pi on Safehouse](./runners.md#pi-on-safehouse) for nonstandard install prefixes.
|
|
39
|
+
- `sdx`: the contributed Pi kit's supported default keeps an Anthropic key on the host and injects it through Docker Sandboxes' credential proxy. After creating the sandbox, configure the credential specifically for it with `sbx secret set groundcrew-pi anthropic`. Host Pi auth files are not copied into the sandbox. Other providers require corresponding sandbox network and credential policy; see [Docker Sandboxes Setup](./runners.md#docker-sandboxes-setup).
|
|
40
|
+
|
|
41
|
+
The built-in command is `pi --approve`. Here `--approve` resolves Pi's **project trust** prompt so an unattended task can load project-local Pi resources; it does not authenticate an AI provider and does not bypass Groundcrew's Safehouse or Docker Sandbox boundary.
|
|
42
|
+
|
|
19
43
|
## Build-Time Secrets
|
|
20
44
|
|
|
21
45
|
Groundcrew forwards a small allowlist of build-time secrets from your shell into the `prepareWorktree` phase so package installs can authenticate against private registries. The agent process never inherits these values.
|
package/docs/runners.md
CHANGED
|
@@ -52,6 +52,23 @@ Scope and limits:
|
|
|
52
52
|
- **Ignored by `sdx` / `none`.** The other runners ignore it, so you can leave `networkEgress` set while switching `local.runner`.
|
|
53
53
|
- **No additional effect when `cmd` already starts with `safehouse`:** that command owns its own wrap, so groundcrew injects nothing. Groundcrew-managed setup/resume launches still reject cmd-owned Safehouse wraps because worker self-completion env cannot be injected.
|
|
54
54
|
|
|
55
|
+
## Pi on Safehouse
|
|
56
|
+
|
|
57
|
+
Current Agent Safehouse releases ship a dedicated [`pi.sb` profile](https://github.com/eugene1g/agent-safehouse/blob/main/profiles/60-agents/pi.sb) that grants Pi's default `~/.pi` state while keeping the worktree boundary in Groundcrew's composed sandbox. Its bundled runtime grants cover system package roots, common Node version managers, and `~/.local` npm installs. If `command -v pi` resolves through another home-directory prefix such as `~/.npm-global`, add that prefix to `local.readOnlyDirs` so Safehouse can read both the launcher and package files:
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
local: {
|
|
61
|
+
runner: "safehouse",
|
|
62
|
+
readOnlyDirs: ["~/.config/tfenv", "~/.npm-global"],
|
|
63
|
+
},
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Update Safehouse if a Pi launch reports that its profile or `~/.pi/agent` is unavailable. The profile also assumes Pi's default state directory; a custom `PI_CODING_AGENT_DIR` needs corresponding Safehouse environment and writable-path grants.
|
|
67
|
+
|
|
68
|
+
Safehouse's Pi profile exposes the real `~/.pi` state read/write, so use it only with repositories whose project-local Pi resources you trust. Use Docker Sandboxes when unattended repository code must be isolated from the host's Pi settings, extensions, credentials, and session state.
|
|
69
|
+
|
|
70
|
+
Groundcrew's bundled Clearance allowlist covers Pi's startup service, Anthropic, OpenAI, and their subscription-authentication hosts. Pi supports many additional providers; add the selected provider's hosts with `CLEARANCE_ALLOW_HOSTS` / `CLEARANCE_ALLOW_HOSTS_FILES`, or explicitly choose `local.networkEgress: "open"`.
|
|
71
|
+
|
|
55
72
|
## Docker Sandboxes Setup
|
|
56
73
|
|
|
57
74
|
`sdx` does not support `unsandboxedHooks`. The sdx container has no
|
|
@@ -69,3 +86,15 @@ sbx exec -it groundcrew-claude gh auth login
|
|
|
69
86
|
```
|
|
70
87
|
|
|
71
88
|
Replace `claude` with the sbx agent name for your agent and `<projectDir>` with `workspace.projectDir` from `crew.config.ts`. Manage lifecycle and auth with `sbx` directly (`sbx ls`, `sbx exec`, `sbx rm`). Groundcrew does not create, authenticate, regenerate, list, or remove sandboxes.
|
|
89
|
+
|
|
90
|
+
Pi is available as a contributed Docker Sandbox agent kit. Its supported default routes Anthropic requests through Docker Sandboxes' [credential proxy](https://docs.docker.com/ai/sandboxes/security/credentials/), so the real key remains on the host. Create the exact sandbox name Groundcrew addresses, then scope that credential to this sandbox:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
sbx create --name groundcrew-pi \
|
|
94
|
+
--kit "git+https://github.com/docker/sbx-kits-contrib.git#ref=v0.12.0&dir=pi" \
|
|
95
|
+
pi <projectDir>
|
|
96
|
+
sbx secret set groundcrew-pi anthropic
|
|
97
|
+
sbx exec -it groundcrew-pi gh auth login
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The example pins the reviewed `v0.12.0` kit; review upstream changes before moving the `ref` to a newer release. Enable it in Groundcrew with `pi: { sandbox: { agent: "pi" } }`. The sandbox is persistent, so Pi's per-worktree sessions remain available to later `crew resume` launches. The contributed kit's default network and credential policy supports Anthropic; use a reviewed custom kit or policy before selecting another provider or storing its credentials inside the sandbox.
|
package/docs/spec/v2-design.md
CHANGED
|
@@ -136,7 +136,7 @@ In-session commands are ordinary subcommands (no separate namespace). **Task ide
|
|
|
136
136
|
### 7.2 Config — `crew.config.jsonc`
|
|
137
137
|
|
|
138
138
|
- **JSONC plus a published JSON Schema** (generated from zod, referenced via `$schema`). TS config dies: a global config can't resolve the package import for its types, so it was ceremony without safety. One filename, one location rule: `~/.config/groundcrew/`, or project-local.
|
|
139
|
-
- **Principle 1 — omitted = detected, specified = exactly yours, never merged.** `sources` omitted → `[{ "kind": "todo-txt" }]`; `agents` omitted → presets for CLIs on PATH (claude > codex > cursor); `presenter` omitted → first of cmux/tmux/zellij found. Listing anything replaces the detected set — disabling = not listing.
|
|
139
|
+
- **Principle 1 — omitted = detected, specified = exactly yours, never merged.** `sources` omitted → `[{ "kind": "todo-txt" }]`; `agents` omitted → presets for CLIs on PATH (claude > codex > cursor > pi); `presenter` omitted → first of cmux/tmux/zellij found. Listing anything replaces the detected set — disabling = not listing.
|
|
140
140
|
- **Principle 2 — no secrets, structurally.** No schema field accepts a token value; manifests declare secret _names_, resolved from the parent environment, a `secrets.env` (doctor warns unless 0600), or `op run`. `GROUNDCREW_LINEAR_API_KEY` dies; the linear bundle declares `LINEAR_API_KEY` like any source. Doctor flags credential-looking strings in config.
|
|
141
141
|
- Minimal legal config: `{ "workspace": { "baseDirectory": "~/dev" } }`. Worktrees default to `<baseDirectory>/.groundcrew/worktrees`. No abbreviations anywhere (`maximumInProgress`, `pollIntervalMilliseconds`, `sessionLimitPercentage`, `readOnlyDirectories`, `workingDirectory`).
|
|
142
142
|
- Agent profiles get first-class `model` / `effort` / `resume` fields; presets map them to CLI flags; `{{model}}` / `{{sessionId}}` placeholders for custom commands. Per-harness session-id capture mechanics are an implementation detail under this shape.
|
package/docs/troubleshooting.md
CHANGED
|
@@ -56,6 +56,8 @@ Groundcrew creates isolated per-task worktrees for unattended runs, so the shipp
|
|
|
56
56
|
|
|
57
57
|
Groundcrew provisions each worktree and records workspace trust for `claude`, `codex`, and `cursor-agent` before the agent starts (via [`agent-trust`](https://www.npmjs.com/package/agent-trust)), so unattended launches do not stall on first-run trust dialogs. There is no config toggle: if groundcrew created the worktree, trust is recorded in the agent's local store (`~/.claude.json` for Claude, `~/.codex/config.toml` for Codex, `~/.cursor/projects/<slug>/.workspace-trusted` for Cursor) for the worktree launch directory. Cursor markers use `trustMethod: "groundcrew-auto-trust"` for auditability. This applies only to groundcrew-provisioned worktrees at launch time; it does not trust arbitrary paths you open manually. Permission mode (`claude --permission-mode auto`) and Codex approval bypass (`--dangerously-bypass-approvals-and-sandbox`) are separate from workspace trust.
|
|
58
58
|
|
|
59
|
+
Pi's trust store is not supported by `agent-trust`, so its built-in preset passes `pi --approve` on every launch instead. This approves project-local Pi settings, packages, extensions, and skills for that process. If you override `agents.definitions.pi.cmd`, keep `--approve` for the same unattended behavior or use `--no-approve` to ignore protected project resources without prompting. Provider login is separate; see [Pi Provider Authentication](./credentials.md#pi-provider-authentication).
|
|
60
|
+
|
|
59
61
|
Inspect or clean trust entries with the published CLI:
|
|
60
62
|
|
|
61
63
|
```bash
|
|
@@ -82,4 +84,4 @@ Set `workspaceKind: "zellij"` to run agents as tabs in a shared `groundcrew` zel
|
|
|
82
84
|
|
|
83
85
|
## Agent CLI Must Accept A Positional Prompt
|
|
84
86
|
|
|
85
|
-
The handoff is `<your cmd> "<prompt>"`. `claude`, `codex`,
|
|
87
|
+
The handoff is `<your cmd> "<prompt>"`. `claude`, `codex`, `cursor-agent`, and `pi` all support this.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clipboard-health/groundcrew",
|
|
3
|
-
"version": "4.48.
|
|
3
|
+
"version": "4.48.4",
|
|
4
4
|
"description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
@@ -69,8 +69,8 @@
|
|
|
69
69
|
"verify": "node scripts/verifyAll.mts"
|
|
70
70
|
},
|
|
71
71
|
"dependencies": {
|
|
72
|
-
"@clipboard-health/clearance": "1.
|
|
73
|
-
"@linear/sdk": "88.
|
|
72
|
+
"@clipboard-health/clearance": "1.6.2",
|
|
73
|
+
"@linear/sdk": "88.2.0",
|
|
74
74
|
"agent-trust": "1.0.0",
|
|
75
75
|
"cosmiconfig": "9.0.2",
|
|
76
76
|
"tslib": "2.8.1",
|
|
@@ -78,8 +78,8 @@
|
|
|
78
78
|
},
|
|
79
79
|
"devDependencies": {
|
|
80
80
|
"@clipboard-health/ai-rules": "2.43.4",
|
|
81
|
-
"@clipboard-health/oxlint-config": "1.
|
|
82
|
-
"@nx/js": "
|
|
81
|
+
"@clipboard-health/oxlint-config": "1.14.1",
|
|
82
|
+
"@nx/js": "23.1.0",
|
|
83
83
|
"@tsconfig/node24": "24.0.4",
|
|
84
84
|
"@tsconfig/strictest": "2.0.8",
|
|
85
85
|
"@types/node": "25.9.5",
|
|
@@ -88,15 +88,15 @@
|
|
|
88
88
|
"dependency-cruiser": "18.1.0",
|
|
89
89
|
"husky": "9.1.7",
|
|
90
90
|
"jscpd": "5.0.12",
|
|
91
|
-
"knip": "6.
|
|
92
|
-
"lint-staged": "17.
|
|
91
|
+
"knip": "6.29.0",
|
|
92
|
+
"lint-staged": "17.1.1",
|
|
93
93
|
"markdownlint-cli2": "0.23.1",
|
|
94
|
-
"nx": "
|
|
95
|
-
"oxfmt": "0.
|
|
96
|
-
"oxlint": "1.
|
|
97
|
-
"oxlint-tsgolint": "0.
|
|
94
|
+
"nx": "23.1.0",
|
|
95
|
+
"oxfmt": "0.60.0",
|
|
96
|
+
"oxlint": "1.74.0",
|
|
97
|
+
"oxlint-tsgolint": "7.0.2001",
|
|
98
98
|
"syncpack": "15.3.2",
|
|
99
|
-
"vite": "8.1.
|
|
99
|
+
"vite": "8.1.5",
|
|
100
100
|
"vitest": "4.1.10"
|
|
101
101
|
},
|
|
102
102
|
"engines": {
|