netra-zen 1.0.1__py3-none-any.whl → 1.0.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.
- {netra_zen-1.0.1.dist-info → netra_zen-1.0.2.dist-info}/METADATA +776 -776
- {netra_zen-1.0.1.dist-info → netra_zen-1.0.2.dist-info}/RECORD +7 -7
- {netra_zen-1.0.1.dist-info → netra_zen-1.0.2.dist-info}/licenses/LICENSE.md +1 -1
- zen_orchestrator.py +103 -37
- {netra_zen-1.0.1.dist-info → netra_zen-1.0.2.dist-info}/WHEEL +0 -0
- {netra_zen-1.0.1.dist-info → netra_zen-1.0.2.dist-info}/entry_points.txt +0 -0
- {netra_zen-1.0.1.dist-info → netra_zen-1.0.2.dist-info}/top_level.txt +0 -0
|
@@ -1,776 +1,776 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: netra-zen
|
|
3
|
-
Version: 1.0.
|
|
4
|
-
Summary: Multi-instance Claude orchestrator for parallel task execution
|
|
5
|
-
Home-page: https://github.com/netra-systems/zen
|
|
6
|
-
Author: Systems
|
|
7
|
-
Author-email: Netra Systems <pypi@netrasystems.ai>
|
|
8
|
-
License: MIT
|
|
9
|
-
Project-URL: Homepage, https://github.com/netra-systems/zen
|
|
10
|
-
Project-URL: Documentation, https://github.com/netra-systems/zen#readme
|
|
11
|
-
Project-URL: Repository, https://github.com/netra-systems/zen.git
|
|
12
|
-
Project-URL: Bug Tracker, https://github.com/netra-systems/zen/issues
|
|
13
|
-
Project-URL: Changelog, https://github.com/netra-systems/zen/blob/main/CHANGELOG.md
|
|
14
|
-
Keywords: claude,ai,orchestration,parallel,automation,llm,anthropic
|
|
15
|
-
Classifier: Development Status :: 4 - Beta
|
|
16
|
-
Classifier: Intended Audience :: Developers
|
|
17
|
-
Classifier: License :: Other/Proprietary License
|
|
18
|
-
Classifier: Operating System :: OS Independent
|
|
19
|
-
Classifier: Programming Language :: Python :: 3
|
|
20
|
-
Classifier: Programming Language :: Python :: 3.8
|
|
21
|
-
Classifier: Programming Language :: Python :: 3.9
|
|
22
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
23
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
24
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
25
|
-
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
26
|
-
Classifier: Topic :: Software Development :: Quality Assurance
|
|
27
|
-
Classifier: Topic :: System :: Distributed Computing
|
|
28
|
-
Requires-Python: >=3.8
|
|
29
|
-
Description-Content-Type: text/markdown
|
|
30
|
-
License-File: LICENSE.md
|
|
31
|
-
Requires-Dist: PyYAML>=6.0
|
|
32
|
-
Requires-Dist: python-dateutil>=2.8.2
|
|
33
|
-
Provides-Extra: dev
|
|
34
|
-
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
35
|
-
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
|
|
36
|
-
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
37
|
-
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
38
|
-
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
39
|
-
Requires-Dist: mypy>=1.0.0; extra == "dev"
|
|
40
|
-
Provides-Extra: netra
|
|
41
|
-
Requires-Dist: netraoptimizer>=1.0.0; extra == "netra"
|
|
42
|
-
Dynamic: author
|
|
43
|
-
Dynamic: home-page
|
|
44
|
-
Dynamic: license-file
|
|
45
|
-
Dynamic: requires-python
|
|
46
|
-
|
|
47
|
-
# Zen
|
|
48
|
-
|
|
49
|
-
Zen runs multiple Code CLI instances for peaceful parallel task execution.
|
|
50
|
-
|
|
51
|
-
## What is Zen?
|
|
52
|
-
|
|
53
|
-
Zen allows you to:
|
|
54
|
-
- Run multiple headless Claude Code CLI instances simultaneously.
|
|
55
|
-
- Calm unified results (status, time, token usage)
|
|
56
|
-
- Relax **"5-hour limit reached"** lockout fears with easy token budget limits
|
|
57
|
-
- Get more value out of your Claude MAX subscription
|
|
58
|
-
with scheduling features. (`--run-at "2am"`)
|
|
59
|
-
- Learn more about how Claude Code uses tools and other inner workings
|
|
60
|
-
- Control usage and budget for groups of work or per command
|
|
61
|
-
|
|
62
|
-
Example portion of status report:
|
|
63
|
-
```
|
|
64
|
-
╔═══ STATUS REPORT [14:25:10] ═══╗
|
|
65
|
-
║ Total: 5 instances
|
|
66
|
-
║ Running: 3, Completed: 2, Failed: 0
|
|
67
|
-
║ Tokens: 32.1K total | Tools: 15
|
|
68
|
-
║ 💰 Cost: $0.0642 total
|
|
69
|
-
║
|
|
70
|
-
║ TOKEN BUDGET STATUS
|
|
71
|
-
║ Overall: [████████████----] 75% 32.1K/43.0K
|
|
72
|
-
║
|
|
73
|
-
║ Status Name Duration Tokens
|
|
74
|
-
║ ──────── ───────────────── ─────── ──────
|
|
75
|
-
║ ✅ security-reviewer 2m15s 8.5K
|
|
76
|
-
║ ✅ performance-analyzer 1m42s 7.2K
|
|
77
|
-
║ 🏃 architecture-reviewer 1m18s 6.5K
|
|
78
|
-
║ 🏃 test-coverage-analyst 0m45s 4.8K
|
|
79
|
-
║ ⏳ quality-synthesizer queued 0K
|
|
80
|
-
╚════════════════════════════════════════════╝
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
## Example Start
|
|
84
|
-
```
|
|
85
|
-
zen
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
```
|
|
89
|
-
+=== STATUS REPORT [14:47:39] ===+
|
|
90
|
-
| Total: 2 instances
|
|
91
|
-
| Running: 2, Completed: 0, Failed: 0, Pending: 0
|
|
92
|
-
| Tokens: 0 total, 0 cached | Median: 0 | Tools: 0
|
|
93
|
-
| 💰 Cost: $0.0000 total, $0.0000 avg/instance | Pricing: Claude compliant
|
|
94
|
-
|
|
|
95
|
-
| TOKEN BUDGET STATUS |
|
|
96
|
-
| Overall: [--------------------] 0% 0/10.0K
|
|
97
|
-
| Command Budgets:
|
|
98
|
-
| /analyze-repository [--------------------] 0% 0/5.0K
|
|
99
|
-
| /README [--------------------] 0% 0/1.0K
|
|
100
|
-
|
|
|
101
|
-
| 📝 Model shows actual Claude model used (critical for accurate cost tracking)
|
|
102
|
-
| 💡 Tip: Model may differ from your config - Claude routes requests intelligently
|
|
103
|
-
| Status Name Model Duration Overall Tokens Cache Cr Cache Rd Tools Budget
|
|
104
|
-
| -------- ------------------------------ ---------- ---------- -------- -------- -------- -------- ------ ----------
|
|
105
|
-
| 🏃 analyze-repo opus4 5.1s 0 0 0 0 0 0/5.0K
|
|
106
|
-
| 🏃 help-overview sonnet4 0.0s 0 0 0 0 0 0/1.0K
|
|
107
|
-
+================================+
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
## Budget Warning Only
|
|
111
|
-
```
|
|
112
|
-
zen --overall-token-budget 10000
|
|
113
|
-
```
|
|
114
|
-
```
|
|
115
|
-
+=== STATUS REPORT [14:47:44] ===+
|
|
116
|
-
| Total: 2 instances
|
|
117
|
-
| Running: 2, Completed: 0, Failed: 0, Pending: 0
|
|
118
|
-
| Tokens: 32.2K total, 32.2K cached | Median: 32.2K | Tools: 1
|
|
119
|
-
| 💰 Cost: $0.0818 total, $0.0409 avg/instance | Pricing: Claude compliant
|
|
120
|
-
|
|
|
121
|
-
| TOKEN BUDGET STATUS |
|
|
122
|
-
| Overall: [####################] 100% 32.2K/10.0K
|
|
123
|
-
| Command Budgets:
|
|
124
|
-
| /analyze-repository [####################] 100% 32.2K/5.0K
|
|
125
|
-
| /README [--------------------] 0% 0/1.0K
|
|
126
|
-
|
|
|
127
|
-
| 📝 Model shows actual Claude model used (critical for accurate cost tracking)
|
|
128
|
-
| 💡 Tip: Model may differ from your config - Claude routes requests intelligently
|
|
129
|
-
| Status Name Model Duration Overall Tokens Cache Cr Cache Rd Tools Budget
|
|
130
|
-
| -------- ------------------------------ ---------- ---------- -------- -------- -------- -------- ------ ----------
|
|
131
|
-
| 🏃 analyze-repo 35sonnet 10.1s 32.2K 5 20.9K 11.4K 1 32.2K/5.0K
|
|
132
|
-
| 🏃 help-overview opus4 5.0s 0 0 0 0 0 0/1.0K
|
|
133
|
-
+================================+
|
|
134
|
-
|
|
135
|
-
+=== TOOL USAGE DETAILS ===+
|
|
136
|
-
| Tool Name Uses Tokens Cost ($) Used By
|
|
137
|
-
| -------------------- -------- ---------- ---------- -----------------------------------
|
|
138
|
-
| Bash 1 33 0.0001 analyze-repo(1 uses, 33 tok)
|
|
139
|
-
| -------------------- -------- ---------- ---------- -----------------------------------
|
|
140
|
-
| TOTAL 1 33 0.0001
|
|
141
|
-
+===============================================================================================+
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
## Budget Block
|
|
145
|
-
```
|
|
146
|
-
zen --overall-token-budget 10000 --budget-enforcement-mode block
|
|
147
|
-
```
|
|
148
|
-
```
|
|
149
|
-
2025-09-18 14:50:42,050 - zen_orchestrator - INFO - 💰 BUDGET UPDATE [analyze-repo]: Recording 32240 tokens for command '/analyze-repository'
|
|
150
|
-
2025-09-18 14:50:42,050 - zen_orchestrator - INFO - 📊 BUDGET STATE [analyze-repo]: /analyze-repository now at 32240/5000 tokens (644.8%)
|
|
151
|
-
2025-09-18 14:50:42,050 - zen_orchestrator - ERROR - 🚫 🔴 RUNTIME TERMINATION: Runtime budget violation for analyze-repo: Overall budget exceeded: 32240/10000 tokens
|
|
152
|
-
2025-09-18 14:50:42,050 - zen_orchestrator - INFO - Terminating instance analyze-repo (PID: 88916): Terminated due to budget violation - Overall budget exceeded: 32240/10000 tokens
|
|
153
|
-
2025-09-18 14:50:42,050 - zen_orchestrator - INFO - Sent SIGTERM to analyze-repo (PID: 88916)
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
```
|
|
157
|
-
+=== FINAL STATUS [14:50:57] ===+
|
|
158
|
-
| Total: 2 instances
|
|
159
|
-
| Running: 0, Completed: 0, Failed: 2, Pending: 0
|
|
160
|
-
| Tokens: 85.6K total, 85.2K cached | Median: 42.8K | Tools: 1
|
|
161
|
-
| 💰 Cost: $0.0889 total, $0.0444 avg/instance | Pricing: Claude compliant
|
|
162
|
-
|
|
|
163
|
-
| TOKEN BUDGET STATUS |
|
|
164
|
-
| Overall: [####################] 100% 85.6K/10.0K
|
|
165
|
-
| Command Budgets:
|
|
166
|
-
| /analyze-repository [####################] 100% 48.4K/5.0K
|
|
167
|
-
| /README [####################] 100% 37.2K/1.0K
|
|
168
|
-
|
|
|
169
|
-
| 📝 Model shows actual Claude model used (critical for accurate cost tracking)
|
|
170
|
-
| 💡 Tip: Model may differ from your config - Claude routes requests intelligently
|
|
171
|
-
| Status Name Model Duration Overall Tokens Cache Cr Cache Rd Tools Budget
|
|
172
|
-
| -------- ------------------------------ ---------- ---------- -------- -------- -------- -------- ------ ----------
|
|
173
|
-
| ❌ analyze-repo sonnet4 22.5s 48.4K 31 16.1K 32.2K 1 48.4K/5.0K
|
|
174
|
-
| ❌ help-overview 35sonnet 16.2s 37.2K 422 0 36.8K 0 37.2K/1.0K
|
|
175
|
-
+===============================+
|
|
176
|
-
|
|
177
|
-
+=== TOOL USAGE DETAILS ===+
|
|
178
|
-
| Tool Name Uses Tokens Cost ($) Used By
|
|
179
|
-
| -------------------- -------- ---------- ---------- -----------------------------------
|
|
180
|
-
| Task 1 348 0.0010 analyze-repo(1 uses, 348 tok)
|
|
181
|
-
| -------------------- -------- ---------- ---------- -----------------------------------
|
|
182
|
-
| TOTAL 1 348 0.0010
|
|
183
|
-
+===============================================================================================+
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
# Example Start At
|
|
187
|
-
```
|
|
188
|
-
zen --start-at "2am"
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
```
|
|
192
|
-
...
|
|
193
|
-
2025-09-18 14:54:29,863 - zen_orchestrator - INFO - Added instance: analyze-repo - Analyze the repository structure and codebase
|
|
194
|
-
2025-09-18 14:54:29,863 - zen_orchestrator - INFO - Added instance: help-overview - Show project README and overview information
|
|
195
|
-
|
|
196
|
-
2025-09-18 14:54:29,863 - zen_orchestrator - INFO - Orchestration scheduled to start at: 2025-09-19 02:00:00
|
|
197
|
-
2025-09-18 14:54:29,863 - zen_orchestrator - INFO - Waiting 39930.1 seconds (11.1 hours) until start time...
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
# Example Command
|
|
201
|
-
**
|
|
202
|
-
```
|
|
203
|
-
zen "/runtests"
|
|
204
|
-
```
|
|
205
|
-
```
|
|
206
|
-
...
|
|
207
|
-
2025-09-18 14:56:18,478 - zen_orchestrator - INFO - Added instance: direct-runtests-3337c2c5 - Direct execution of /runtests
|
|
208
|
-
2025-09-18 14:56:18,478 - zen_orchestrator - INFO - Starting Claude Code instance orchestration
|
|
209
|
-
2025-09-18 14:56:18,478 - zen_orchestrator - INFO - Starting 1 instances with 5.0s delay between launches (timeout: 10000s each)
|
|
210
|
-
2025-09-18 14:56:18,478 - zen_orchestrator - INFO - Now starting instance 'direct-runtests-3337c2c5' (after 0.0s delay)
|
|
211
|
-
|
|
212
|
-
```
|
|
213
|
-
# Example Config (Recommended Usage)
|
|
214
|
-
|
|
215
|
-
Your JSON file as `path\my_config.json`
|
|
216
|
-
```JSON
|
|
217
|
-
{
|
|
218
|
-
"instances": [
|
|
219
|
-
{
|
|
220
|
-
"name": "analyze-repository",
|
|
221
|
-
"command": "/analyze-repository; Spawn three subagents to understand how the information at this website is used in the zen directory. https://docs.claude.com/en/docs/about-claude/pricing#tool-use-pricing.",
|
|
222
|
-
"description": "Reads and understands the required portion of the repository",
|
|
223
|
-
"permission_mode": "bypassPermissions",
|
|
224
|
-
"output_format": "stream-json",
|
|
225
|
-
"max_tokens_per_command": 5000
|
|
226
|
-
}
|
|
227
|
-
]
|
|
228
|
-
}
|
|
229
|
-
```
|
|
230
|
-
```
|
|
231
|
-
zen --config path\my_config.json
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
```
|
|
235
|
-
...
|
|
236
|
-
|
|
237
|
-
2025-09-18 15:00:09,645 - zen_orchestrator - INFO - Loading config from config_example.json
|
|
238
|
-
|
|
239
|
-
2025-09-18 15:00:09,657 - zen_orchestrator - INFO - 🎯 Token transparency pricing engine enabled - Claude pricing compliance active
|
|
240
|
-
|
|
241
|
-
2025-09-18 15:00:09,657 - zen_orchestrator - WARNING - Command '/analyze-repository; Spawn three subagents to understand how the information at this website is used in the zen directory. https://docs.claude.com/en/docs/about-claude/pricing#tool-use-pricing.' not found in available commands
|
|
242
|
-
|
|
243
|
-
2025-09-18 15:00:09,657 - zen_orchestrator - INFO - Available commands: /clear, /compact, /help
|
|
244
|
-
|
|
245
|
-
2025-09-18 15:00:09,657 - zen_orchestrator - INFO - Added instance: analyze-repository - Reads and understands the required portion of the repository
|
|
246
|
-
|
|
247
|
-
2025-09-18 15:00:09,657 - zen_orchestrator - INFO - Starting Claude Code instance orchestration
|
|
248
|
-
|
|
249
|
-
2025-09-18 15:00:09,659 - zen_orchestrator - INFO - Starting 1 instances with 5.0s delay between launches (timeout: 10000s each)
|
|
250
|
-
|
|
251
|
-
2025-09-18 15:00:09,659 - zen_orchestrator - INFO - Now starting instance 'analyze-repository' (after 0.0s delay)
|
|
252
|
-
|
|
253
|
-
2025-09-18 15:00:09,659 - zen_orchestrator - INFO - Starting instance: analyze-repository
|
|
254
|
-
|
|
255
|
-
2025-09-18 15:00:09,665 - zen_orchestrator - INFO - Command: claude.CMD -p /analyze-repository; Spawn three subagents to understand how the information at this website is used in the zen directory. https://docs.claude.com/en/docs/about-claude/pricing#tool-use-pricing. --output-format=stream-json --permission-mode=bypassPermissions --verbose
|
|
256
|
-
|
|
257
|
-
2025-09-18 15:00:09,738 - zen_orchestrator - INFO - Permission mode: bypassPermissions (Platform: Windows)
|
|
258
|
-
2025-09-18 15:00:09,746 - zen_orchestrator - INFO - Instance analyze-repository started with PID 672
|
|
259
|
-
|
|
260
|
-
+=== STATUS REPORT [15:00:14] ===+
|
|
261
|
-
| Total: 1 instances
|
|
262
|
-
| Running: 1, Completed: 0, Failed: 0, Pending: 0
|
|
263
|
-
| Tokens: 0 total, 0 cached | Median: 0 | Tools: 0
|
|
264
|
-
| 💰 Cost: $0.0000 total, $0.0000 avg/instance | Pricing: Claude compliant
|
|
265
|
-
|
|
|
266
|
-
| 📝 Model shows actual Claude model used (critical for accurate cost tracking)
|
|
267
|
-
| 💡 Tip: Model may differ from your config - Claude routes requests intelligently
|
|
268
|
-
| Status Name Model Duration Overall Tokens Cache Cr Cache Rd Tools Budget
|
|
269
|
-
| -------- ------------------------------ ---------- ---------- -------- -------- -------- -------- ------ ----------
|
|
270
|
-
| 🏃 analyze-repository opus4 5.1s 0 0 0 0 0 -
|
|
271
|
-
+================================+
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
+=== STATUS REPORT [15:00:19] ===+
|
|
275
|
-
| Total: 1 instances
|
|
276
|
-
| Running: 1, Completed: 0, Failed: 0, Pending: 0
|
|
277
|
-
| Tokens: 14.7K total, 14.7K cached | Median: 14.7K | Tools: 0
|
|
278
|
-
| 💰 Cost: $0.0798 total, $0.0798 avg/instance | Pricing: Claude compliant
|
|
279
|
-
| Status Name Model Duration Overall Tokens Cache Cr Cache Rd Tools Budget
|
|
280
|
-
| -------- ------------------------------ ---------- ---------- -------- -------- -------- -------- ------ ----------
|
|
281
|
-
| 🏃 analyze-repository opus4 10.1s 14.7K 6 3.3K 11.4K 0 -
|
|
282
|
-
+================================+
|
|
283
|
-
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
## Inspiration and background
|
|
288
|
-
While developing Netra Apex (commercial product)
|
|
289
|
-
our team has been running 100s of parallel claude code instances.
|
|
290
|
-
During that process we got annoyed at the "cognitive overhead"
|
|
291
|
-
of each having 10s of terminals open per machine and scrolling mountains of text.
|
|
292
|
-
Did the `/command` work or not?
|
|
293
|
-
|
|
294
|
-
What started as a simple way to make that process more peaceful turned into something we believe will be useful to the community.
|
|
295
|
-
|
|
296
|
-
Further, as usage limits become more restrictive, getting up at odd hours just to feed the beast got old fast. So we added scheduling to run it at pre-defined times.
|
|
297
|
-
|
|
298
|
-
Surprisingly, the duration that a command ran and it's presumed difficulty, often had little correlation with actual token usage.
|
|
299
|
-
"Simple" git operations would sometimes eat 10x as many as complex issue resolution commands.
|
|
300
|
-
|
|
301
|
-
The market is moving quickly, codex is getting better and other Code CLIs are coming. How effective a code factory is matters. This V1 alpha is just the start of codifying code CLI dev practices and progressing from alchemy to engineering.
|
|
302
|
-
|
|
303
|
-
For more power, try Zen with Netra Apex for the most effective usage and control of business AI spend.
|
|
304
|
-
|
|
305
|
-
## Limitations
|
|
306
|
-
|
|
307
|
-
### Budget Enforcement Behavior
|
|
308
|
-
|
|
309
|
-
**Important:**
|
|
310
|
-
|
|
311
|
-
- **Local Monitoring Only**: Budgets defined in `json` configs or command-line flags are tracked locally by Zen.
|
|
312
|
-
Zen cannot prevent the underlying CLI from consuming tokens beyond the limit in some cases.
|
|
313
|
-
For example if a request is made when it is under budget, that single request may exceed the budget. In `block` mode the *next* request will be stopped.
|
|
314
|
-
- **Budget Exceeded Behavior**:
|
|
315
|
-
- `warn` mode: Zen logs warnings but continues execution
|
|
316
|
-
- `block` mode: Zen prevents running new instances or halts in progress commands, depending on the nature of the budget config.
|
|
317
|
-
- **Token Counting**: Budget calculations are based on estimates and may not match exact billing from Claude/Codex
|
|
318
|
-
|
|
319
|
-
### Target Audience and Use Cases
|
|
320
|
-
|
|
321
|
-
Zen is designed for internal developer productivity and automation workflows and is *not* suitable for all use cases.
|
|
322
|
-
|
|
323
|
-
It is generally expected that you already familiar with claude code
|
|
324
|
-
in order to get the most value out of Zen.
|
|
325
|
-
|
|
326
|
-
**✅ Supported Use Cases:**
|
|
327
|
-
- Internal development workflows and automation
|
|
328
|
-
- Parallel execution of development tasks
|
|
329
|
-
- CI/CD integration for development teams
|
|
330
|
-
- Budget and cost control for Claude
|
|
331
|
-
|
|
332
|
-
## Installation
|
|
333
|
-
|
|
334
|
-
### Default Method: pipx (Recommended for ALL Users)
|
|
335
|
-
|
|
336
|
-
Pipx automatically handles PATH configuration and creates an isolated environment, preventing dependency conflicts.
|
|
337
|
-
|
|
338
|
-
#### Step 1: Install pipx
|
|
339
|
-
```bash
|
|
340
|
-
# Windows
|
|
341
|
-
pip install --user pipx
|
|
342
|
-
python -m pipx ensurepath
|
|
343
|
-
|
|
344
|
-
# macOS
|
|
345
|
-
brew install pipx
|
|
346
|
-
pipx ensurepath
|
|
347
|
-
|
|
348
|
-
# Linux (Ubuntu/Debian)
|
|
349
|
-
sudo apt update
|
|
350
|
-
sudo apt install pipx
|
|
351
|
-
pipx ensurepath
|
|
352
|
-
|
|
353
|
-
# Linux (Other)
|
|
354
|
-
pip install --user pipx
|
|
355
|
-
pipx ensurepath
|
|
356
|
-
```
|
|
357
|
-
|
|
358
|
-
**Note:** Restart your terminal after running `pipx ensurepath`
|
|
359
|
-
|
|
360
|
-
#### Step 2: Install zen
|
|
361
|
-
```bash
|
|
362
|
-
# From PyPI
|
|
363
|
-
pipx install netra-zen
|
|
364
|
-
|
|
365
|
-
# For local development (editable mode)
|
|
366
|
-
cd zen/
|
|
367
|
-
pipx install --editable .
|
|
368
|
-
|
|
369
|
-
# Verify installation
|
|
370
|
-
zen --help
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
### Alternative: pip (Manual PATH Configuration Required)
|
|
374
|
-
|
|
375
|
-
⚠️ **Warning:** Using pip directly often results in PATH issues. We strongly recommend pipx instead.
|
|
376
|
-
|
|
377
|
-
```bash
|
|
378
|
-
pip install netra-zen
|
|
379
|
-
|
|
380
|
-
# If 'zen' command not found, you'll need to:
|
|
381
|
-
# Option 1: Use Python module directly
|
|
382
|
-
python -m zen_orchestrator --help
|
|
383
|
-
|
|
384
|
-
# Option 2: Manually add to PATH (see Troubleshooting)
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
## Understanding the Model Column in Status Reports
|
|
388
|
-
|
|
389
|
-
### Model Column Behavior
|
|
390
|
-
|
|
391
|
-
The **Model** column in Zen's status display shows the **actual model used** by Claude Code for each API response, not necessarily the model you configured in your settings.
|
|
392
|
-
|
|
393
|
-
**Key Points:**
|
|
394
|
-
- **Cost Tracking Value**: Knowing the actual model is critical for accurate cost calculation since different models have vastly different pricing (e.g., Opus costs 5x more than Sonnet)
|
|
395
|
-
- **Dynamic Detection**: Zen automatically detects the model from Claude's API responses in real-time
|
|
396
|
-
|
|
397
|
-
**Example Status Display:**
|
|
398
|
-
```
|
|
399
|
-
║ Status Name Model Duration Overall Tokens Budget
|
|
400
|
-
║ ✅ analyze-code 35sonnet 2m15s 45.2K 2.1K 85% used
|
|
401
|
-
║ 🏃 optimize-perf opus4 1m30s 12.8K 800 45% used
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
This transparency helps you understand your actual AI spend and make informed decisions about model usage.
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
### Step 3: Generate with AI
|
|
408
|
-
|
|
409
|
-
1. Copy your customized prompt
|
|
410
|
-
2. Paste it into ChatGPT, Claude, or your preferred LLM
|
|
411
|
-
3. Save the generated JSON as `customer_feedback.json`
|
|
412
|
-
4. Run: `zen --config customer_feedback.json`
|
|
413
|
-
|
|
414
|
-
## Understanding Configuration Structure
|
|
415
|
-
|
|
416
|
-
Every Zen configuration has the same basic structure:
|
|
417
|
-
|
|
418
|
-
```json
|
|
419
|
-
{
|
|
420
|
-
"// Description": "What this workflow accomplishes",
|
|
421
|
-
"// Use Case": "When to use this configuration",
|
|
422
|
-
|
|
423
|
-
"instances": [
|
|
424
|
-
{
|
|
425
|
-
"command": "/command || prompt",
|
|
426
|
-
"permission_mode": "bypassPermissions", // Default
|
|
427
|
-
"output_format": "stream-json", // Default
|
|
428
|
-
"max_tokens_per_command": 12000, // Optional
|
|
429
|
-
"allowed_tools": ["Read", "Write", "Edit", "Task"], // Optional
|
|
430
|
-
// Other optional features
|
|
431
|
-
}//,
|
|
432
|
-
//{
|
|
433
|
-
// next instance
|
|
434
|
-
//}
|
|
435
|
-
//... series of instances
|
|
436
|
-
]
|
|
437
|
-
}
|
|
438
|
-
```
|
|
439
|
-
|
|
440
|
-
### Key Configuration Elements
|
|
441
|
-
|
|
442
|
-
| Element | Purpose | Best Practice |
|
|
443
|
-
|---------|---------|---------------|
|
|
444
|
-
| `command` | Task specification | Can use existing /commands or any string literal input |
|
|
445
|
-
| `max_tokens_per_command` | Token budget | Allocate based on complexity |
|
|
446
|
-
| `allowed_tools` | Tool permissions | Grant minimal necessary tools |
|
|
447
|
-
|
|
448
|
-
For Output Truncation control: `--max-console-lines` and `--max-line-length` parameters, or redirect output to files
|
|
449
|
-
|
|
450
|
-
### Scheduling
|
|
451
|
-
|
|
452
|
-
Schedule to run later.
|
|
453
|
-
This helps you get the most value out of your claude max subscription.
|
|
454
|
-
|
|
455
|
-
```bash
|
|
456
|
-
# Start in 2 hours
|
|
457
|
-
zen --config my_config.json --start-at "2h"
|
|
458
|
-
|
|
459
|
-
# Start at specific time
|
|
460
|
-
zen --config my_config.json --start-at "14:30"
|
|
461
|
-
|
|
462
|
-
# Start in 30 minutes
|
|
463
|
-
zen --config my_config.json --start-at "30m"
|
|
464
|
-
```
|
|
465
|
-
|
|
466
|
-
## Expected questions
|
|
467
|
-
|
|
468
|
-
### 1. Do I have to use /commands?
|
|
469
|
-
- No. You can just put your string query (prompt) and it works the same.
|
|
470
|
-
- It does seem to be a best practice though to version controlled `/commands`.
|
|
471
|
-
|
|
472
|
-
### 2. Does this replace using Claude command directly?
|
|
473
|
-
- No. At least not yet fully.
|
|
474
|
-
- As we primarily using structured commands, internally we see 80%+ of our usage through Zen.
|
|
475
|
-
- Ad hoc questions or validating if a command is working as expected for now is better through Claude directly.
|
|
476
|
-
|
|
477
|
-
### 3. What does this assume?
|
|
478
|
-
- You have claude code installed, authenticated, and configured already.
|
|
479
|
-
|
|
480
|
-
### 4. How do I know if it's working?
|
|
481
|
-
- Each command returns fairly clear overall statuses.
|
|
482
|
-
- Budget states etc. are logged.
|
|
483
|
-
- You can also see the duration and token usage.
|
|
484
|
-
- By default, each command outputs a truncated version of the output to the console.
|
|
485
|
-
- You can optionally choose to save a report of all output to .json
|
|
486
|
-
- Our usage is heavily integrated with github, we use git issues as the visual output
|
|
487
|
-
and notification system for most work. This means regardless of where Zen is running
|
|
488
|
-
you can see the results wherever you access git. This is as easy as adding `gh` instructions (the cli + token assumed to be present) to your commands.
|
|
489
|
-
|
|
490
|
-
### 5. Data privacy?
|
|
491
|
-
At this moment no data is collected.
|
|
492
|
-
Our intent is to add an optional system where non-PII usage data is sent to Netra for exclusively aggregated metadata level use to help make our spend management system better. (So you can get more from your AI spend!)
|
|
493
|
-
|
|
494
|
-
## 6. What about the UI/UX?
|
|
495
|
-
There is a time and a place for wanting to have multiple windows and git trees open.
|
|
496
|
-
Zen's intent is the opposite: make running `n` code clis more peaceful.
|
|
497
|
-
Why activate your "giga-brain" when you can run one command instead?
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
## Zen --help
|
|
501
|
-
```zen --help```
|
|
502
|
-
yields:
|
|
503
|
-
```
|
|
504
|
-
usage: zen [-h] [--workspace WORKSPACE] [--config CONFIG] [--dry-run] [--list-commands] [--inspect-command INSPECT_COMMAND]
|
|
505
|
-
[--output-format {json,stream-json}] [--timeout TIMEOUT] [--max-console-lines MAX_CONSOLE_LINES] [--quiet]
|
|
506
|
-
[--startup-delay STARTUP_DELAY] [--max-line-length MAX_LINE_LENGTH] [--status-report-interval STATUS_REPORT_INTERVAL]
|
|
507
|
-
[--start-at START_AT] [--overall-token-budget OVERALL_TOKEN_BUDGET] [--command-budget COMMAND_BUDGET]
|
|
508
|
-
[--budget-enforcement-mode {warn,block}] [--disable-budget-visuals]
|
|
509
|
-
|
|
510
|
-
Claude Code Instance Orchestrator
|
|
511
|
-
|
|
512
|
-
options:
|
|
513
|
-
-h, --help show this help message and exit
|
|
514
|
-
--workspace WORKSPACE
|
|
515
|
-
Workspace directory (default: current directory)
|
|
516
|
-
--config CONFIG Custom instance configuration file
|
|
517
|
-
--dry-run Show commands without running
|
|
518
|
-
--list-commands List all available slash commands and exit
|
|
519
|
-
--inspect-command INSPECT_COMMAND
|
|
520
|
-
Inspect a specific slash command and exit
|
|
521
|
-
--output-format {json,stream-json}
|
|
522
|
-
Output format for Claude instances (default: stream-json)
|
|
523
|
-
--timeout TIMEOUT Timeout in seconds for each instance (default: 10000)
|
|
524
|
-
--max-console-lines MAX_CONSOLE_LINES
|
|
525
|
-
Maximum recent lines to show per instance on console (default: 5)
|
|
526
|
-
--quiet Minimize console output, show only errors and final summaries
|
|
527
|
-
--startup-delay STARTUP_DELAY
|
|
528
|
-
Delay in seconds between launching each instance (default: 5.0)
|
|
529
|
-
--max-line-length MAX_LINE_LENGTH
|
|
530
|
-
Maximum characters per line in console output (default: 500)
|
|
531
|
-
--status-report-interval STATUS_REPORT_INTERVAL
|
|
532
|
-
Seconds between rolling status reports (default: 5)
|
|
533
|
-
--start-at START_AT Schedule orchestration to start at specific time. Examples: '2h' (2 hours from now), '30m' (30 minutes),
|
|
534
|
-
'14:30' (2:30 PM today), '1am' (1 AM today/tomorrow)
|
|
535
|
-
--overall-token-budget OVERALL_TOKEN_BUDGET
|
|
536
|
-
Global token budget for the entire session.
|
|
537
|
-
--command-budget COMMAND_BUDGET
|
|
538
|
-
Per-command budget in format: '/command_name=limit'. Can be used multiple times.
|
|
539
|
-
--budget-enforcement-mode {warn,block}
|
|
540
|
-
Action to take when a budget is exceeded: 'warn' (log and continue) or 'block' (prevent new instances).
|
|
541
|
-
--disable-budget-visuals
|
|
542
|
-
Disable budget visualization in status reports
|
|
543
|
-
|
|
544
|
-
```
|
|
545
|
-
|
|
546
|
-
## Requirements
|
|
547
|
-
|
|
548
|
-
- Python 3.8+
|
|
549
|
-
- Claude Code CLI
|
|
550
|
-
- Dependencies in requirements.txt
|
|
551
|
-
|
|
552
|
-
## Logging and Output
|
|
553
|
-
|
|
554
|
-
- **Console Output**: All logs and execution results are displayed in the console
|
|
555
|
-
- **No File Logging**: ZEN does not write logs to files by default
|
|
556
|
-
- **Capturing Output**: To save execution logs, use output redirection:
|
|
557
|
-
```bash
|
|
558
|
-
zen --config tasks.json > execution.log 2>&1
|
|
559
|
-
```
|
|
560
|
-
|
|
561
|
-
## Testing
|
|
562
|
-
|
|
563
|
-
```bash
|
|
564
|
-
cd tests/
|
|
565
|
-
python test_runner.py
|
|
566
|
-
```
|
|
567
|
-
|
|
568
|
-
## Basic Usage
|
|
569
|
-
|
|
570
|
-
### Command Execution
|
|
571
|
-
Execute commands directly without config files:
|
|
572
|
-
```bash
|
|
573
|
-
# Execute a single command directly
|
|
574
|
-
zen "/my-existing-claude-command"
|
|
575
|
-
|
|
576
|
-
# Execute with config (recommended usage pattern)
|
|
577
|
-
zen --config /my-config.json
|
|
578
|
-
|
|
579
|
-
# Execute with custom workspace
|
|
580
|
-
zen "/analyze-code" --workspace ~/my-project
|
|
581
|
-
|
|
582
|
-
# Execute with token budget
|
|
583
|
-
zen "/complex-analysis" --overall-token-budget 5000
|
|
584
|
-
|
|
585
|
-
# Execute with custom instance name
|
|
586
|
-
zen "/debug-issue" --instance-name "debug-session"
|
|
587
|
-
|
|
588
|
-
# Execute with session continuity
|
|
589
|
-
zen "/optimize-performance" --session-id "perf-session-1"
|
|
590
|
-
|
|
591
|
-
# Start in 2 hours
|
|
592
|
-
zen --config my_config.json --start-at "2h"
|
|
593
|
-
|
|
594
|
-
# Start at specific time
|
|
595
|
-
zen --config my_config.json --start-at "14:30"
|
|
596
|
-
|
|
597
|
-
```
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
### Quick Test
|
|
601
|
-
```bash
|
|
602
|
-
# List available commands (auto-detects workspace)
|
|
603
|
-
zen --list-commands
|
|
604
|
-
|
|
605
|
-
# Dry run to see what would be executed (auto-detects workspace)
|
|
606
|
-
zen --dry-run
|
|
607
|
-
|
|
608
|
-
# Run with default configuration (uses actual slash commands from workspace)
|
|
609
|
-
zen
|
|
610
|
-
```
|
|
611
|
-
|
|
612
|
-
### Workspace Management
|
|
613
|
-
```bash
|
|
614
|
-
# Auto-detect workspace (looks for project root with .git, .claude, etc.)
|
|
615
|
-
zen --dry-run
|
|
616
|
-
|
|
617
|
-
# Use specific workspace (override auto-detection)
|
|
618
|
-
zen --workspace ~/projects/myapp
|
|
619
|
-
|
|
620
|
-
# With custom timeout
|
|
621
|
-
zen --timeout 300 --workspace ~/projects/myapp
|
|
622
|
-
```
|
|
623
|
-
|
|
624
|
-
### Token Budget Control
|
|
625
|
-
```bash
|
|
626
|
-
# Set overall budget
|
|
627
|
-
zen --overall-token-budget 100000
|
|
628
|
-
|
|
629
|
-
# Set per-command budgets
|
|
630
|
-
zen --command-budget "/analyze=50000" --command-budget "/optimize=30000"
|
|
631
|
-
|
|
632
|
-
# Budget enforcement modes
|
|
633
|
-
zen --budget-enforcement-mode block # Stop when exceeded
|
|
634
|
-
zen --budget-enforcement-mode warn # Warn but continue
|
|
635
|
-
```
|
|
636
|
-
|
|
637
|
-
### Scheduled Execution
|
|
638
|
-
```bash
|
|
639
|
-
# Start in 2 hours
|
|
640
|
-
zen --start-at "2h"
|
|
641
|
-
|
|
642
|
-
# Start at specific time
|
|
643
|
-
zen --start-at "14:30" # 2:30 PM today
|
|
644
|
-
zen --start-at "1am" # 1 AM tomorrow
|
|
645
|
-
```
|
|
646
|
-
|
|
647
|
-
### Execution Mode Precedence
|
|
648
|
-
Zen supports three execution modes with clear precedence rules:
|
|
649
|
-
|
|
650
|
-
1. **Direct Command** (Highest Priority)
|
|
651
|
-
```bash
|
|
652
|
-
zen "/analyze-code" # Executes direct command
|
|
653
|
-
```
|
|
654
|
-
|
|
655
|
-
2. **Config File** (Medium Priority)
|
|
656
|
-
```bash
|
|
657
|
-
zen --config my-config.json # Uses config file
|
|
658
|
-
```
|
|
659
|
-
|
|
660
|
-
3. **Default Instances** (Lowest Priority)
|
|
661
|
-
```bash
|
|
662
|
-
zen # Uses built-in default commands
|
|
663
|
-
```
|
|
664
|
-
|
|
665
|
-
## Other Features
|
|
666
|
-
|
|
667
|
-
### Parallel Execution Control
|
|
668
|
-
```bash
|
|
669
|
-
# Control startup delay between instances
|
|
670
|
-
zen --startup-delay 30.0 # seconds between launches
|
|
671
|
-
|
|
672
|
-
# Limit console output
|
|
673
|
-
zen --max-console-lines 10
|
|
674
|
-
zen --max-line-length 200
|
|
675
|
-
```
|
|
676
|
-
|
|
677
|
-
### Output Formats
|
|
678
|
-
```bash
|
|
679
|
-
# JSON output
|
|
680
|
-
zen --output-format json
|
|
681
|
-
|
|
682
|
-
# Stream JSON (default)
|
|
683
|
-
zen --output-format stream-json
|
|
684
|
-
```
|
|
685
|
-
|
|
686
|
-
### Quiet Mode
|
|
687
|
-
```bash
|
|
688
|
-
# Minimal output - only errors and summary
|
|
689
|
-
zen --quiet
|
|
690
|
-
```
|
|
691
|
-
|
|
692
|
-
### Status Reporting
|
|
693
|
-
```bash
|
|
694
|
-
# Change status report interval
|
|
695
|
-
zen --status-report-interval 30 # Every 30 seconds
|
|
696
|
-
```
|
|
697
|
-
|
|
698
|
-
## Environment Variables
|
|
699
|
-
|
|
700
|
-
```bash
|
|
701
|
-
# Set default workspace
|
|
702
|
-
export ZEN_WORKSPACE="~/projects"
|
|
703
|
-
|
|
704
|
-
# Set default config
|
|
705
|
-
export ZEN_CONFIG="~/configs/zen-default.json"
|
|
706
|
-
|
|
707
|
-
# Enable debug logging
|
|
708
|
-
export ZEN_DEBUG="true"
|
|
709
|
-
```
|
|
710
|
-
|
|
711
|
-
## Troubleshooting
|
|
712
|
-
|
|
713
|
-
### Command not found
|
|
714
|
-
|
|
715
|
-
#### If using pipx (recommended):
|
|
716
|
-
```bash
|
|
717
|
-
# Ensure PATH is configured
|
|
718
|
-
pipx ensurepath
|
|
719
|
-
|
|
720
|
-
# Restart terminal, then verify
|
|
721
|
-
zen --version
|
|
722
|
-
```
|
|
723
|
-
|
|
724
|
-
### Permission denied
|
|
725
|
-
```bash
|
|
726
|
-
# Make sure scripts are executable
|
|
727
|
-
chmod +x $(which zen)
|
|
728
|
-
```
|
|
729
|
-
|
|
730
|
-
### Module not found
|
|
731
|
-
```bash
|
|
732
|
-
# Reinstall with dependencies
|
|
733
|
-
pip install --force-reinstall netra-zen
|
|
734
|
-
```
|
|
735
|
-
|
|
736
|
-
## Getting Help
|
|
737
|
-
|
|
738
|
-
```bash
|
|
739
|
-
# Show help
|
|
740
|
-
zen --help
|
|
741
|
-
|
|
742
|
-
# Inspect specific command
|
|
743
|
-
zen --inspect-command /analyze
|
|
744
|
-
|
|
745
|
-
# Visit documentation
|
|
746
|
-
# https://github.com/netra-systems/zen
|
|
747
|
-
```
|
|
748
|
-
|
|
749
|
-
### Known Issues
|
|
750
|
-
|
|
751
|
-
**Token Budget Accuracy:**
|
|
752
|
-
- **Problem**: Budget calculations may not exactly match actual API billing
|
|
753
|
-
- **Cause**: Estimates based on local token counting vs. server-side billing
|
|
754
|
-
- **Workaround**: Use conservative budget limits and monitor actual usage through provider dashboards
|
|
755
|
-
|
|
756
|
-
**Configuration File Validation:**
|
|
757
|
-
- **Problem**: Limited validation of JSON configuration files
|
|
758
|
-
- **Impact**: Invalid configurations may cause runtime errors
|
|
759
|
-
- **Workaround**: Use `--dry-run` to validate configurations before execution
|
|
760
|
-
|
|
761
|
-
**Resource Cleanup:**
|
|
762
|
-
- **Problem**: Interrupted executions may leave background processes running
|
|
763
|
-
- **Workaround**: Monitor system processes and manually terminate if necessary
|
|
764
|
-
- **Planned Fix**: Improved signal handling and cleanup in future versions
|
|
765
|
-
|
|
766
|
-
## Example Configurations
|
|
767
|
-
|
|
768
|
-
See the included example files:
|
|
769
|
-
- `minimal_config.json` - Basic setup
|
|
770
|
-
- `config_example.json` - Standard configuration
|
|
771
|
-
- `netra_apex_tool_example.json` - Advanced integration
|
|
772
|
-
|
|
773
|
-
## Support
|
|
774
|
-
|
|
775
|
-
- GitHub Issues: https://github.com/netra-systems/zen/issues
|
|
776
|
-
- Documentation: https://github.com/netra-systems/zen/wiki
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: netra-zen
|
|
3
|
+
Version: 1.0.2
|
|
4
|
+
Summary: Multi-instance Claude orchestrator for parallel task execution
|
|
5
|
+
Home-page: https://github.com/netra-systems/zen
|
|
6
|
+
Author: Systems
|
|
7
|
+
Author-email: Netra Systems <pypi@netrasystems.ai>
|
|
8
|
+
License: MIT
|
|
9
|
+
Project-URL: Homepage, https://github.com/netra-systems/zen
|
|
10
|
+
Project-URL: Documentation, https://github.com/netra-systems/zen#readme
|
|
11
|
+
Project-URL: Repository, https://github.com/netra-systems/zen.git
|
|
12
|
+
Project-URL: Bug Tracker, https://github.com/netra-systems/zen/issues
|
|
13
|
+
Project-URL: Changelog, https://github.com/netra-systems/zen/blob/main/CHANGELOG.md
|
|
14
|
+
Keywords: claude,ai,orchestration,parallel,automation,llm,anthropic
|
|
15
|
+
Classifier: Development Status :: 4 - Beta
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: License :: Other/Proprietary License
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
25
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
26
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
27
|
+
Classifier: Topic :: System :: Distributed Computing
|
|
28
|
+
Requires-Python: >=3.8
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
License-File: LICENSE.md
|
|
31
|
+
Requires-Dist: PyYAML>=6.0
|
|
32
|
+
Requires-Dist: python-dateutil>=2.8.2
|
|
33
|
+
Provides-Extra: dev
|
|
34
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
35
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
|
|
36
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
37
|
+
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
38
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
39
|
+
Requires-Dist: mypy>=1.0.0; extra == "dev"
|
|
40
|
+
Provides-Extra: netra
|
|
41
|
+
Requires-Dist: netraoptimizer>=1.0.0; extra == "netra"
|
|
42
|
+
Dynamic: author
|
|
43
|
+
Dynamic: home-page
|
|
44
|
+
Dynamic: license-file
|
|
45
|
+
Dynamic: requires-python
|
|
46
|
+
|
|
47
|
+
# Zen
|
|
48
|
+
|
|
49
|
+
Zen runs multiple Code CLI instances for peaceful parallel task execution.
|
|
50
|
+
|
|
51
|
+
## What is Zen?
|
|
52
|
+
|
|
53
|
+
Zen allows you to:
|
|
54
|
+
- Run multiple headless Claude Code CLI instances simultaneously.
|
|
55
|
+
- Calm unified results (status, time, token usage)
|
|
56
|
+
- Relax **"5-hour limit reached"** lockout fears with easy token budget limits
|
|
57
|
+
- Get more value out of your Claude MAX subscription
|
|
58
|
+
with scheduling features. (`--run-at "2am"`)
|
|
59
|
+
- Learn more about how Claude Code uses tools and other inner workings
|
|
60
|
+
- Control usage and budget for groups of work or per command
|
|
61
|
+
|
|
62
|
+
Example portion of status report:
|
|
63
|
+
```
|
|
64
|
+
╔═══ STATUS REPORT [14:25:10] ═══╗
|
|
65
|
+
║ Total: 5 instances
|
|
66
|
+
║ Running: 3, Completed: 2, Failed: 0
|
|
67
|
+
║ Tokens: 32.1K total | Tools: 15
|
|
68
|
+
║ 💰 Cost: $0.0642 total
|
|
69
|
+
║
|
|
70
|
+
║ TOKEN BUDGET STATUS
|
|
71
|
+
║ Overall: [████████████----] 75% 32.1K/43.0K
|
|
72
|
+
║
|
|
73
|
+
║ Status Name Duration Tokens
|
|
74
|
+
║ ──────── ───────────────── ─────── ──────
|
|
75
|
+
║ ✅ security-reviewer 2m15s 8.5K
|
|
76
|
+
║ ✅ performance-analyzer 1m42s 7.2K
|
|
77
|
+
║ 🏃 architecture-reviewer 1m18s 6.5K
|
|
78
|
+
║ 🏃 test-coverage-analyst 0m45s 4.8K
|
|
79
|
+
║ ⏳ quality-synthesizer queued 0K
|
|
80
|
+
╚════════════════════════════════════════════╝
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Example Start
|
|
84
|
+
```
|
|
85
|
+
zen
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
+=== STATUS REPORT [14:47:39] ===+
|
|
90
|
+
| Total: 2 instances
|
|
91
|
+
| Running: 2, Completed: 0, Failed: 0, Pending: 0
|
|
92
|
+
| Tokens: 0 total, 0 cached | Median: 0 | Tools: 0
|
|
93
|
+
| 💰 Cost: $0.0000 total, $0.0000 avg/instance | Pricing: Claude compliant
|
|
94
|
+
|
|
|
95
|
+
| TOKEN BUDGET STATUS |
|
|
96
|
+
| Overall: [--------------------] 0% 0/10.0K
|
|
97
|
+
| Command Budgets:
|
|
98
|
+
| /analyze-repository [--------------------] 0% 0/5.0K
|
|
99
|
+
| /README [--------------------] 0% 0/1.0K
|
|
100
|
+
|
|
|
101
|
+
| 📝 Model shows actual Claude model used (critical for accurate cost tracking)
|
|
102
|
+
| 💡 Tip: Model may differ from your config - Claude routes requests intelligently
|
|
103
|
+
| Status Name Model Duration Overall Tokens Cache Cr Cache Rd Tools Budget
|
|
104
|
+
| -------- ------------------------------ ---------- ---------- -------- -------- -------- -------- ------ ----------
|
|
105
|
+
| 🏃 analyze-repo opus4 5.1s 0 0 0 0 0 0/5.0K
|
|
106
|
+
| 🏃 help-overview sonnet4 0.0s 0 0 0 0 0 0/1.0K
|
|
107
|
+
+================================+
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Budget Warning Only
|
|
111
|
+
```
|
|
112
|
+
zen --overall-token-budget 10000
|
|
113
|
+
```
|
|
114
|
+
```
|
|
115
|
+
+=== STATUS REPORT [14:47:44] ===+
|
|
116
|
+
| Total: 2 instances
|
|
117
|
+
| Running: 2, Completed: 0, Failed: 0, Pending: 0
|
|
118
|
+
| Tokens: 32.2K total, 32.2K cached | Median: 32.2K | Tools: 1
|
|
119
|
+
| 💰 Cost: $0.0818 total, $0.0409 avg/instance | Pricing: Claude compliant
|
|
120
|
+
|
|
|
121
|
+
| TOKEN BUDGET STATUS |
|
|
122
|
+
| Overall: [####################] 100% 32.2K/10.0K
|
|
123
|
+
| Command Budgets:
|
|
124
|
+
| /analyze-repository [####################] 100% 32.2K/5.0K
|
|
125
|
+
| /README [--------------------] 0% 0/1.0K
|
|
126
|
+
|
|
|
127
|
+
| 📝 Model shows actual Claude model used (critical for accurate cost tracking)
|
|
128
|
+
| 💡 Tip: Model may differ from your config - Claude routes requests intelligently
|
|
129
|
+
| Status Name Model Duration Overall Tokens Cache Cr Cache Rd Tools Budget
|
|
130
|
+
| -------- ------------------------------ ---------- ---------- -------- -------- -------- -------- ------ ----------
|
|
131
|
+
| 🏃 analyze-repo 35sonnet 10.1s 32.2K 5 20.9K 11.4K 1 32.2K/5.0K
|
|
132
|
+
| 🏃 help-overview opus4 5.0s 0 0 0 0 0 0/1.0K
|
|
133
|
+
+================================+
|
|
134
|
+
|
|
135
|
+
+=== TOOL USAGE DETAILS ===+
|
|
136
|
+
| Tool Name Uses Tokens Cost ($) Used By
|
|
137
|
+
| -------------------- -------- ---------- ---------- -----------------------------------
|
|
138
|
+
| Bash 1 33 0.0001 analyze-repo(1 uses, 33 tok)
|
|
139
|
+
| -------------------- -------- ---------- ---------- -----------------------------------
|
|
140
|
+
| TOTAL 1 33 0.0001
|
|
141
|
+
+===============================================================================================+
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Budget Block
|
|
145
|
+
```
|
|
146
|
+
zen --overall-token-budget 10000 --budget-enforcement-mode block
|
|
147
|
+
```
|
|
148
|
+
```
|
|
149
|
+
2025-09-18 14:50:42,050 - zen_orchestrator - INFO - 💰 BUDGET UPDATE [analyze-repo]: Recording 32240 tokens for command '/analyze-repository'
|
|
150
|
+
2025-09-18 14:50:42,050 - zen_orchestrator - INFO - 📊 BUDGET STATE [analyze-repo]: /analyze-repository now at 32240/5000 tokens (644.8%)
|
|
151
|
+
2025-09-18 14:50:42,050 - zen_orchestrator - ERROR - 🚫 🔴 RUNTIME TERMINATION: Runtime budget violation for analyze-repo: Overall budget exceeded: 32240/10000 tokens
|
|
152
|
+
2025-09-18 14:50:42,050 - zen_orchestrator - INFO - Terminating instance analyze-repo (PID: 88916): Terminated due to budget violation - Overall budget exceeded: 32240/10000 tokens
|
|
153
|
+
2025-09-18 14:50:42,050 - zen_orchestrator - INFO - Sent SIGTERM to analyze-repo (PID: 88916)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
+=== FINAL STATUS [14:50:57] ===+
|
|
158
|
+
| Total: 2 instances
|
|
159
|
+
| Running: 0, Completed: 0, Failed: 2, Pending: 0
|
|
160
|
+
| Tokens: 85.6K total, 85.2K cached | Median: 42.8K | Tools: 1
|
|
161
|
+
| 💰 Cost: $0.0889 total, $0.0444 avg/instance | Pricing: Claude compliant
|
|
162
|
+
|
|
|
163
|
+
| TOKEN BUDGET STATUS |
|
|
164
|
+
| Overall: [####################] 100% 85.6K/10.0K
|
|
165
|
+
| Command Budgets:
|
|
166
|
+
| /analyze-repository [####################] 100% 48.4K/5.0K
|
|
167
|
+
| /README [####################] 100% 37.2K/1.0K
|
|
168
|
+
|
|
|
169
|
+
| 📝 Model shows actual Claude model used (critical for accurate cost tracking)
|
|
170
|
+
| 💡 Tip: Model may differ from your config - Claude routes requests intelligently
|
|
171
|
+
| Status Name Model Duration Overall Tokens Cache Cr Cache Rd Tools Budget
|
|
172
|
+
| -------- ------------------------------ ---------- ---------- -------- -------- -------- -------- ------ ----------
|
|
173
|
+
| ❌ analyze-repo sonnet4 22.5s 48.4K 31 16.1K 32.2K 1 48.4K/5.0K
|
|
174
|
+
| ❌ help-overview 35sonnet 16.2s 37.2K 422 0 36.8K 0 37.2K/1.0K
|
|
175
|
+
+===============================+
|
|
176
|
+
|
|
177
|
+
+=== TOOL USAGE DETAILS ===+
|
|
178
|
+
| Tool Name Uses Tokens Cost ($) Used By
|
|
179
|
+
| -------------------- -------- ---------- ---------- -----------------------------------
|
|
180
|
+
| Task 1 348 0.0010 analyze-repo(1 uses, 348 tok)
|
|
181
|
+
| -------------------- -------- ---------- ---------- -----------------------------------
|
|
182
|
+
| TOTAL 1 348 0.0010
|
|
183
|
+
+===============================================================================================+
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
# Example Start At
|
|
187
|
+
```
|
|
188
|
+
zen --start-at "2am"
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
...
|
|
193
|
+
2025-09-18 14:54:29,863 - zen_orchestrator - INFO - Added instance: analyze-repo - Analyze the repository structure and codebase
|
|
194
|
+
2025-09-18 14:54:29,863 - zen_orchestrator - INFO - Added instance: help-overview - Show project README and overview information
|
|
195
|
+
|
|
196
|
+
2025-09-18 14:54:29,863 - zen_orchestrator - INFO - Orchestration scheduled to start at: 2025-09-19 02:00:00
|
|
197
|
+
2025-09-18 14:54:29,863 - zen_orchestrator - INFO - Waiting 39930.1 seconds (11.1 hours) until start time...
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
# Example Command
|
|
201
|
+
**Assumes you have a claude command /runtests**
|
|
202
|
+
```
|
|
203
|
+
zen "/runtests"
|
|
204
|
+
```
|
|
205
|
+
```
|
|
206
|
+
...
|
|
207
|
+
2025-09-18 14:56:18,478 - zen_orchestrator - INFO - Added instance: direct-runtests-3337c2c5 - Direct execution of /runtests
|
|
208
|
+
2025-09-18 14:56:18,478 - zen_orchestrator - INFO - Starting Claude Code instance orchestration
|
|
209
|
+
2025-09-18 14:56:18,478 - zen_orchestrator - INFO - Starting 1 instances with 5.0s delay between launches (timeout: 10000s each)
|
|
210
|
+
2025-09-18 14:56:18,478 - zen_orchestrator - INFO - Now starting instance 'direct-runtests-3337c2c5' (after 0.0s delay)
|
|
211
|
+
|
|
212
|
+
```
|
|
213
|
+
# Example Config (Recommended Usage)
|
|
214
|
+
|
|
215
|
+
Your JSON file as `path\my_config.json`
|
|
216
|
+
```JSON
|
|
217
|
+
{
|
|
218
|
+
"instances": [
|
|
219
|
+
{
|
|
220
|
+
"name": "analyze-repository",
|
|
221
|
+
"command": "/analyze-repository; Spawn three subagents to understand how the information at this website is used in the zen directory. https://docs.claude.com/en/docs/about-claude/pricing#tool-use-pricing.",
|
|
222
|
+
"description": "Reads and understands the required portion of the repository",
|
|
223
|
+
"permission_mode": "bypassPermissions",
|
|
224
|
+
"output_format": "stream-json",
|
|
225
|
+
"max_tokens_per_command": 5000
|
|
226
|
+
}
|
|
227
|
+
]
|
|
228
|
+
}
|
|
229
|
+
```
|
|
230
|
+
```
|
|
231
|
+
zen --config path\my_config.json
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
```
|
|
235
|
+
...
|
|
236
|
+
|
|
237
|
+
2025-09-18 15:00:09,645 - zen_orchestrator - INFO - Loading config from config_example.json
|
|
238
|
+
|
|
239
|
+
2025-09-18 15:00:09,657 - zen_orchestrator - INFO - 🎯 Token transparency pricing engine enabled - Claude pricing compliance active
|
|
240
|
+
|
|
241
|
+
2025-09-18 15:00:09,657 - zen_orchestrator - WARNING - Command '/analyze-repository; Spawn three subagents to understand how the information at this website is used in the zen directory. https://docs.claude.com/en/docs/about-claude/pricing#tool-use-pricing.' not found in available commands
|
|
242
|
+
|
|
243
|
+
2025-09-18 15:00:09,657 - zen_orchestrator - INFO - Available commands: /clear, /compact, /help
|
|
244
|
+
|
|
245
|
+
2025-09-18 15:00:09,657 - zen_orchestrator - INFO - Added instance: analyze-repository - Reads and understands the required portion of the repository
|
|
246
|
+
|
|
247
|
+
2025-09-18 15:00:09,657 - zen_orchestrator - INFO - Starting Claude Code instance orchestration
|
|
248
|
+
|
|
249
|
+
2025-09-18 15:00:09,659 - zen_orchestrator - INFO - Starting 1 instances with 5.0s delay between launches (timeout: 10000s each)
|
|
250
|
+
|
|
251
|
+
2025-09-18 15:00:09,659 - zen_orchestrator - INFO - Now starting instance 'analyze-repository' (after 0.0s delay)
|
|
252
|
+
|
|
253
|
+
2025-09-18 15:00:09,659 - zen_orchestrator - INFO - Starting instance: analyze-repository
|
|
254
|
+
|
|
255
|
+
2025-09-18 15:00:09,665 - zen_orchestrator - INFO - Command: claude.CMD -p /analyze-repository; Spawn three subagents to understand how the information at this website is used in the zen directory. https://docs.claude.com/en/docs/about-claude/pricing#tool-use-pricing. --output-format=stream-json --permission-mode=bypassPermissions --verbose
|
|
256
|
+
|
|
257
|
+
2025-09-18 15:00:09,738 - zen_orchestrator - INFO - Permission mode: bypassPermissions (Platform: Windows)
|
|
258
|
+
2025-09-18 15:00:09,746 - zen_orchestrator - INFO - Instance analyze-repository started with PID 672
|
|
259
|
+
|
|
260
|
+
+=== STATUS REPORT [15:00:14] ===+
|
|
261
|
+
| Total: 1 instances
|
|
262
|
+
| Running: 1, Completed: 0, Failed: 0, Pending: 0
|
|
263
|
+
| Tokens: 0 total, 0 cached | Median: 0 | Tools: 0
|
|
264
|
+
| 💰 Cost: $0.0000 total, $0.0000 avg/instance | Pricing: Claude compliant
|
|
265
|
+
|
|
|
266
|
+
| 📝 Model shows actual Claude model used (critical for accurate cost tracking)
|
|
267
|
+
| 💡 Tip: Model may differ from your config - Claude routes requests intelligently
|
|
268
|
+
| Status Name Model Duration Overall Tokens Cache Cr Cache Rd Tools Budget
|
|
269
|
+
| -------- ------------------------------ ---------- ---------- -------- -------- -------- -------- ------ ----------
|
|
270
|
+
| 🏃 analyze-repository opus4 5.1s 0 0 0 0 0 -
|
|
271
|
+
+================================+
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
+=== STATUS REPORT [15:00:19] ===+
|
|
275
|
+
| Total: 1 instances
|
|
276
|
+
| Running: 1, Completed: 0, Failed: 0, Pending: 0
|
|
277
|
+
| Tokens: 14.7K total, 14.7K cached | Median: 14.7K | Tools: 0
|
|
278
|
+
| 💰 Cost: $0.0798 total, $0.0798 avg/instance | Pricing: Claude compliant
|
|
279
|
+
| Status Name Model Duration Overall Tokens Cache Cr Cache Rd Tools Budget
|
|
280
|
+
| -------- ------------------------------ ---------- ---------- -------- -------- -------- -------- ------ ----------
|
|
281
|
+
| 🏃 analyze-repository opus4 10.1s 14.7K 6 3.3K 11.4K 0 -
|
|
282
|
+
+================================+
|
|
283
|
+
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
## Inspiration and background
|
|
288
|
+
While developing Netra Apex (commercial product)
|
|
289
|
+
our team has been running 100s of parallel claude code instances.
|
|
290
|
+
During that process we got annoyed at the "cognitive overhead"
|
|
291
|
+
of each having 10s of terminals open per machine and scrolling mountains of text.
|
|
292
|
+
Did the `/command` work or not?
|
|
293
|
+
|
|
294
|
+
What started as a simple way to make that process more peaceful turned into something we believe will be useful to the community.
|
|
295
|
+
|
|
296
|
+
Further, as usage limits become more restrictive, getting up at odd hours just to feed the beast got old fast. So we added scheduling to run it at pre-defined times.
|
|
297
|
+
|
|
298
|
+
Surprisingly, the duration that a command ran and it's presumed difficulty, often had little correlation with actual token usage.
|
|
299
|
+
"Simple" git operations would sometimes eat 10x as many as complex issue resolution commands.
|
|
300
|
+
|
|
301
|
+
The market is moving quickly, codex is getting better and other Code CLIs are coming. How effective a code factory is matters. This V1 alpha is just the start of codifying code CLI dev practices and progressing from alchemy to engineering.
|
|
302
|
+
|
|
303
|
+
For more power, try Zen with Netra Apex for the most effective usage and control of business AI spend.
|
|
304
|
+
|
|
305
|
+
## Limitations
|
|
306
|
+
|
|
307
|
+
### Budget Enforcement Behavior
|
|
308
|
+
|
|
309
|
+
**Important:**
|
|
310
|
+
|
|
311
|
+
- **Local Monitoring Only**: Budgets defined in `json` configs or command-line flags are tracked locally by Zen.
|
|
312
|
+
Zen cannot prevent the underlying CLI from consuming tokens beyond the limit in some cases.
|
|
313
|
+
For example if a request is made when it is under budget, that single request may exceed the budget. In `block` mode the *next* request will be stopped.
|
|
314
|
+
- **Budget Exceeded Behavior**:
|
|
315
|
+
- `warn` mode: Zen logs warnings but continues execution
|
|
316
|
+
- `block` mode: Zen prevents running new instances or halts in progress commands, depending on the nature of the budget config.
|
|
317
|
+
- **Token Counting**: Budget calculations are based on estimates and may not match exact billing from Claude/Codex
|
|
318
|
+
|
|
319
|
+
### Target Audience and Use Cases
|
|
320
|
+
|
|
321
|
+
Zen is designed for internal developer productivity and automation workflows and is *not* suitable for all use cases.
|
|
322
|
+
|
|
323
|
+
It is generally expected that you already familiar with claude code
|
|
324
|
+
in order to get the most value out of Zen.
|
|
325
|
+
|
|
326
|
+
**✅ Supported Use Cases:**
|
|
327
|
+
- Internal development workflows and automation
|
|
328
|
+
- Parallel execution of development tasks
|
|
329
|
+
- CI/CD integration for development teams
|
|
330
|
+
- Budget and cost control for Claude
|
|
331
|
+
|
|
332
|
+
## Installation
|
|
333
|
+
|
|
334
|
+
### Default Method: pipx (Recommended for ALL Users)
|
|
335
|
+
|
|
336
|
+
Pipx automatically handles PATH configuration and creates an isolated environment, preventing dependency conflicts.
|
|
337
|
+
|
|
338
|
+
#### Step 1: Install pipx
|
|
339
|
+
```bash
|
|
340
|
+
# Windows
|
|
341
|
+
pip install --user pipx
|
|
342
|
+
python -m pipx ensurepath
|
|
343
|
+
|
|
344
|
+
# macOS
|
|
345
|
+
brew install pipx
|
|
346
|
+
pipx ensurepath
|
|
347
|
+
|
|
348
|
+
# Linux (Ubuntu/Debian)
|
|
349
|
+
sudo apt update
|
|
350
|
+
sudo apt install pipx
|
|
351
|
+
pipx ensurepath
|
|
352
|
+
|
|
353
|
+
# Linux (Other)
|
|
354
|
+
pip install --user pipx
|
|
355
|
+
pipx ensurepath
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
**Note:** Restart your terminal after running `pipx ensurepath`
|
|
359
|
+
|
|
360
|
+
#### Step 2: Install zen
|
|
361
|
+
```bash
|
|
362
|
+
# From PyPI
|
|
363
|
+
pipx install netra-zen
|
|
364
|
+
|
|
365
|
+
# For local development (editable mode)
|
|
366
|
+
cd zen/
|
|
367
|
+
pipx install --editable .
|
|
368
|
+
|
|
369
|
+
# Verify installation
|
|
370
|
+
zen --help
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
### Alternative: pip (Manual PATH Configuration Required)
|
|
374
|
+
|
|
375
|
+
⚠️ **Warning:** Using pip directly often results in PATH issues. We strongly recommend pipx instead.
|
|
376
|
+
|
|
377
|
+
```bash
|
|
378
|
+
pip install netra-zen
|
|
379
|
+
|
|
380
|
+
# If 'zen' command not found, you'll need to:
|
|
381
|
+
# Option 1: Use Python module directly
|
|
382
|
+
python -m zen_orchestrator --help
|
|
383
|
+
|
|
384
|
+
# Option 2: Manually add to PATH (see Troubleshooting)
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
## Understanding the Model Column in Status Reports
|
|
388
|
+
|
|
389
|
+
### Model Column Behavior
|
|
390
|
+
|
|
391
|
+
The **Model** column in Zen's status display shows the **actual model used** by Claude Code for each API response, not necessarily the model you configured in your settings.
|
|
392
|
+
|
|
393
|
+
**Key Points:**
|
|
394
|
+
- **Cost Tracking Value**: Knowing the actual model is critical for accurate cost calculation since different models have vastly different pricing (e.g., Opus costs 5x more than Sonnet)
|
|
395
|
+
- **Dynamic Detection**: Zen automatically detects the model from Claude's API responses in real-time
|
|
396
|
+
|
|
397
|
+
**Example Status Display:**
|
|
398
|
+
```
|
|
399
|
+
║ Status Name Model Duration Overall Tokens Budget
|
|
400
|
+
║ ✅ analyze-code 35sonnet 2m15s 45.2K 2.1K 85% used
|
|
401
|
+
║ 🏃 optimize-perf opus4 1m30s 12.8K 800 45% used
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
This transparency helps you understand your actual AI spend and make informed decisions about model usage.
|
|
405
|
+
|
|
406
|
+
|
|
407
|
+
### Step 3: Generate with AI
|
|
408
|
+
|
|
409
|
+
1. Copy your customized prompt
|
|
410
|
+
2. Paste it into ChatGPT, Claude, or your preferred LLM
|
|
411
|
+
3. Save the generated JSON as `customer_feedback.json`
|
|
412
|
+
4. Run: `zen --config customer_feedback.json`
|
|
413
|
+
|
|
414
|
+
## Understanding Configuration Structure
|
|
415
|
+
|
|
416
|
+
Every Zen configuration has the same basic structure:
|
|
417
|
+
|
|
418
|
+
```json
|
|
419
|
+
{
|
|
420
|
+
"// Description": "What this workflow accomplishes",
|
|
421
|
+
"// Use Case": "When to use this configuration",
|
|
422
|
+
|
|
423
|
+
"instances": [
|
|
424
|
+
{
|
|
425
|
+
"command": "/command || prompt",
|
|
426
|
+
"permission_mode": "bypassPermissions", // Default
|
|
427
|
+
"output_format": "stream-json", // Default
|
|
428
|
+
"max_tokens_per_command": 12000, // Optional
|
|
429
|
+
"allowed_tools": ["Read", "Write", "Edit", "Task"], // Optional
|
|
430
|
+
// Other optional features
|
|
431
|
+
}//,
|
|
432
|
+
//{
|
|
433
|
+
// next instance
|
|
434
|
+
//}
|
|
435
|
+
//... series of instances
|
|
436
|
+
]
|
|
437
|
+
}
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
### Key Configuration Elements
|
|
441
|
+
|
|
442
|
+
| Element | Purpose | Best Practice |
|
|
443
|
+
|---------|---------|---------------|
|
|
444
|
+
| `command` | Task specification | Can use existing /commands or any string literal input |
|
|
445
|
+
| `max_tokens_per_command` | Token budget | Allocate based on complexity |
|
|
446
|
+
| `allowed_tools` | Tool permissions | Grant minimal necessary tools |
|
|
447
|
+
|
|
448
|
+
For Output Truncation control: `--max-console-lines` and `--max-line-length` parameters, or redirect output to files
|
|
449
|
+
|
|
450
|
+
### Scheduling
|
|
451
|
+
|
|
452
|
+
Schedule to run later.
|
|
453
|
+
This helps you get the most value out of your claude max subscription.
|
|
454
|
+
|
|
455
|
+
```bash
|
|
456
|
+
# Start in 2 hours
|
|
457
|
+
zen --config my_config.json --start-at "2h"
|
|
458
|
+
|
|
459
|
+
# Start at specific time
|
|
460
|
+
zen --config my_config.json --start-at "14:30"
|
|
461
|
+
|
|
462
|
+
# Start in 30 minutes
|
|
463
|
+
zen --config my_config.json --start-at "30m"
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
## Expected questions
|
|
467
|
+
|
|
468
|
+
### 1. Do I have to use /commands?
|
|
469
|
+
- No. You can just put your string query (prompt) and it works the same.
|
|
470
|
+
- It does seem to be a best practice though to version controlled `/commands`.
|
|
471
|
+
|
|
472
|
+
### 2. Does this replace using Claude command directly?
|
|
473
|
+
- No. At least not yet fully.
|
|
474
|
+
- As we primarily using structured commands, internally we see 80%+ of our usage through Zen.
|
|
475
|
+
- Ad hoc questions or validating if a command is working as expected for now is better through Claude directly.
|
|
476
|
+
|
|
477
|
+
### 3. What does this assume?
|
|
478
|
+
- You have claude code installed, authenticated, and configured already.
|
|
479
|
+
|
|
480
|
+
### 4. How do I know if it's working?
|
|
481
|
+
- Each command returns fairly clear overall statuses.
|
|
482
|
+
- Budget states etc. are logged.
|
|
483
|
+
- You can also see the duration and token usage.
|
|
484
|
+
- By default, each command outputs a truncated version of the output to the console.
|
|
485
|
+
- You can optionally choose to save a report of all output to .json
|
|
486
|
+
- Our usage is heavily integrated with github, we use git issues as the visual output
|
|
487
|
+
and notification system for most work. This means regardless of where Zen is running
|
|
488
|
+
you can see the results wherever you access git. This is as easy as adding `gh` instructions (the cli + token assumed to be present) to your commands.
|
|
489
|
+
|
|
490
|
+
### 5. Data privacy?
|
|
491
|
+
At this moment no data is collected.
|
|
492
|
+
Our intent is to add an optional system where non-PII usage data is sent to Netra for exclusively aggregated metadata level use to help make our spend management system better. (So you can get more from your AI spend!)
|
|
493
|
+
|
|
494
|
+
## 6. What about the UI/UX?
|
|
495
|
+
There is a time and a place for wanting to have multiple windows and git trees open.
|
|
496
|
+
Zen's intent is the opposite: make running `n` code clis more peaceful.
|
|
497
|
+
Why activate your "giga-brain" when you can run one command instead?
|
|
498
|
+
|
|
499
|
+
|
|
500
|
+
## Zen --help
|
|
501
|
+
```zen --help```
|
|
502
|
+
yields:
|
|
503
|
+
```
|
|
504
|
+
usage: zen [-h] [--workspace WORKSPACE] [--config CONFIG] [--dry-run] [--list-commands] [--inspect-command INSPECT_COMMAND]
|
|
505
|
+
[--output-format {json,stream-json}] [--timeout TIMEOUT] [--max-console-lines MAX_CONSOLE_LINES] [--quiet]
|
|
506
|
+
[--startup-delay STARTUP_DELAY] [--max-line-length MAX_LINE_LENGTH] [--status-report-interval STATUS_REPORT_INTERVAL]
|
|
507
|
+
[--start-at START_AT] [--overall-token-budget OVERALL_TOKEN_BUDGET] [--command-budget COMMAND_BUDGET]
|
|
508
|
+
[--budget-enforcement-mode {warn,block}] [--disable-budget-visuals]
|
|
509
|
+
|
|
510
|
+
Claude Code Instance Orchestrator
|
|
511
|
+
|
|
512
|
+
options:
|
|
513
|
+
-h, --help show this help message and exit
|
|
514
|
+
--workspace WORKSPACE
|
|
515
|
+
Workspace directory (default: current directory)
|
|
516
|
+
--config CONFIG Custom instance configuration file
|
|
517
|
+
--dry-run Show commands without running
|
|
518
|
+
--list-commands List all available slash commands and exit
|
|
519
|
+
--inspect-command INSPECT_COMMAND
|
|
520
|
+
Inspect a specific slash command and exit
|
|
521
|
+
--output-format {json,stream-json}
|
|
522
|
+
Output format for Claude instances (default: stream-json)
|
|
523
|
+
--timeout TIMEOUT Timeout in seconds for each instance (default: 10000)
|
|
524
|
+
--max-console-lines MAX_CONSOLE_LINES
|
|
525
|
+
Maximum recent lines to show per instance on console (default: 5)
|
|
526
|
+
--quiet Minimize console output, show only errors and final summaries
|
|
527
|
+
--startup-delay STARTUP_DELAY
|
|
528
|
+
Delay in seconds between launching each instance (default: 5.0)
|
|
529
|
+
--max-line-length MAX_LINE_LENGTH
|
|
530
|
+
Maximum characters per line in console output (default: 500)
|
|
531
|
+
--status-report-interval STATUS_REPORT_INTERVAL
|
|
532
|
+
Seconds between rolling status reports (default: 5)
|
|
533
|
+
--start-at START_AT Schedule orchestration to start at specific time. Examples: '2h' (2 hours from now), '30m' (30 minutes),
|
|
534
|
+
'14:30' (2:30 PM today), '1am' (1 AM today/tomorrow)
|
|
535
|
+
--overall-token-budget OVERALL_TOKEN_BUDGET
|
|
536
|
+
Global token budget for the entire session.
|
|
537
|
+
--command-budget COMMAND_BUDGET
|
|
538
|
+
Per-command budget in format: '/command_name=limit'. Can be used multiple times.
|
|
539
|
+
--budget-enforcement-mode {warn,block}
|
|
540
|
+
Action to take when a budget is exceeded: 'warn' (log and continue) or 'block' (prevent new instances).
|
|
541
|
+
--disable-budget-visuals
|
|
542
|
+
Disable budget visualization in status reports
|
|
543
|
+
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
## Requirements
|
|
547
|
+
|
|
548
|
+
- Python 3.8+
|
|
549
|
+
- Claude Code CLI
|
|
550
|
+
- Dependencies in requirements.txt
|
|
551
|
+
|
|
552
|
+
## Logging and Output
|
|
553
|
+
|
|
554
|
+
- **Console Output**: All logs and execution results are displayed in the console
|
|
555
|
+
- **No File Logging**: ZEN does not write logs to files by default
|
|
556
|
+
- **Capturing Output**: To save execution logs, use output redirection:
|
|
557
|
+
```bash
|
|
558
|
+
zen --config tasks.json > execution.log 2>&1
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
## Testing
|
|
562
|
+
|
|
563
|
+
```bash
|
|
564
|
+
cd tests/
|
|
565
|
+
python test_runner.py
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
## Basic Usage
|
|
569
|
+
|
|
570
|
+
### Command Execution
|
|
571
|
+
Execute commands directly without config files:
|
|
572
|
+
```bash
|
|
573
|
+
# Execute a single command directly
|
|
574
|
+
zen "/my-existing-claude-command"
|
|
575
|
+
|
|
576
|
+
# Execute with config (recommended usage pattern)
|
|
577
|
+
zen --config /my-config.json
|
|
578
|
+
|
|
579
|
+
# Execute with custom workspace
|
|
580
|
+
zen "/analyze-code" --workspace ~/my-project
|
|
581
|
+
|
|
582
|
+
# Execute with token budget
|
|
583
|
+
zen "/complex-analysis" --overall-token-budget 5000
|
|
584
|
+
|
|
585
|
+
# Execute with custom instance name
|
|
586
|
+
zen "/debug-issue" --instance-name "debug-session"
|
|
587
|
+
|
|
588
|
+
# Execute with session continuity
|
|
589
|
+
zen "/optimize-performance" --session-id "perf-session-1"
|
|
590
|
+
|
|
591
|
+
# Start in 2 hours
|
|
592
|
+
zen --config my_config.json --start-at "2h"
|
|
593
|
+
|
|
594
|
+
# Start at specific time
|
|
595
|
+
zen --config my_config.json --start-at "14:30"
|
|
596
|
+
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
|
|
600
|
+
### Quick Test
|
|
601
|
+
```bash
|
|
602
|
+
# List available commands (auto-detects workspace)
|
|
603
|
+
zen --list-commands
|
|
604
|
+
|
|
605
|
+
# Dry run to see what would be executed (auto-detects workspace)
|
|
606
|
+
zen --dry-run
|
|
607
|
+
|
|
608
|
+
# Run with default configuration (uses actual slash commands from workspace)
|
|
609
|
+
zen
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
### Workspace Management
|
|
613
|
+
```bash
|
|
614
|
+
# Auto-detect workspace (looks for project root with .git, .claude, etc.)
|
|
615
|
+
zen --dry-run
|
|
616
|
+
|
|
617
|
+
# Use specific workspace (override auto-detection)
|
|
618
|
+
zen --workspace ~/projects/myapp
|
|
619
|
+
|
|
620
|
+
# With custom timeout
|
|
621
|
+
zen --timeout 300 --workspace ~/projects/myapp
|
|
622
|
+
```
|
|
623
|
+
|
|
624
|
+
### Token Budget Control
|
|
625
|
+
```bash
|
|
626
|
+
# Set overall budget
|
|
627
|
+
zen --overall-token-budget 100000
|
|
628
|
+
|
|
629
|
+
# Set per-command budgets
|
|
630
|
+
zen --command-budget "/analyze=50000" --command-budget "/optimize=30000"
|
|
631
|
+
|
|
632
|
+
# Budget enforcement modes
|
|
633
|
+
zen --budget-enforcement-mode block # Stop when exceeded
|
|
634
|
+
zen --budget-enforcement-mode warn # Warn but continue
|
|
635
|
+
```
|
|
636
|
+
|
|
637
|
+
### Scheduled Execution
|
|
638
|
+
```bash
|
|
639
|
+
# Start in 2 hours
|
|
640
|
+
zen --start-at "2h"
|
|
641
|
+
|
|
642
|
+
# Start at specific time
|
|
643
|
+
zen --start-at "14:30" # 2:30 PM today
|
|
644
|
+
zen --start-at "1am" # 1 AM tomorrow
|
|
645
|
+
```
|
|
646
|
+
|
|
647
|
+
### Execution Mode Precedence
|
|
648
|
+
Zen supports three execution modes with clear precedence rules:
|
|
649
|
+
|
|
650
|
+
1. **Direct Command** (Highest Priority)
|
|
651
|
+
```bash
|
|
652
|
+
zen "/analyze-code" # Executes direct command
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
2. **Config File** (Medium Priority)
|
|
656
|
+
```bash
|
|
657
|
+
zen --config my-config.json # Uses config file
|
|
658
|
+
```
|
|
659
|
+
|
|
660
|
+
3. **Default Instances** (Lowest Priority)
|
|
661
|
+
```bash
|
|
662
|
+
zen # Uses built-in default commands
|
|
663
|
+
```
|
|
664
|
+
|
|
665
|
+
## Other Features
|
|
666
|
+
|
|
667
|
+
### Parallel Execution Control
|
|
668
|
+
```bash
|
|
669
|
+
# Control startup delay between instances
|
|
670
|
+
zen --startup-delay 30.0 # seconds between launches
|
|
671
|
+
|
|
672
|
+
# Limit console output
|
|
673
|
+
zen --max-console-lines 10
|
|
674
|
+
zen --max-line-length 200
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
### Output Formats
|
|
678
|
+
```bash
|
|
679
|
+
# JSON output
|
|
680
|
+
zen --output-format json
|
|
681
|
+
|
|
682
|
+
# Stream JSON (default)
|
|
683
|
+
zen --output-format stream-json
|
|
684
|
+
```
|
|
685
|
+
|
|
686
|
+
### Quiet Mode
|
|
687
|
+
```bash
|
|
688
|
+
# Minimal output - only errors and summary
|
|
689
|
+
zen --quiet
|
|
690
|
+
```
|
|
691
|
+
|
|
692
|
+
### Status Reporting
|
|
693
|
+
```bash
|
|
694
|
+
# Change status report interval
|
|
695
|
+
zen --status-report-interval 30 # Every 30 seconds
|
|
696
|
+
```
|
|
697
|
+
|
|
698
|
+
## Environment Variables
|
|
699
|
+
|
|
700
|
+
```bash
|
|
701
|
+
# Set default workspace
|
|
702
|
+
export ZEN_WORKSPACE="~/projects"
|
|
703
|
+
|
|
704
|
+
# Set default config
|
|
705
|
+
export ZEN_CONFIG="~/configs/zen-default.json"
|
|
706
|
+
|
|
707
|
+
# Enable debug logging
|
|
708
|
+
export ZEN_DEBUG="true"
|
|
709
|
+
```
|
|
710
|
+
|
|
711
|
+
## Troubleshooting
|
|
712
|
+
|
|
713
|
+
### Command not found
|
|
714
|
+
|
|
715
|
+
#### If using pipx (recommended):
|
|
716
|
+
```bash
|
|
717
|
+
# Ensure PATH is configured
|
|
718
|
+
pipx ensurepath
|
|
719
|
+
|
|
720
|
+
# Restart terminal, then verify
|
|
721
|
+
zen --version
|
|
722
|
+
```
|
|
723
|
+
|
|
724
|
+
### Permission denied
|
|
725
|
+
```bash
|
|
726
|
+
# Make sure scripts are executable
|
|
727
|
+
chmod +x $(which zen)
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
### Module not found
|
|
731
|
+
```bash
|
|
732
|
+
# Reinstall with dependencies
|
|
733
|
+
pip install --force-reinstall netra-zen
|
|
734
|
+
```
|
|
735
|
+
|
|
736
|
+
## Getting Help
|
|
737
|
+
|
|
738
|
+
```bash
|
|
739
|
+
# Show help
|
|
740
|
+
zen --help
|
|
741
|
+
|
|
742
|
+
# Inspect specific command
|
|
743
|
+
zen --inspect-command /analyze
|
|
744
|
+
|
|
745
|
+
# Visit documentation
|
|
746
|
+
# https://github.com/netra-systems/zen
|
|
747
|
+
```
|
|
748
|
+
|
|
749
|
+
### Known Issues
|
|
750
|
+
|
|
751
|
+
**Token Budget Accuracy:**
|
|
752
|
+
- **Problem**: Budget calculations may not exactly match actual API billing
|
|
753
|
+
- **Cause**: Estimates based on local token counting vs. server-side billing
|
|
754
|
+
- **Workaround**: Use conservative budget limits and monitor actual usage through provider dashboards
|
|
755
|
+
|
|
756
|
+
**Configuration File Validation:**
|
|
757
|
+
- **Problem**: Limited validation of JSON configuration files
|
|
758
|
+
- **Impact**: Invalid configurations may cause runtime errors
|
|
759
|
+
- **Workaround**: Use `--dry-run` to validate configurations before execution
|
|
760
|
+
|
|
761
|
+
**Resource Cleanup:**
|
|
762
|
+
- **Problem**: Interrupted executions may leave background processes running
|
|
763
|
+
- **Workaround**: Monitor system processes and manually terminate if necessary
|
|
764
|
+
- **Planned Fix**: Improved signal handling and cleanup in future versions
|
|
765
|
+
|
|
766
|
+
## Example Configurations
|
|
767
|
+
|
|
768
|
+
See the included example files:
|
|
769
|
+
- `minimal_config.json` - Basic setup
|
|
770
|
+
- `config_example.json` - Standard configuration
|
|
771
|
+
- `netra_apex_tool_example.json` - Advanced integration
|
|
772
|
+
|
|
773
|
+
## Support
|
|
774
|
+
|
|
775
|
+
- GitHub Issues: https://github.com/netra-systems/zen/issues
|
|
776
|
+
- Documentation: https://github.com/netra-systems/zen/wiki
|