jules-agent 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. jules_agent-0.1.2/LICENSE +21 -0
  2. jules_agent-0.1.2/PKG-INFO +296 -0
  3. jules_agent-0.1.2/README.md +255 -0
  4. jules_agent-0.1.2/pyproject.toml +43 -0
  5. jules_agent-0.1.2/setup.cfg +4 -0
  6. jules_agent-0.1.2/src/jules_agent/__init__.py +4 -0
  7. jules_agent-0.1.2/src/jules_agent/__main__.py +5 -0
  8. jules_agent-0.1.2/src/jules_agent/cli/__init__.py +379 -0
  9. jules_agent-0.1.2/src/jules_agent/cli/__main__.py +5 -0
  10. jules_agent-0.1.2/src/jules_agent/cli/advance_core.py +388 -0
  11. jules_agent-0.1.2/src/jules_agent/cli/commands/__init__.py +29 -0
  12. jules_agent-0.1.2/src/jules_agent/cli/commands/advance.py +64 -0
  13. jules_agent-0.1.2/src/jules_agent/cli/commands/approve.py +48 -0
  14. jules_agent-0.1.2/src/jules_agent/cli/commands/delete.py +119 -0
  15. jules_agent-0.1.2/src/jules_agent/cli/commands/feedback.py +247 -0
  16. jules_agent-0.1.2/src/jules_agent/cli/commands/import_command.py +185 -0
  17. jules_agent-0.1.2/src/jules_agent/cli/commands/merge.py +139 -0
  18. jules_agent-0.1.2/src/jules_agent/cli/commands/next.py +51 -0
  19. jules_agent-0.1.2/src/jules_agent/cli/commands/review.py +48 -0
  20. jules_agent-0.1.2/src/jules_agent/cli/commands/run.py +237 -0
  21. jules_agent-0.1.2/src/jules_agent/cli/commands/send.py +50 -0
  22. jules_agent-0.1.2/src/jules_agent/cli/commands/status.py +44 -0
  23. jules_agent-0.1.2/src/jules_agent/cli/commands/sync.py +118 -0
  24. jules_agent-0.1.2/src/jules_agent/cli/io.py +193 -0
  25. jules_agent-0.1.2/src/jules_agent/cli/state.py +315 -0
  26. jules_agent-0.1.2/src/jules_agent/client.py +156 -0
  27. jules_agent-0.1.2/src/jules_agent/codex.py +408 -0
  28. jules_agent-0.1.2/src/jules_agent/config.py +80 -0
  29. jules_agent-0.1.2/src/jules_agent/git.py +98 -0
  30. jules_agent-0.1.2/src/jules_agent/github.py +120 -0
  31. jules_agent-0.1.2/src/jules_agent/models.py +330 -0
  32. jules_agent-0.1.2/src/jules_agent/persistence.py +55 -0
  33. jules_agent-0.1.2/src/jules_agent/pipeline.py +757 -0
  34. jules_agent-0.1.2/src/jules_agent/review.py +267 -0
  35. jules_agent-0.1.2/src/jules_agent.egg-info/PKG-INFO +296 -0
  36. jules_agent-0.1.2/src/jules_agent.egg-info/SOURCES.txt +55 -0
  37. jules_agent-0.1.2/src/jules_agent.egg-info/dependency_links.txt +1 -0
  38. jules_agent-0.1.2/src/jules_agent.egg-info/entry_points.txt +2 -0
  39. jules_agent-0.1.2/src/jules_agent.egg-info/requires.txt +6 -0
  40. jules_agent-0.1.2/src/jules_agent.egg-info/top_level.txt +1 -0
  41. jules_agent-0.1.2/tests/test_advance.py +329 -0
  42. jules_agent-0.1.2/tests/test_claude_adapter.py +67 -0
  43. jules_agent-0.1.2/tests/test_cli.py +210 -0
  44. jules_agent-0.1.2/tests/test_client.py +71 -0
  45. jules_agent-0.1.2/tests/test_config.py +71 -0
  46. jules_agent-0.1.2/tests/test_feedback.py +188 -0
  47. jules_agent-0.1.2/tests/test_github.py +135 -0
  48. jules_agent-0.1.2/tests/test_import.py +166 -0
  49. jules_agent-0.1.2/tests/test_interactive_selection.py +148 -0
  50. jules_agent-0.1.2/tests/test_merge.py +175 -0
  51. jules_agent-0.1.2/tests/test_next_command.py +110 -0
  52. jules_agent-0.1.2/tests/test_opencode.py +66 -0
  53. jules_agent-0.1.2/tests/test_pipeline.py +147 -0
  54. jules_agent-0.1.2/tests/test_review.py +155 -0
  55. jules_agent-0.1.2/tests/test_status.py +65 -0
  56. jules_agent-0.1.2/tests/test_sync.py +123 -0
  57. jules_agent-0.1.2/tests/test_sync_output.py +166 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ship
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,296 @@
1
+ Metadata-Version: 2.4
2
+ Name: jules-agent
3
+ Version: 0.1.2
4
+ Summary: Decompose a task with Codex and dispatch the subtasks to Jules.
5
+ Author: ship
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 ship
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Project-URL: Repository, https://github.com/shipwebdotjp/jules-agent-orchestra
29
+ Classifier: License :: OSI Approved :: MIT License
30
+ Classifier: Programming Language :: Python :: 3
31
+ Classifier: Programming Language :: Python :: 3 :: Only
32
+ Requires-Python: >=3.12
33
+ Description-Content-Type: text/markdown
34
+ License-File: LICENSE
35
+ Requires-Dist: httpx
36
+ Provides-Extra: dev
37
+ Requires-Dist: pytest; extra == "dev"
38
+ Requires-Dist: respx; extra == "dev"
39
+ Requires-Dist: pytest-mock; extra == "dev"
40
+ Dynamic: license-file
41
+
42
+ # jules-agent
43
+
44
+ `jules-agent` is a CLI for handing off work to Jules with a little more structure around it.
45
+ It turns a task into a plan, sends the work to Jules, and helps you keep moving through feedback, review, and merge.
46
+
47
+ - 日本語版: [README_ja.md](README_ja.md)
48
+
49
+ ## What it does
50
+
51
+ `jules-agent` helps with the full loop around a coding task:
52
+
53
+ - turn a single request into a workable plan
54
+ - surface clarification questions before the work starts
55
+ - send the task to Jules
56
+ - collect feedback and move the task forward
57
+ - review the result and merge the pull request when it is ready
58
+
59
+ It is useful whether you want a light planning pass or a more hands-on loop around implementation and review.
60
+
61
+ ## Requirements
62
+
63
+ - Python 3.12 or newer
64
+ - `git` available on `PATH`
65
+ - `JULES_API_KEY` set in the environment, or `api_key` configured in TOML
66
+ - `GITHUB_TOKEN` set when you want review, merge, or PR status syncing
67
+
68
+ Repository assumptions:
69
+
70
+ - you are inside a Git repository
71
+ - the repository has a GitHub remote
72
+ - Jules is already set up for the GitHub account as an app and has access to the repository
73
+
74
+ `jules-agent` talks to the Jules API directly, so a local `jules` CLI binary is not required.
75
+
76
+ If you do not run the command inside a git repository, pass `--repo owner/name`.
77
+
78
+ ## Install
79
+
80
+ From PyPI:
81
+
82
+ ```bash
83
+ pipx install jules-agent
84
+ ```
85
+
86
+ ```bash
87
+ uv tool install jules-agent
88
+ ```
89
+
90
+ ```bash
91
+ pip install jules-agent
92
+ ```
93
+
94
+ From a local checkout:
95
+
96
+ ```bash
97
+ pip install -e .
98
+ ```
99
+
100
+ After installing, the `jules-agent` command is available on your `PATH`.
101
+
102
+ ## Usage
103
+
104
+ ```bash
105
+ jules-agent [flags] <command> [args]
106
+ ```
107
+
108
+ The common flow is:
109
+
110
+ 1. Create a task with `run`.
111
+ 2. Check progress with `status` and `sync`.
112
+ 3. Approve, give feedback, or send a direct message if needed.
113
+ 4. Review the pull request.
114
+ 5. Merge when it is ready.
115
+
116
+ ### Subcommands
117
+
118
+ - `run [flags] <task>`: Analyze a new task with the configured planning tool and dispatch it to Jules.
119
+ - In interactive mode, it may first ask clarification questions before generating a plan.
120
+ - `--no-confirm`: Skip the confirmation loop and dispatch immediately.
121
+ - `--auto-plan-approval`: Automatically approve the task plan (forces `requirePlanApproval=false`).
122
+ - `--automation-mode <mode>`: Specify the automation mode for the Jules session.
123
+ - `AUTO_CREATE_PR` (default): Whenever a final code patch is generated in the session, automatically create a branch and a pull request for it.
124
+ - `AUTOMATION_MODE_UNSPECIFIED`: The automation mode is unspecified. Default to no automation.
125
+ - `import <session_id>`: Import an existing Jules session into the local state.
126
+ - Supports both bare IDs (e.g., `12345`) and full session names (e.g., `sessions/12345`).
127
+ - `status`: Show the current local state, including runs and tasks. By default, it only shows runs with `planned` or `running` status.
128
+ - `-a`, `--all`: Show all runs, including completed, failed, and cancelled.
129
+ - `--show-activities`: Show detailed session activities for each task.
130
+ - `sync`: Synchronize the local state with the Jules API and GitHub (to update PR status).
131
+ - `advance [flags]`: Automatically or interactively advance work across the next active task. For `sequential_subtasks`, a successful merge also dispatches the next `planned` task in the same run.
132
+ - `cron [flags]`: Non-interactive background execution. This is a purely automated version of `advance` that never asks for input, and it also dispatches the next `planned` task after a successful sequential merge.
133
+ - `approve [task_id]`: Manually approve the proposed plan for a specific task. If `task_id` is omitted, it shows a list of tasks awaiting plan approval.
134
+ - `send [task_id] message`: Send a manual message to a task's Jules session. If `task_id` is omitted, it shows a list of active tasks. If your message contains spaces and you omit `task_id`, the message must be quoted (e.g., `jules-agent send "hello world"`).
135
+ - `feedback [task_id]`: Enter an interactive feedback loop to refine a task's plan or reply. If `task_id` is omitted, it shows a list of eligible tasks.
136
+ - `review [task_id]`: Run a review for a task with an open pull request. If `task_id` is omitted, it shows a list of tasks with open pull requests.
137
+ - `merge [task_id]`: Manually merge the pull request associated with a task. If `task_id` is omitted, it first performs a full state synchronization and then shows a list of tasks with open pull requests.
138
+ - `next [run_id]`: Dispatch the next task in a sequential run. If `run_id` is omitted, it shows a list of active sequential runs with planned tasks.
139
+ - `--automation-mode <mode>`: Specify the automation mode for the Jules session (e.g., `AUTO_CREATE_PR` or `AUTOMATION_MODE_UNSPECIFIED`).
140
+ - `delete run [run_id]`: Delete a run and its tasks from the local state.
141
+ - `delete task [task_id]`: Delete a specific task from the local state. If the run becomes empty, it is also removed.
142
+ - `rm`: An alias for `delete`.
143
+ - Omitting `run_id` or `task_id` triggers an interactive selection prompt.
144
+ - `--dry-run`: Show what would be deleted without making changes.
145
+ - `--yes`, `-y`: Skip confirmation prompts and proceed immediately.
146
+
147
+ ### Global Flags
148
+
149
+ - `--repo owner/name`: Override the target repository.
150
+ - `--tool-bin /path/to/tool`: Path to the backend tool executable.
151
+ - `--tool <name>`: Backend tool to use.
152
+ - `--gemini-skip-trust`: Pass `--skip-trust` to the Gemini CLI adapter.
153
+ - `--plan-tool <name>`: Tool override for the planning phase.
154
+ - `--approve-tool <name>`: Tool override for the approval phase.
155
+ - `--feedback-tool <name>`: Tool override for the feedback phase.
156
+ - `--review-tool <name>`: Tool override for the review phase.
157
+ - `--config /path/to/config.toml`: Specify a custom configuration file.
158
+
159
+ Supported backend tools are `codex`, `claude`, `gemini`, `opencode`, `copilot`, and `cline`.
160
+ Use `--tool` to set one default backend, or override individual phases with `--plan-tool`, `--approve-tool`, `--feedback-tool`, and `--review-tool`.
161
+
162
+ The `--tool-bin` flag and `tool_bin` config field let you point at a specific backend binary.
163
+
164
+ ### Automation Flags (for `advance` and `cron`)
165
+
166
+ - `--auto-plan-approval`: Automatically approve plans when recommended by the planning tool.
167
+ - `--auto-feedback`: Automatically send suggested feedback messages.
168
+ - `--auto-merge`: Automatically merge pull requests when they are ready.
169
+ - `--auto`: Enable both plan approval and feedback (does NOT include merge).
170
+ - `--json`: Emit the result as a single JSON object.
171
+
172
+ ### Examples
173
+
174
+ ```bash
175
+ # 1. Create a task
176
+ jules-agent run "Split the parser from the dispatcher"
177
+
178
+ # 2. Check progress and capture the run/task IDs
179
+ jules-agent status
180
+
181
+ # 3. Refresh local state from Jules and GitHub
182
+ jules-agent sync
183
+
184
+ # 4. If the task is waiting for a plan decision, approve it
185
+ jules-agent approve RUN_ID:TASK_ID
186
+
187
+ # Or, if the plan needs changes, give feedback instead
188
+ jules-agent feedback RUN_ID:TASK_ID
189
+
190
+ # 5. Review the pull request once Jules opens one
191
+ jules-agent review RUN_ID:TASK_ID
192
+
193
+ # 6. Merge the pull request when it is ready
194
+ jules-agent merge RUN_ID:TASK_ID
195
+ ```
196
+
197
+ For a sequential run, you can keep going with:
198
+
199
+ ```bash
200
+ # Dispatch the next planned task in the run
201
+ jules-agent next RUN_ID
202
+
203
+ # Or let the tool advance work and merge automatically
204
+ jules-agent advance --auto
205
+ ```
206
+
207
+ ## Configuration
208
+
209
+ `jules-agent` can be configured using TOML files. It searches for configuration in the following locations (in order of increasing priority):
210
+
211
+ 1. `~/.jules-agent.toml`
212
+ 2. `~/.config/jules-agent/config.toml`
213
+ 3. `./.jules-agent.toml`
214
+ 4. `./jules-agent.toml`
215
+ 5. A custom file specified via `--config`
216
+
217
+ Settings in the configuration file have lower priority than environment variables and command-line flags. For automation flags, the priority is:
218
+ 1. Individual CLI flag (e.g., `--auto-merge`, `--automation-mode`)
219
+ 2. The `--auto` flag (sets approval and feedback to true)
220
+ 3. Configuration file settings
221
+ 4. Default values (auto_plan_approval=true, others=false, automation_mode="AUTO_CREATE_PR")
222
+
223
+ ### GitHub Token
224
+
225
+ `jules-agent` reads `GITHUB_TOKEN` from the environment, or `github_token` from the TOML configuration file.
226
+
227
+ Need permissions:
228
+ - pull-requests: write
229
+ - issues: write
230
+ - contents: write
231
+
232
+ ### Supported Settings
233
+
234
+ ```toml
235
+ api_key = "your-jules-api-key"
236
+ repo = "owner/repo"
237
+ github_token = "ghp_your-github-token"
238
+ tool_bin = "path/to/tool"
239
+ tool = "codex"
240
+ gemini_skip_trust = false
241
+ plan_tool = "claude"
242
+ approve_tool = "gemini"
243
+ feedback_tool = "opencode"
244
+ review_tool = "copilot"
245
+ base_url = "https://jules.googleapis.com/v1alpha"
246
+ merge_method = "rebase"
247
+ merge_delete_branch = true
248
+ merge_pull = true
249
+ automation_mode = "AUTO_CREATE_PR"
250
+ ```
251
+
252
+ Example:
253
+
254
+ ```bash
255
+ jules-agent --repo example-org/example-repo "Split the parser from the dispatcher"
256
+ ```
257
+
258
+ ## Output
259
+
260
+ The CLI prints one line per dispatch result:
261
+
262
+ ```text
263
+ Jules dispatch result(s): 2
264
+ 1. [success] [123456] Update the parser
265
+ 2. [success] [123457] Add tests
266
+ ```
267
+
268
+ If the planning tool fails, the command exits non-zero and includes the command plus captured stdout and stderr.
269
+ If a Jules dispatch fails, the CLI prints `failure` for that subtask, shows the captured command output, and exits non-zero after the first failure.
270
+ If confirmation mode is enabled and stdin is not interactive, the CLI exits with an error and tells you to use `--no-confirm`.
271
+ If a command is run without a `task_id` and stdin is not interactive, the CLI exits with an error.
272
+
273
+ ## How It Works
274
+
275
+ The planning step expects JSON shaped like this:
276
+
277
+ ```json
278
+ {
279
+ "strategy": "single_session",
280
+ "tasks": [
281
+ { "title": "First task" }
282
+ ]
283
+ }
284
+ ```
285
+
286
+ `strategy` can be `single_session` or `sequential_subtasks`. Each task can also be a plain string. The dispatcher turns the title and any available details into the prompt passed to Jules.
287
+
288
+ ## Development
289
+
290
+ Run the tests with:
291
+
292
+ ```bash
293
+ python3 -m pytest
294
+ ```
295
+
296
+ The tests cover JSON parsing, subtask normalization, session ID extraction, and the end-to-end pipeline error path.
@@ -0,0 +1,255 @@
1
+ # jules-agent
2
+
3
+ `jules-agent` is a CLI for handing off work to Jules with a little more structure around it.
4
+ It turns a task into a plan, sends the work to Jules, and helps you keep moving through feedback, review, and merge.
5
+
6
+ - 日本語版: [README_ja.md](README_ja.md)
7
+
8
+ ## What it does
9
+
10
+ `jules-agent` helps with the full loop around a coding task:
11
+
12
+ - turn a single request into a workable plan
13
+ - surface clarification questions before the work starts
14
+ - send the task to Jules
15
+ - collect feedback and move the task forward
16
+ - review the result and merge the pull request when it is ready
17
+
18
+ It is useful whether you want a light planning pass or a more hands-on loop around implementation and review.
19
+
20
+ ## Requirements
21
+
22
+ - Python 3.12 or newer
23
+ - `git` available on `PATH`
24
+ - `JULES_API_KEY` set in the environment, or `api_key` configured in TOML
25
+ - `GITHUB_TOKEN` set when you want review, merge, or PR status syncing
26
+
27
+ Repository assumptions:
28
+
29
+ - you are inside a Git repository
30
+ - the repository has a GitHub remote
31
+ - Jules is already set up for the GitHub account as an app and has access to the repository
32
+
33
+ `jules-agent` talks to the Jules API directly, so a local `jules` CLI binary is not required.
34
+
35
+ If you do not run the command inside a git repository, pass `--repo owner/name`.
36
+
37
+ ## Install
38
+
39
+ From PyPI:
40
+
41
+ ```bash
42
+ pipx install jules-agent
43
+ ```
44
+
45
+ ```bash
46
+ uv tool install jules-agent
47
+ ```
48
+
49
+ ```bash
50
+ pip install jules-agent
51
+ ```
52
+
53
+ From a local checkout:
54
+
55
+ ```bash
56
+ pip install -e .
57
+ ```
58
+
59
+ After installing, the `jules-agent` command is available on your `PATH`.
60
+
61
+ ## Usage
62
+
63
+ ```bash
64
+ jules-agent [flags] <command> [args]
65
+ ```
66
+
67
+ The common flow is:
68
+
69
+ 1. Create a task with `run`.
70
+ 2. Check progress with `status` and `sync`.
71
+ 3. Approve, give feedback, or send a direct message if needed.
72
+ 4. Review the pull request.
73
+ 5. Merge when it is ready.
74
+
75
+ ### Subcommands
76
+
77
+ - `run [flags] <task>`: Analyze a new task with the configured planning tool and dispatch it to Jules.
78
+ - In interactive mode, it may first ask clarification questions before generating a plan.
79
+ - `--no-confirm`: Skip the confirmation loop and dispatch immediately.
80
+ - `--auto-plan-approval`: Automatically approve the task plan (forces `requirePlanApproval=false`).
81
+ - `--automation-mode <mode>`: Specify the automation mode for the Jules session.
82
+ - `AUTO_CREATE_PR` (default): Whenever a final code patch is generated in the session, automatically create a branch and a pull request for it.
83
+ - `AUTOMATION_MODE_UNSPECIFIED`: The automation mode is unspecified. Default to no automation.
84
+ - `import <session_id>`: Import an existing Jules session into the local state.
85
+ - Supports both bare IDs (e.g., `12345`) and full session names (e.g., `sessions/12345`).
86
+ - `status`: Show the current local state, including runs and tasks. By default, it only shows runs with `planned` or `running` status.
87
+ - `-a`, `--all`: Show all runs, including completed, failed, and cancelled.
88
+ - `--show-activities`: Show detailed session activities for each task.
89
+ - `sync`: Synchronize the local state with the Jules API and GitHub (to update PR status).
90
+ - `advance [flags]`: Automatically or interactively advance work across the next active task. For `sequential_subtasks`, a successful merge also dispatches the next `planned` task in the same run.
91
+ - `cron [flags]`: Non-interactive background execution. This is a purely automated version of `advance` that never asks for input, and it also dispatches the next `planned` task after a successful sequential merge.
92
+ - `approve [task_id]`: Manually approve the proposed plan for a specific task. If `task_id` is omitted, it shows a list of tasks awaiting plan approval.
93
+ - `send [task_id] message`: Send a manual message to a task's Jules session. If `task_id` is omitted, it shows a list of active tasks. If your message contains spaces and you omit `task_id`, the message must be quoted (e.g., `jules-agent send "hello world"`).
94
+ - `feedback [task_id]`: Enter an interactive feedback loop to refine a task's plan or reply. If `task_id` is omitted, it shows a list of eligible tasks.
95
+ - `review [task_id]`: Run a review for a task with an open pull request. If `task_id` is omitted, it shows a list of tasks with open pull requests.
96
+ - `merge [task_id]`: Manually merge the pull request associated with a task. If `task_id` is omitted, it first performs a full state synchronization and then shows a list of tasks with open pull requests.
97
+ - `next [run_id]`: Dispatch the next task in a sequential run. If `run_id` is omitted, it shows a list of active sequential runs with planned tasks.
98
+ - `--automation-mode <mode>`: Specify the automation mode for the Jules session (e.g., `AUTO_CREATE_PR` or `AUTOMATION_MODE_UNSPECIFIED`).
99
+ - `delete run [run_id]`: Delete a run and its tasks from the local state.
100
+ - `delete task [task_id]`: Delete a specific task from the local state. If the run becomes empty, it is also removed.
101
+ - `rm`: An alias for `delete`.
102
+ - Omitting `run_id` or `task_id` triggers an interactive selection prompt.
103
+ - `--dry-run`: Show what would be deleted without making changes.
104
+ - `--yes`, `-y`: Skip confirmation prompts and proceed immediately.
105
+
106
+ ### Global Flags
107
+
108
+ - `--repo owner/name`: Override the target repository.
109
+ - `--tool-bin /path/to/tool`: Path to the backend tool executable.
110
+ - `--tool <name>`: Backend tool to use.
111
+ - `--gemini-skip-trust`: Pass `--skip-trust` to the Gemini CLI adapter.
112
+ - `--plan-tool <name>`: Tool override for the planning phase.
113
+ - `--approve-tool <name>`: Tool override for the approval phase.
114
+ - `--feedback-tool <name>`: Tool override for the feedback phase.
115
+ - `--review-tool <name>`: Tool override for the review phase.
116
+ - `--config /path/to/config.toml`: Specify a custom configuration file.
117
+
118
+ Supported backend tools are `codex`, `claude`, `gemini`, `opencode`, `copilot`, and `cline`.
119
+ Use `--tool` to set one default backend, or override individual phases with `--plan-tool`, `--approve-tool`, `--feedback-tool`, and `--review-tool`.
120
+
121
+ The `--tool-bin` flag and `tool_bin` config field let you point at a specific backend binary.
122
+
123
+ ### Automation Flags (for `advance` and `cron`)
124
+
125
+ - `--auto-plan-approval`: Automatically approve plans when recommended by the planning tool.
126
+ - `--auto-feedback`: Automatically send suggested feedback messages.
127
+ - `--auto-merge`: Automatically merge pull requests when they are ready.
128
+ - `--auto`: Enable both plan approval and feedback (does NOT include merge).
129
+ - `--json`: Emit the result as a single JSON object.
130
+
131
+ ### Examples
132
+
133
+ ```bash
134
+ # 1. Create a task
135
+ jules-agent run "Split the parser from the dispatcher"
136
+
137
+ # 2. Check progress and capture the run/task IDs
138
+ jules-agent status
139
+
140
+ # 3. Refresh local state from Jules and GitHub
141
+ jules-agent sync
142
+
143
+ # 4. If the task is waiting for a plan decision, approve it
144
+ jules-agent approve RUN_ID:TASK_ID
145
+
146
+ # Or, if the plan needs changes, give feedback instead
147
+ jules-agent feedback RUN_ID:TASK_ID
148
+
149
+ # 5. Review the pull request once Jules opens one
150
+ jules-agent review RUN_ID:TASK_ID
151
+
152
+ # 6. Merge the pull request when it is ready
153
+ jules-agent merge RUN_ID:TASK_ID
154
+ ```
155
+
156
+ For a sequential run, you can keep going with:
157
+
158
+ ```bash
159
+ # Dispatch the next planned task in the run
160
+ jules-agent next RUN_ID
161
+
162
+ # Or let the tool advance work and merge automatically
163
+ jules-agent advance --auto
164
+ ```
165
+
166
+ ## Configuration
167
+
168
+ `jules-agent` can be configured using TOML files. It searches for configuration in the following locations (in order of increasing priority):
169
+
170
+ 1. `~/.jules-agent.toml`
171
+ 2. `~/.config/jules-agent/config.toml`
172
+ 3. `./.jules-agent.toml`
173
+ 4. `./jules-agent.toml`
174
+ 5. A custom file specified via `--config`
175
+
176
+ Settings in the configuration file have lower priority than environment variables and command-line flags. For automation flags, the priority is:
177
+ 1. Individual CLI flag (e.g., `--auto-merge`, `--automation-mode`)
178
+ 2. The `--auto` flag (sets approval and feedback to true)
179
+ 3. Configuration file settings
180
+ 4. Default values (auto_plan_approval=true, others=false, automation_mode="AUTO_CREATE_PR")
181
+
182
+ ### GitHub Token
183
+
184
+ `jules-agent` reads `GITHUB_TOKEN` from the environment, or `github_token` from the TOML configuration file.
185
+
186
+ Need permissions:
187
+ - pull-requests: write
188
+ - issues: write
189
+ - contents: write
190
+
191
+ ### Supported Settings
192
+
193
+ ```toml
194
+ api_key = "your-jules-api-key"
195
+ repo = "owner/repo"
196
+ github_token = "ghp_your-github-token"
197
+ tool_bin = "path/to/tool"
198
+ tool = "codex"
199
+ gemini_skip_trust = false
200
+ plan_tool = "claude"
201
+ approve_tool = "gemini"
202
+ feedback_tool = "opencode"
203
+ review_tool = "copilot"
204
+ base_url = "https://jules.googleapis.com/v1alpha"
205
+ merge_method = "rebase"
206
+ merge_delete_branch = true
207
+ merge_pull = true
208
+ automation_mode = "AUTO_CREATE_PR"
209
+ ```
210
+
211
+ Example:
212
+
213
+ ```bash
214
+ jules-agent --repo example-org/example-repo "Split the parser from the dispatcher"
215
+ ```
216
+
217
+ ## Output
218
+
219
+ The CLI prints one line per dispatch result:
220
+
221
+ ```text
222
+ Jules dispatch result(s): 2
223
+ 1. [success] [123456] Update the parser
224
+ 2. [success] [123457] Add tests
225
+ ```
226
+
227
+ If the planning tool fails, the command exits non-zero and includes the command plus captured stdout and stderr.
228
+ If a Jules dispatch fails, the CLI prints `failure` for that subtask, shows the captured command output, and exits non-zero after the first failure.
229
+ If confirmation mode is enabled and stdin is not interactive, the CLI exits with an error and tells you to use `--no-confirm`.
230
+ If a command is run without a `task_id` and stdin is not interactive, the CLI exits with an error.
231
+
232
+ ## How It Works
233
+
234
+ The planning step expects JSON shaped like this:
235
+
236
+ ```json
237
+ {
238
+ "strategy": "single_session",
239
+ "tasks": [
240
+ { "title": "First task" }
241
+ ]
242
+ }
243
+ ```
244
+
245
+ `strategy` can be `single_session` or `sequential_subtasks`. Each task can also be a plain string. The dispatcher turns the title and any available details into the prompt passed to Jules.
246
+
247
+ ## Development
248
+
249
+ Run the tests with:
250
+
251
+ ```bash
252
+ python3 -m pytest
253
+ ```
254
+
255
+ The tests cover JSON parsing, subtask normalization, session ID extraction, and the end-to-end pipeline error path.
@@ -0,0 +1,43 @@
1
+ [build-system]
2
+ requires = ["setuptools>=69"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "jules-agent"
7
+ version = "0.1.2"
8
+ description = "Decompose a task with Codex and dispatch the subtasks to Jules."
9
+ requires-python = ">=3.12"
10
+ readme = { file = "README.md", content-type = "text/markdown" }
11
+ license = { file = "LICENSE" }
12
+ authors = [
13
+ { name = "ship" },
14
+ ]
15
+ dependencies = [
16
+ "httpx",
17
+ ]
18
+ urls = { Repository = "https://github.com/shipwebdotjp/jules-agent-orchestra" }
19
+ classifiers = [
20
+ "License :: OSI Approved :: MIT License",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3 :: Only",
23
+ ]
24
+
25
+ [project.optional-dependencies]
26
+ dev = [
27
+ "pytest",
28
+ "respx",
29
+ "pytest-mock",
30
+ ]
31
+
32
+ [project.scripts]
33
+ jules-agent = "jules_agent.cli:main"
34
+
35
+ [tool.setuptools]
36
+ package-dir = {"" = "src"}
37
+
38
+ [tool.setuptools.packages.find]
39
+ where = ["src"]
40
+
41
+ [tool.pytest.ini_options]
42
+ testpaths = ["tests"]
43
+ pythonpath = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """jules-agent package."""
2
+
3
+ __all__ = ["__version__"]
4
+ __version__ = "0.1.2"
@@ -0,0 +1,5 @@
1
+ from .cli import main
2
+
3
+
4
+ if __name__ == "__main__":
5
+ raise SystemExit(main())