dingo-pack 0.4.2__tar.gz

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.
@@ -0,0 +1,41 @@
1
+ # Build and validate before the protected, token-free publishing job.
2
+ name: publish
3
+ on:
4
+ release:
5
+ types: [published]
6
+ permissions:
7
+ contents: read
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+ - uses: astral-sh/setup-uv@v6
14
+ - name: Self-test
15
+ run: uv run --no-project python selftest_dingo_pack.py
16
+ - name: Build and validate distributions
17
+ run: |
18
+ uv build
19
+ uvx twine check dist/*
20
+ uv run --no-project python selftest_release.py --artifacts dist
21
+ - name: Check the version matches the release tag
22
+ run: |
23
+ v=$(uv run --no-project python bin/dingo-pack --version | awk '{print $2}')
24
+ test "v$v" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != package version $v"; exit 1; }
25
+ - uses: actions/upload-artifact@v4
26
+ with:
27
+ name: distributions
28
+ path: dist/*
29
+ if-no-files-found: error
30
+ pypi:
31
+ needs: build
32
+ runs-on: ubuntu-latest
33
+ environment: pypi
34
+ permissions:
35
+ id-token: write
36
+ steps:
37
+ - uses: actions/download-artifact@v4
38
+ with:
39
+ name: distributions
40
+ path: dist/
41
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,40 @@
1
+ name: test
2
+ on: [push, pull_request]
3
+ permissions:
4
+ contents: read
5
+ jobs:
6
+ posix:
7
+ strategy:
8
+ # One broken cell must not cancel the others (the 3.8 cell hid 3.12 / macOS results).
9
+ fail-fast: false
10
+ matrix:
11
+ include:
12
+ # ubuntu-latest is 26.04 now and setup-python has no 3.8 build for it;
13
+ # 3.8 is still built for 22.04.
14
+ - {os: ubuntu-22.04, python: '3.8'}
15
+ - {os: ubuntu-latest, python: '3.12'}
16
+ - {os: macos-latest, python: '3.12'}
17
+ runs-on: ${{ matrix.os }}
18
+ steps:
19
+ - uses: actions/checkout@v4
20
+ - uses: actions/setup-python@v5
21
+ with:
22
+ python-version: ${{ matrix.python }}
23
+ - name: Portable smoke and failure diagnostics
24
+ run: python selftest_release.py --portable
25
+ - name: Full Linux regression
26
+ if: runner.os == 'Linux'
27
+ run: python selftest_dingo_pack.py
28
+ windows-boundary:
29
+ runs-on: windows-latest
30
+ steps:
31
+ - uses: actions/checkout@v4
32
+ - uses: actions/setup-python@v5
33
+ with:
34
+ python-version: '3.12'
35
+ - name: Native Windows gives an actionable unsupported-platform message
36
+ shell: pwsh
37
+ run: |
38
+ $output = python bin/dingo-pack --version 2>&1 | Out-String
39
+ if ($LASTEXITCODE -ne 2 -or $output -notmatch 'inside WSL2') { throw $output }
40
+ exit 0
@@ -0,0 +1,9 @@
1
+ # 本地验证产物;公开分发另用 pyproject 的显式清单。
2
+ .venv*/
3
+ dist/
4
+ __pycache__/
5
+ *.pyc
6
+ *.log
7
+ validation*/
8
+ core
9
+ core.*
@@ -0,0 +1,96 @@
1
+ # Adapters: teaching dingo-pack about another coding agent
2
+
3
+ dingo-pack's core (process trees, memory, slots, the git queue via wombat-gate, boxes, the board) does not care which agent you run. Three things do, and they live in an **adapter**:
4
+
5
+ 1. **Find the sessions.** Which agent sessions are alive on this machine: id, name, pid, working directory, state.
6
+ 2. **Read a session's record.** Where its transcript is, and how many tokens each turn used.
7
+ 3. **Hook into it.** How to make the agent run `dingo-pack save --hook` every turn and `hooks/hint.py` before heavy tool calls (optional: everything else works without hooks).
8
+
9
+ dingo-pack ships one adapter, for Claude Code. If you are an agent (Codex, pi, …) reading this to set dingo-pack up for yourself: write the ~100 lines below for your own agent, run the adapter test, and point dingo-pack at the file. We maintain the interface, the Claude Code adapter and the test, not other agents' adapters.
10
+
11
+ ## 1 · The interface
12
+
13
+ One Python file that defines `ADAPTER`, an object with these attributes and methods (duck-typed; no base class to import):
14
+
15
+ ```python
16
+ class MyAgentAdapter:
17
+ name = "my-agent" # shown in `dingo-pack top` next to each session
18
+ owner_env = "MY_AGENT_PID" # env var your agent sets in every process it starts, holding the agent's pid;
19
+ # None if there is none (then only the agent's process tree counts as its children)
20
+
21
+ def sessions(self):
22
+ """Live sessions on this machine. A list of dicts:
23
+ {"id": str, "pid": int, "name": str or None, "cwd": str or None,
24
+ "proc_start": str or None, # /proc/<pid>/stat field 22, to tell a reused pid apart (None if unknown)
25
+ "status": "busy" | "idle" | "waiting" | None,
26
+ "started_at": float or None} # epoch seconds"""
27
+
28
+ def transcript(self, session_id):
29
+ """Path of the session's transcript file, or None."""
30
+
31
+ def subtranscripts(self, session_id, path):
32
+ """Paths of its sub-agents' transcripts (may be [])."""
33
+
34
+ def usage(self, path, cache):
35
+ """Tokens in one transcript, read incrementally. `cache` is a dict you may keep state in
36
+ (dingo-pack saves it between runs, keyed however you like). Return
37
+ {"days": {"YYYY-MM-DD": [input, cache_write, cache_read, output, turns]},
38
+ "last_input": int or None} # input tokens of the latest turn (input + cache write + cache read)
39
+ or None if the file cannot be read. Count each model call once."""
40
+
41
+ def hooks(self):
42
+ """A short text for the human: how to make the agent run the two hooks."""
43
+
44
+ ADAPTER = MyAgentAdapter()
45
+ ```
46
+
47
+ Rules:
48
+
49
+ - **Read only.** An adapter must not write to the agent's files or send signals. dingo-pack's own test checks that `sessions()` and `usage()` leave the files they read unchanged.
50
+ - **Say "unknown", never guess.** If a field is not available, return `None`; the board then shows "读不到" / "?" instead of a made-up number.
51
+ - Standard library only, Python ≥ 3.8.
52
+
53
+ ## 2 · Test it
54
+
55
+ ```sh
56
+ DINGO_AGENTS=/path/to/my_agent_adapter.py dingo-pack adapter test
57
+ ```
58
+
59
+ It loads the file, calls each method on the live machine, and checks: types and required keys, that each `pid` is alive, that transcripts exist and `usage()` returns non-negative integers, and that nothing it read changed. Exit code 0 = usable; otherwise it lists what is wrong.
60
+
61
+ ## 3 · Use it
62
+
63
+ ```sh
64
+ export DINGO_AGENTS=claude-code,/path/to/my_agent_adapter.py # several agents on one machine
65
+ dingo-pack top # each session: children, what it waits for, spin flags, tokens
66
+ dingo-pack tokens # tokens per session today
67
+ dingo-pack board
68
+ ```
69
+
70
+ `DINGO_AGENTS` takes built-in names (`claude-code`) and paths to adapter files, comma-separated. The default is `claude-code`.
71
+
72
+ ## 4 · What uses the interface (0.4)
73
+
74
+ `top`, `tokens` and the task columns of `board` go through adapters. The roster (`save` / `list` / `resume` / `close-all` / `restore`) and `ghosts` still talk to Claude Code directly; they move behind the interface in a later version.
75
+
76
+ ## 5 · The Claude Code adapter, for reference
77
+
78
+ - sessions: `~/.claude/sessions/<pid>.json` (`sessionId`, `pid`, `procStart`, `name`, `nameSource`, `status`, `cwd`, `startedAt`).
79
+ - transcript: `~/.claude/projects/<dir>/<sessionId>.jsonl`; sub-agents in `<sessionId>/subagents/*.jsonl`.
80
+ - usage: assistant lines carry `message.usage` (`input_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `output_tokens`); one message is often written several times with the same `message.id`, so it is counted once.
81
+ - owner_env: `CLAUDE_PID`.
82
+ - hooks: the plugin in this repo (`/plugin install dingo-pack@dingo-pack`), or the snippet in REFERENCE.md.
83
+
84
+ ## 6 · Claude Code、Codex、OpenCode Go 的接入边界
85
+
86
+ 三者可在同一 POSIX 主机上调用 `dingo-pack run --heavy --mem <预估> -- <命令>`,
87
+ 共享本地 DINGO_HOME。README 中英版给出项目 AGENTS.md、Codex skill、OpenCode
88
+ instructions 的配置例子。这些规则要求 agent 主动包命令,不构成外部命令拦截。
89
+
90
+ 内置适配器只有 `claude-code`;Codex 与 OpenCode Go 没有内置发现/token/恢复适配。
91
+ 不要在 DINGO_AGENTS 中填写不存在的内置名称。自定义实现通过文件路径加载,按上文
92
+ `adapter test` 校验;名册与 ghosts 仍仅针对 Claude。
93
+
94
+ All three agents can share command admission. Only Claude Code has a built-in session
95
+ adapter. Use external adapter file paths for other agents; do not invent built-in names.
96
+ The instruction/skill examples in both READMEs are guidance, not enforcement hooks.
@@ -0,0 +1,34 @@
1
+ # 更新记录 / Changelog
2
+
3
+ ## 0.4.2 · 候选 / candidate
4
+
5
+ - Re-release of the 0.4.1 candidate with the public repo brought in sync: `hooks/hint.py` and `skills/dingo-pack/SKILL.md` now match the source tree.
6
+ - Positional arguments after options are accepted on Python < 3.12 (argparse `parse_known_args` fallback), so `mark done --sid X note` and similar forms work from 3.8 through 3.14; command lines are unchanged.
7
+ - Self-test falls back to the tool's fixed-zone implementation when `zoneinfo` is missing (Python 3.8), removing the four zone-related failures there.
8
+ - CI: the 3.8 job runs on `ubuntu-22.04` (setup-python has no 3.8 build for 26.04) and `fail-fast` is off, so one red job no longer cancels the others; the test matrix is an explicit `include`.
9
+
10
+ ## 0.4.1 · 候选 / candidate
11
+
12
+ - 基于 0.4.0,保留 boxes、tokens、任务列及只读适配接口;未部署、未发布。
13
+ Based on 0.4.0; retains boxes, tokens, task columns and read-only adapters; not deployed or published.
14
+ - 失败时输出配置上限、退出信号和审慎的可能撞限提示;保留子命令输出、退出码与整树停止行为。
15
+ Report configured limits, exit signals and cautious memory hints; preserve child output and exit codes.
16
+ - sdist 补 ADAPTERS、发布说明与回归;补中英平台表、三种 agent 接法和安装演示。
17
+ Include adapter/release docs and regressions in sdist; document platforms, agent setup and local install.
18
+ - 发布前独立构建检查,审批后的上传任务只消费产物;增加 Linux/macOS CI 与 Windows 边界检查。
19
+ Validate artifacts before environment approval; publishing consumes artifacts; add platform CI.
20
+
21
+ ## 0.4.0 · work 源码基线 / source baseline
22
+
23
+ boxes、tokens、adapter test、任务等待列及 claim 扩展;历史测试通过但未部署。
24
+ Adds boxes, tokens, adapter test, task/wait columns and claim extensions; historically tested, not deployed.
25
+
26
+ ## 0.3.1 · 未公开发布 / unpublished build
27
+
28
+ 慢盘队列、CPU 名额、doctor、ghosts、会话恢复、看板与占用登记。
29
+ I/O lane, CPU slots, doctor, ghosts, session restore, board and claims.
30
+
31
+ ## 0.1.1 · 公开 release / public release
32
+
33
+ 名额、内存准入与上限、lease、Claude 名册与恢复。
34
+ Slots, memory admission/limits, leases and Claude roster/resume.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 liyifreddy
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,284 @@
1
+ Metadata-Version: 2.5
2
+ Name: dingo-pack
3
+ Version: 0.4.2
4
+ Summary: The pack eats in order: heavy-job slots, memory admission and a crash-recovery session roster for many AI agents on one machine.
5
+ Project-URL: Homepage, https://github.com/liyifreddy/dingo-pack
6
+ Project-URL: Issues, https://github.com/liyifreddy/dingo-pack/issues
7
+ Author: liyifreddy
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: claude-code,memory,multi-agent,oom,queue,sessions,wsl
11
+ Classifier: Environment :: Console
12
+ Classifier: Operating System :: POSIX
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: System :: Monitoring
15
+ Requires-Python: >=3.8
16
+ Description-Content-Type: text/markdown
17
+
18
+ # 🐕 dingo-pack
19
+
20
+ <p align="center">
21
+ <img src="https://raw.githubusercontent.com/liyifreddy/dingo-pack/main/docs/img/dingo-pack-banner.jpg" width="100%"
22
+ alt="Dingoes eating side by side at a trough with four compartments while three more wait their turn">
23
+ </p>
24
+
25
+ **Like a tab saver, for your Claude Code sessions.**
26
+
27
+ ```sh
28
+ dingo-pack save # remember the open sessions (the hooks also do it)
29
+ dingo-pack close-all # remember them, close the idle ones that are waiting / done
30
+ dingo-pack restore # bring the last batch back, one terminal tab each
31
+ ```
32
+
33
+ 🌐 **English** · [中文](https://github.com/liyifreddy/dingo-pack/blob/main/README.zh-CN.md)
34
+
35
+ The pack eats in order: dingoes share a kill without a scramble. dingo-pack is the pack
36
+ leader for a dozen coding agents on one machine — it also hands out slots for heavy work
37
+ and checks what is wrong when the machine struggles.
38
+
39
+ `restore` opens a new Windows Terminal tab per session when it runs in WSL, a tmux window
40
+ inside tmux, and otherwise prints the commands for you to paste. `close-all` only closes
41
+ sessions that are idle and said they are waiting or done, and it is for humans: inside an
42
+ agent it refuses.
43
+
44
+ ## 🚀 Quick start
45
+
46
+ ```sh
47
+ pipx install git+https://github.com/liyifreddy/dingo-pack
48
+
49
+ dingo-pack # one screen: memory, slots, sessions
50
+ dingo-pack run --heavy --mem 4G -- pytest # heavy work waits for a slot and free memory
51
+ dingo-pack doctor # what's wrong with this machine right now?
52
+ dingo-pack list # after a crash: which sessions were lost
53
+ dingo-pack resume --midway # reopen the ones that were mid-task
54
+ ```
55
+
56
+ In Claude Code, install the plugin and the roster saves itself:
57
+
58
+ ```
59
+ /plugin marketplace add liyifreddy/dingo-pack
60
+ /plugin install dingo-pack@dingo-pack
61
+ ```
62
+
63
+ One file, Python ≥ 3.8, standard library only. Linux, macOS and WSL.
64
+
65
+ ## Release and installation demo
66
+
67
+ Current release: **0.4.2**. Install it from PyPI with pip or pipx:
68
+
69
+ ```sh
70
+ python3 -m pip install dingo-pack # or: pipx install dingo-pack
71
+ dingo-pack --version
72
+ ```
73
+
74
+ To install from this source tree instead, use a separate environment:
75
+
76
+ ```sh
77
+ python3 -m venv .venv-demo && .venv-demo/bin/python -m pip install .
78
+ .venv-demo/bin/dingo-pack --version
79
+ .venv-demo/bin/dingo-pack run --heavy --threads 1 --mem 64M -- python3 -c 'print("hello")'
80
+ ```
81
+
82
+ Expected from either: `dingo-pack 0.4.2`; the source demo also prints `hello`
83
+ (admission may wait). State and locks must live on a local disk; leave `DINGO_HOME`
84
+ at its default, outside a WSL mounted drive. `boxes`, `tokens`, adapter validation
85
+ and task/wait columns are included; `watch`, `dispatch` and full three-table
86
+ crosscheck remain design proposals. See [CHANGELOG](CHANGELOG.md) and
87
+ [release procedure](RELEASING.md).
88
+
89
+ ## Platforms and agents
90
+
91
+ | Platform | Support boundary | Tested for this candidate (2026-11-04) |
92
+ |---|---|---|
93
+ | Linux | POSIX CLI and `/proc` monitoring | WSL Linux kernel tested; separate native Linux host not tested |
94
+ | WSL2 | Run Python and the CLI inside WSL; state on the Linux disk | Tested: full suite, bounded CSV and install smoke |
95
+ | macOS | POSIX CLI, `ps`/`vm_stat` fallbacks; Linux-only probes may be unknown | Not tested; portable CI job added, not yet run |
96
+ | Native Windows | Unsupported: requires `fcntl`, POSIX signals and resource limits; use WSL2 | Tested with native Windows Python 3.14: actionable unsupported-platform message, exit 2 |
97
+
98
+ All three agents can use the same `run` queue on a supported host. No tool-specific
99
+ hook is required to wrap a shell command. Configuration examples below are manual
100
+ instructions, not enforcement hooks.
101
+
102
+ - **Claude Code:** plugin installation above supplies hooks; see [REFERENCE](REFERENCE.md)
103
+ for manual hook configuration. The bundled `skills/dingo-pack/SKILL.md` supplies guidance.
104
+ - **Codex:** add the following rule to the project's `AGENTS.md`. Optionally copy
105
+ `skills/dingo-pack/SKILL.md` into `.agents/skills/dingo-pack/SKILL.md` in that project.
106
+ - **OpenCode Go:** when using OpenCode with Go, put the same rule in the project's
107
+ `AGENTS.md`. Alternatively reference a rule file in `opencode.json`:
108
+ `{"$schema":"https://opencode.ai/config.json","instructions":["docs/heavy-work.md"]}`.
109
+ No provider credentials are needed by dingo-pack.
110
+
111
+ ```markdown
112
+ Before heavy shell work, run `dingo-pack who`, then wrap the command:
113
+ `dingo-pack run --heavy --mem <estimated peak> -- <command>`.
114
+ Use the same local DINGO_HOME for all agents sharing the machine.
115
+ Keep the queue and memory limits in force; report failures with the diagnostic line.
116
+ ```
117
+
118
+ Claude Code has a built-in session/token adapter. Codex and OpenCode can share the
119
+ queue, but automatic session discovery, token counts, resume and close are not
120
+ provided for them. External read-only adapters can extend `top`/`tokens`/task columns;
121
+ [ADAPTERS](ADAPTERS.md) defines that interface. Roster and ghosts are still Claude-specific.
122
+ Agent UI sessions were not launched for this candidate's tests.
123
+
124
+ Sources: [Codex instructions](https://learn.chatgpt.com/docs/agent-configuration/agents-md),
125
+ [skills](https://learn.chatgpt.com/docs/build-skills),
126
+ [OpenCode rules](https://docs.opencode.ai/docs/rules/).
127
+
128
+ ## Reading memory failures
129
+
130
+ On a failed job, the CLI preserves its exit status and prints configured per-process
131
+ and tree limits, sampled RSS, and the exit signal. `SIGSEGV`/139 and `SIGKILL`/137 with
132
+ a configured cap mean **possible memory limit hit**, not proof of OOM. A tree-limit
133
+ stop is confirmed by the supervisor. An ordinary nonzero exit keeps its cause unknown;
134
+ read the child's `MemoryError`, parser error or application error too.
135
+
136
+ Without configuration, defaults are `--mem 1G`, per-process `--limit 1.5G`, and matching tree limit.
137
+ `default_mem` / `DINGO_DEFAULT_MEM` overrides the estimate. RLIMIT_DATA
138
+ and RLIMIT_AS are not RSS: failed allocations and brief peaks can be missed by RSS
139
+ sampling. For large CSVs, prefer chunked reading; if more memory is needed, check
140
+ available memory and raise the estimate/caps together. Input file size alone does not
141
+ predict peak memory. `python3 selftest_release.py --large-csv` exercises a 670 MiB
142
+ synthetic CSV under bounded memory without loading gigabytes into RAM.
143
+
144
+ ## 😩 The problem
145
+
146
+ - 💥 **Heavy jobs pile up.** Test runs, model loads, builds and reviews from several
147
+ sessions start at once. In our 16 GB WSL VM, 13 sessions already used 4.4 GB; then the
148
+ kernel killed a 7.5–11 GB Python job, and work in flight died with it.
149
+ - 🪟 **WSL drops its Windows drives.** When memory runs out, `/mnt/c`, `/mnt/g`, … start
150
+ returning I/O errors until remounted — for every session at once.
151
+ - 👻 **Closed sessions leave things running.** Their python, node and MCP servers keep
152
+ eating memory until the next big job tips the machine over.
153
+ - 🧠 **After a crash, who was running?** Our laptop went down with 8 sessions open. We
154
+ pieced the list together from memory.
155
+
156
+ ## ✨ Five things
157
+
158
+ - ✅ 🎟️ **Slots and memory.** `run --heavy` waits for a free slot (6 by default) *and*
159
+ enough free memory, then runs the job under a memory limit for the whole process tree.
160
+ On a simulated 350 MB machine, four 150 MB jobs started together hit the OOM killer;
161
+ through dingo-pack, all four finish.
162
+ - ✅ 🚚 **A lane for slow disks.** `run --io` gives big copies, archives and scans on a
163
+ network or 9p drive their own queue (1 at a time), apart from CPU work.
164
+ - ✅ 📋 **Roster: close-all, restore, recall.** Before you shut down, `close-all` notes every
165
+ session and closes the ones that are idle and waiting or done; `restore` brings them
166
+ back. After a crash `restore` works too: it brings back what the crash lost.
167
+ - ✅ 👻 **Ghosts and sub-agent hints.** `ghosts` finds processes whose session is gone.
168
+ The hint hook tells an agent, before it starts sub-agents or heavy commands, how many
169
+ slots are free, how much memory is left, and how many jobs it should run in parallel.
170
+ - ✅ 🩺 **One-stop checkup.** `doctor` reads memory, recent OOM kills, whether each
171
+ network drive still answers, your WSL settings, stuck slots, lost sessions, ghosts and
172
+ git lock files (through [wombat-gate](https://github.com/liyifreddy/wombat-gate)). It
173
+ only reports; it never fixes anything for you.
174
+
175
+ ```
176
+ heavy 0 [###### pytest (est 2G) ######]
177
+ heavy 1 [######### lease: code review #########]
178
+ io 0 [## tar of the dataset ##]
179
+ queue C ──> D ──> E next in line waits for a free slot AND enough memory
180
+ ```
181
+
182
+ ## 🎟️ Heavy work and slow disks
183
+
184
+ ```sh
185
+ dingo-pack run --heavy --mem 6G -- python train.py # wait for a slot + 6 GB, then run
186
+ dingo-pack run --heavy --mem 2G --timeout 30m -- pytest # give up after 30 min (exit 75)
187
+ dingo-pack run --io -- tar -cf /mnt/g/backup.tar data/ # big copy on a slow disk: its own lane
188
+ dingo-pack who # who holds the slots, who is waiting
189
+ dingo-pack top # memory by session
190
+ ```
191
+
192
+ - `--threads N` (default 8) sets `OMP_NUM_THREADS`, `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`
193
+ and friends for the job and takes N of the machine's CPU slots (one per core). `doctor`
194
+ and the hint warn when the load is above 1.5 per core.
195
+ - `--mem` is your best guess at the peak. The limit defaults to 1.5 × that; go over it
196
+ and only your job stops (a single process gets a MemoryError; a whole tree over the
197
+ limit is stopped with exit 137), not the machine.
198
+ - Work that isn't a shell command — an agent's own review, a batch of sub-agents — takes
199
+ a lease: `dingo-pack lease --mem 3G --for 45m`, then `dingo-pack release`. The lease
200
+ also ends when its agent exits.
201
+
202
+ ## 📋 The roster
203
+
204
+ <p align="center">
205
+ <img src="https://raw.githubusercontent.com/liyifreddy/dingo-pack/main/docs/img/dingo-pack-roster-captioned.jpg" width="100%"
206
+ alt="Three panels: at night the pack leader keeps a roster by the campfires; a storm scatters the pack while the leader shelters with the roster; at dawn the leader whistles and the pack comes back to the fires">
207
+ </p>
208
+
209
+ 1. **Save** — sessions are snapshotted as they work.
210
+ 2. **The machine goes down** — the roster is already on disk.
211
+ 3. **Resume** — `list` shows who was lost; `resume` calls them back.
212
+
213
+ <p align="center"><sub>Illustrations generated with Google Gemini and edited by the author.</sub></p>
214
+
215
+ ```sh
216
+ dingo-pack mark running "step 3" # say what you're doing: running | waiting | blocked | done
217
+ dingo-pack mark waiting --until 18:30 "nightly job"
218
+ dingo-pack close-all # before shutting down: note everyone, close the idle waiting / done ones
219
+ dingo-pack restore # bring back what close-all closed
220
+ dingo-pack resume NAME... --via tmux # by name; tabs via Windows Terminal, tmux, or just print
221
+ ```
222
+
223
+ `close-all` never touches a session that is busy, running, blocked, or the one you
224
+ type it in, and it checks each session again right before closing it. It is for humans:
225
+ inside an agent it refuses.
226
+
227
+ ## 👻 Ghosts
228
+
229
+ ```sh
230
+ dingo-pack ghosts # process trees whose Claude Code session is gone
231
+ dingo-pack ghosts --reap # stop them, after asking (humans only)
232
+ ```
233
+
234
+ A process belongs to the session whose `CLAUDE_PID` it carries. Jobs left on purpose
235
+ (nohup, setsid, tmux, or a session that said it is waiting) are listed but kept.
236
+
237
+ ## 📊 Board
238
+
239
+ ```sh
240
+ dingo-pack board # one line per session: state, box, expected finish, flags
241
+ dingo-pack board --html board.html --watch 30 # a page that refreshes itself
242
+ ```
243
+
244
+ It reads each session's last status line. "ask now" means the expected finish it wrote
245
+ has passed; "may have stopped" means the status line has not changed for 3 hours
246
+ (`--stale-h`). It only understands an expected time after a word like 预计 / 约 … 完 / ETA;
247
+ anything else is left blank rather than guessed.
248
+
249
+ ## 🧰 Team routines (optional)
250
+
251
+ `name` (next session name for a letter), `card new` (next free card number + skeleton),
252
+ `lint` (naming, one session per letter, stale or overdue status lines), `queue` (prompts
253
+ waiting for a condition) and `claim` (the per-box occupancy file). All are deterministic
254
+ and off unless you call them — see the [reference](REFERENCE.md).
255
+
256
+ ## ⚙️ More
257
+
258
+ The plugin brings the CLI, the roster hooks, the hint hook and a skill that teaches the
259
+ agent when to use a slot. Hook setup without the plugin, project settings, every option
260
+ and WSL memory tips are in the [reference](REFERENCE.md).
261
+
262
+ ## ⚠️ Limits
263
+
264
+ - The agent process itself can't be limited, only counted with a lease.
265
+ - Only jobs started through dingo-pack are managed.
266
+ - Slots are handed out roughly first come, first served (the kernel decides who wakes first).
267
+ - macOS: the per-process limit isn't enforced (the tree limit is), and free memory is an
268
+ estimate. `ghosts`, `top` and the WSL checks need Linux.
269
+ - The roster reads Claude Code's session files, which aren't a documented interface. If
270
+ they change, it falls back to transcripts and says so.
271
+
272
+ ## ✅ Self-test
273
+
274
+ ```sh
275
+ python3 selftest_dingo_pack.py --base /some/local/dir # 1–3 min, depending on load
276
+ python3 selftest_dingo_pack.py --mutants # each planted bug must turn a check red
277
+ ```
278
+
279
+ Memory tests run on a simulated machine, never on your real memory.
280
+
281
+ ## 📄 License
282
+
283
+ MIT. Sister tool: [wombat-gate](https://github.com/liyifreddy/wombat-gate), a git commit
284
+ queue for agents sharing one repo.