dkitchen 0.1.0__tar.gz

dkitchen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 917Dhj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dkitchen-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: dkitchen
+Version: 0.1.0
+Summary: A multi-agent workflow for research repos, with the ding CLI for messaging and waking agent sessions
+Author: 917Dhj
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/917Dhj/dkitchen
+Project-URL: Documentation, https://github.com/917Dhj/dkitchen/blob/main/docs/ding.md
+Project-URL: Repository, https://github.com/917Dhj/dkitchen
+Project-URL: Issues, https://github.com/917Dhj/dkitchen/issues
+Keywords: agents,multi-agent,codex,claude-code,workflow,research,tmux,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websocket-client<2,>=1.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# dkitchen
+
+**English** | [简体中文](https://github.com/917Dhj/dkitchen/blob/main/README.zh-CN.md)
+
+**You decide what to cook. Your agents run the kitchen.** 🧑‍🍳
+
+dkitchen is the multi-agent workflow I use every day to run my research repo. It gives a set of Claude Code and Codex sessions fixed stations, a shared way to hand off work through GitHub issues, clear rules for when to stop and ask you, and the tools that tie it together. You keep the decisions only you can make: what to research, what to try, what to spend.
+
+## 🍽️ Why a kitchen
+
+AI agents made execution cheap. The bottleneck moved to you.
+
+With one agent, you supervise every step. With several, you become the message bus: copying context between sessions, checking whether a job finished, remembering which session owns which task, approving small things all day. Your GPUs sit idle between runs because nobody noticed the last one ended. By evening you have touched everything and thought about nothing.
+
+A Michelin kitchen solves the same problem. The head chef designs the menu and tastes the dishes. Everyone else has a station, every order is a ticket, and a bell rings when a dish is ready. The head chef never chops onions, and never loses track of the kitchen.
+
+dkitchen sets up your agents the same way. You are the head chef.
+
+## 🧑‍🍳 The kitchen
+
+| Station | In a kitchen | What it does | Runs on |
+| --- | --- | --- | --- |
+| 👑 **You** | Head chef | Choose the direction, approve designs and budgets, decide what the results mean for your paper. | You |
+| 🤖 **Orchestrator** | Sous chef at the pass | Schedules tickets, GPUs, and concurrency. Relays messages, reviews and merges PRs, reports facts to you. | Claude Code · Claude Opus 5.5 |
+| 🤔 **Designer** | Recipe developer | Writes tickets, designs methods and every piece of text a model will see, interprets results. | Claude Code · Claude Opus 5.5 |
+| 🔍 **Verifier** | Taster | Checks facts against code and data before money is spent. Reports what it found and never makes the call. | Claude Code · Claude Sonnet 5.5 |
+| 🔪 **Executors** | Line cooks | One fresh session per ticket, in its own worktree. Implements, runs, and reports on the ticket. | Codex · GPT-6.1 Sol |
+
+Each station has written rules for what it owns, what it hands off, and when it must stop. When something fits no station, the agents ask you.
+
+## 🎫 How a ticket moves through the kitchen
+
+1. **You and the designer agree on what to do.** The designer writes it up as a GitHub issue: the goal, the exact steps, and the budget the work may spend.
+2. **The verifier checks the ticket's premises** against the code and data: field names, dataset ranges, call counts, cost estimates.
+3. **The orchestrator dispatches it** to a new executor session and picks free GPUs.
+4. **The executor works and reports on the ticket.** Every comment opens with the same four lines: status, who it is waiting on, the key numbers, and what happens next. Long jobs start with `ding launch`; when the job exits, `ding` wakes the executor so it can read the output and continue.
+5. **Results go to the designer** for interpretation. The orchestrator reviews the PR, merges it, and logs what it did and why.
+6. **You read a short report** and make the next call.
+
+Every decision, request, and result lives on a ticket, so any session (or you, a week later) can pick up the story from GitHub.
+
+## ✋ What stays with you
+
+The rules write down which calls belong to the head chef:
+
+- the research direction, how datasets are used, and what the paper claims;
+- model runs, paid API calls, or service starts beyond what a ticket's approved budget covers.
+
+Agents propose on these and wait. An approval only counts when it is in your own words. Neither the orchestrator nor the designer can approve on your behalf.
+
+Everything else the kitchen handles on its own, by one rule: **if anyone would do it the same way, the agents do it. If the choice changes the results, the cost, or the direction, they stop and wait for you.**
+
+This is what lets you walk away. While you are in class, asleep, or reading papers, an issue watcher wakes the orchestrator when an executor finishes a stage, gets stuck, or goes quiet; when you leave a comment; or when a PR opens. The orchestrator moves forward what is already approved and leaves a list of decisions for when you are back.
+
+## ⚖️ One pool of resources
+
+A research repo has more resources than any single agent sees: GPUs on several servers, a shared model server, CPU time, an API budget, tokens, and hours in the day. In dkitchen the orchestrator, running on the strongest model you have, manages them as one pool.
+
+- 🖥️ **Compute.** It schedules tickets across free GPUs and checks the shared model server's load before raising concurrency.
+- 💰 **Money.** Each ticket that runs models carries one approved budget for calls, cost, and GPU hours. Stages within the budget start right away, and anything beyond it comes back to you.
+- 🪙 **Tokens.** One session per ticket keeps each context small, and fact-checking runs on a cheaper model.
+- ⏱️ **Time.** Jobs wake their owner when they exit, so nothing waits for someone to look.
+
+## 🧰 The tools
+
+### 🛎️ `ding`, the bell
+
+`ding` passes messages between agent sessions and wakes a session when its long job ends.
+
+```bash
+ding board                                            # who is working on what, in this repo
+ding send '#42' --from orchestrator --message-file note.md
+ding launch train -- python train.py                  # run in tmux, wake me when it exits
+```
+
+You can address a session by its UUID, its name, or a GitHub issue such as `'#42'`; `ding` finds the session that owns that ticket. On Linux, `ding board` also lists long-running processes that were started without `ding`, so you can spot jobs nobody will be woken for.
+
+`ding` talks to Codex sessions through the Codex App Server. The full guide is in [docs/ding.md](https://github.com/917Dhj/dkitchen/blob/main/docs/ding.md).
+
+## 🚀 Get started
+
+### Requirements
+
+- Linux or another POSIX system, with `tmux`
+- Python 3.10 or later
+- A GitHub repo and the `gh` CLI
+- Claude Code, and Codex with its App Server running under the same user
+
+### Install `ding`
+
+```bash
+pipx install git+https://github.com/917Dhj/dkitchen.git
+```
+
+## ❓ FAQ
+
+**Is it safe to let agents run unattended?**
+They stop for anything that changes direction, results, or spending, and approvals only come from your own words on a ticket. Every action is a comment or a PR on GitHub, so you can audit the night's work over coffee.
+
+**Will it fit my repo?**
+The rules were written for computational research, and most of them carry over to any repo with long-running jobs.
+
+**Do I need both Claude Code and Codex?**
+For now, yes. That is the combination I run every day.
+
+**Isn't this too much process for a small project?**
+Start with the orchestrator and executors, then add the designer and verifier when you want them.
+
+## 💡 About
+
+The *d* is my mark. dkitchen is how I run my own kitchen, written down so you can run yours. It started in my research repo, which moved 171 issues and 111 merged PRs through this workflow in its first four weeks.
+
+The Michelin kitchen metaphor comes from Lauren Tan, known online as [Poteto](https://github.com/poteto). Poteto's way of running agents inspired much of this workflow. Thank you, Poteto. 🙏
+
+## License
+
+[MIT](https://github.com/917Dhj/dkitchen/blob/main/LICENSE)

dkitchen-0.1.0/README.md

@@ -0,0 +1,117 @@
+# dkitchen
+
+**English** | [简体中文](https://github.com/917Dhj/dkitchen/blob/main/README.zh-CN.md)
+
+**You decide what to cook. Your agents run the kitchen.** 🧑‍🍳
+
+dkitchen is the multi-agent workflow I use every day to run my research repo. It gives a set of Claude Code and Codex sessions fixed stations, a shared way to hand off work through GitHub issues, clear rules for when to stop and ask you, and the tools that tie it together. You keep the decisions only you can make: what to research, what to try, what to spend.
+
+## 🍽️ Why a kitchen
+
+AI agents made execution cheap. The bottleneck moved to you.
+
+With one agent, you supervise every step. With several, you become the message bus: copying context between sessions, checking whether a job finished, remembering which session owns which task, approving small things all day. Your GPUs sit idle between runs because nobody noticed the last one ended. By evening you have touched everything and thought about nothing.
+
+A Michelin kitchen solves the same problem. The head chef designs the menu and tastes the dishes. Everyone else has a station, every order is a ticket, and a bell rings when a dish is ready. The head chef never chops onions, and never loses track of the kitchen.
+
+dkitchen sets up your agents the same way. You are the head chef.
+
+## 🧑‍🍳 The kitchen
+
+| Station | In a kitchen | What it does | Runs on |
+| --- | --- | --- | --- |
+| 👑 **You** | Head chef | Choose the direction, approve designs and budgets, decide what the results mean for your paper. | You |
+| 🤖 **Orchestrator** | Sous chef at the pass | Schedules tickets, GPUs, and concurrency. Relays messages, reviews and merges PRs, reports facts to you. | Claude Code · Claude Opus 5.5 |
+| 🤔 **Designer** | Recipe developer | Writes tickets, designs methods and every piece of text a model will see, interprets results. | Claude Code · Claude Opus 5.5 |
+| 🔍 **Verifier** | Taster | Checks facts against code and data before money is spent. Reports what it found and never makes the call. | Claude Code · Claude Sonnet 5.5 |
+| 🔪 **Executors** | Line cooks | One fresh session per ticket, in its own worktree. Implements, runs, and reports on the ticket. | Codex · GPT-6.1 Sol |
+
+Each station has written rules for what it owns, what it hands off, and when it must stop. When something fits no station, the agents ask you.
+
+## 🎫 How a ticket moves through the kitchen
+
+1. **You and the designer agree on what to do.** The designer writes it up as a GitHub issue: the goal, the exact steps, and the budget the work may spend.
+2. **The verifier checks the ticket's premises** against the code and data: field names, dataset ranges, call counts, cost estimates.
+3. **The orchestrator dispatches it** to a new executor session and picks free GPUs.
+4. **The executor works and reports on the ticket.** Every comment opens with the same four lines: status, who it is waiting on, the key numbers, and what happens next. Long jobs start with `ding launch`; when the job exits, `ding` wakes the executor so it can read the output and continue.
+5. **Results go to the designer** for interpretation. The orchestrator reviews the PR, merges it, and logs what it did and why.
+6. **You read a short report** and make the next call.
+
+Every decision, request, and result lives on a ticket, so any session (or you, a week later) can pick up the story from GitHub.
+
+## ✋ What stays with you
+
+The rules write down which calls belong to the head chef:
+
+- the research direction, how datasets are used, and what the paper claims;
+- model runs, paid API calls, or service starts beyond what a ticket's approved budget covers.
+
+Agents propose on these and wait. An approval only counts when it is in your own words. Neither the orchestrator nor the designer can approve on your behalf.
+
+Everything else the kitchen handles on its own, by one rule: **if anyone would do it the same way, the agents do it. If the choice changes the results, the cost, or the direction, they stop and wait for you.**
+
+This is what lets you walk away. While you are in class, asleep, or reading papers, an issue watcher wakes the orchestrator when an executor finishes a stage, gets stuck, or goes quiet; when you leave a comment; or when a PR opens. The orchestrator moves forward what is already approved and leaves a list of decisions for when you are back.
+
+## ⚖️ One pool of resources
+
+A research repo has more resources than any single agent sees: GPUs on several servers, a shared model server, CPU time, an API budget, tokens, and hours in the day. In dkitchen the orchestrator, running on the strongest model you have, manages them as one pool.
+
+- 🖥️ **Compute.** It schedules tickets across free GPUs and checks the shared model server's load before raising concurrency.
+- 💰 **Money.** Each ticket that runs models carries one approved budget for calls, cost, and GPU hours. Stages within the budget start right away, and anything beyond it comes back to you.
+- 🪙 **Tokens.** One session per ticket keeps each context small, and fact-checking runs on a cheaper model.
+- ⏱️ **Time.** Jobs wake their owner when they exit, so nothing waits for someone to look.
+
+## 🧰 The tools
+
+### 🛎️ `ding`, the bell
+
+`ding` passes messages between agent sessions and wakes a session when its long job ends.
+
+```bash
+ding board                                            # who is working on what, in this repo
+ding send '#42' --from orchestrator --message-file note.md
+ding launch train -- python train.py                  # run in tmux, wake me when it exits
+```
+
+You can address a session by its UUID, its name, or a GitHub issue such as `'#42'`; `ding` finds the session that owns that ticket. On Linux, `ding board` also lists long-running processes that were started without `ding`, so you can spot jobs nobody will be woken for.
+
+`ding` talks to Codex sessions through the Codex App Server. The full guide is in [docs/ding.md](https://github.com/917Dhj/dkitchen/blob/main/docs/ding.md).
+
+## 🚀 Get started
+
+### Requirements
+
+- Linux or another POSIX system, with `tmux`
+- Python 3.10 or later
+- A GitHub repo and the `gh` CLI
+- Claude Code, and Codex with its App Server running under the same user
+
+### Install `ding`
+
+```bash
+pipx install git+https://github.com/917Dhj/dkitchen.git
+```
+
+## ❓ FAQ
+
+**Is it safe to let agents run unattended?**
+They stop for anything that changes direction, results, or spending, and approvals only come from your own words on a ticket. Every action is a comment or a PR on GitHub, so you can audit the night's work over coffee.
+
+**Will it fit my repo?**
+The rules were written for computational research, and most of them carry over to any repo with long-running jobs.
+
+**Do I need both Claude Code and Codex?**
+For now, yes. That is the combination I run every day.
+
+**Isn't this too much process for a small project?**
+Start with the orchestrator and executors, then add the designer and verifier when you want them.
+
+## 💡 About
+
+The *d* is my mark. dkitchen is how I run my own kitchen, written down so you can run yours. It started in my research repo, which moved 171 issues and 111 merged PRs through this workflow in its first four weeks.
+
+The Michelin kitchen metaphor comes from Lauren Tan, known online as [Poteto](https://github.com/poteto). Poteto's way of running agents inspired much of this workflow. Thank you, Poteto. 🙏
+
+## License
+
+[MIT](https://github.com/917Dhj/dkitchen/blob/main/LICENSE)

dkitchen-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dkitchen"
+version = "0.1.0"
+description = "A multi-agent workflow for research repos, with the ding CLI for messaging and waking agent sessions"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "917Dhj"}]
+keywords = ["agents", "multi-agent", "codex", "claude-code", "workflow", "research", "tmux", "cli"]
+dependencies = ["websocket-client>=1.9,<2"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+ding = "dkitchen.ding:main"
+
+[project.urls]
+Homepage = "https://github.com/917Dhj/dkitchen"
+Documentation = "https://github.com/917Dhj/dkitchen/blob/main/docs/ding.md"
+Repository = "https://github.com/917Dhj/dkitchen"
+Issues = "https://github.com/917Dhj/dkitchen/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dkitchen-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dkitchen-0.1.0/src/dkitchen/__init__.py

@@ -0,0 +1 @@
+"""dkitchen: a multi-agent workflow kit. The `ding` CLI lives in `dkitchen.ding`."""