dingo-pack 0.4.2__py3-none-any.whl
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,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.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
dingo_pack.py,sha256=VTfL4wbwojRq1ym4XuZO-cjF8QAOY-mkWVHgMirVXbo,190817
|
|
2
|
+
dingo_pack-0.4.2.dist-info/METADATA,sha256=6uxeu94aDCGymUyscB-gTotkpemBtIJLiF8F9xEGWrY,14254
|
|
3
|
+
dingo_pack-0.4.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
4
|
+
dingo_pack-0.4.2.dist-info/entry_points.txt,sha256=3Ovn3fybxLQR19IPrdtPLsaSMGF_wGlrwm5XiPxBFP8,47
|
|
5
|
+
dingo_pack-0.4.2.dist-info/licenses/LICENSE,sha256=vkORRUlcFkj4YtCKU43Fqdzmmf4ivx_Zzz2kdFBSAAg,1067
|
|
6
|
+
dingo_pack-0.4.2.dist-info/RECORD,,
|
|
@@ -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.
|