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.
- jules_agent-0.1.2/LICENSE +21 -0
- jules_agent-0.1.2/PKG-INFO +296 -0
- jules_agent-0.1.2/README.md +255 -0
- jules_agent-0.1.2/pyproject.toml +43 -0
- jules_agent-0.1.2/setup.cfg +4 -0
- jules_agent-0.1.2/src/jules_agent/__init__.py +4 -0
- jules_agent-0.1.2/src/jules_agent/__main__.py +5 -0
- jules_agent-0.1.2/src/jules_agent/cli/__init__.py +379 -0
- jules_agent-0.1.2/src/jules_agent/cli/__main__.py +5 -0
- jules_agent-0.1.2/src/jules_agent/cli/advance_core.py +388 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/__init__.py +29 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/advance.py +64 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/approve.py +48 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/delete.py +119 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/feedback.py +247 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/import_command.py +185 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/merge.py +139 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/next.py +51 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/review.py +48 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/run.py +237 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/send.py +50 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/status.py +44 -0
- jules_agent-0.1.2/src/jules_agent/cli/commands/sync.py +118 -0
- jules_agent-0.1.2/src/jules_agent/cli/io.py +193 -0
- jules_agent-0.1.2/src/jules_agent/cli/state.py +315 -0
- jules_agent-0.1.2/src/jules_agent/client.py +156 -0
- jules_agent-0.1.2/src/jules_agent/codex.py +408 -0
- jules_agent-0.1.2/src/jules_agent/config.py +80 -0
- jules_agent-0.1.2/src/jules_agent/git.py +98 -0
- jules_agent-0.1.2/src/jules_agent/github.py +120 -0
- jules_agent-0.1.2/src/jules_agent/models.py +330 -0
- jules_agent-0.1.2/src/jules_agent/persistence.py +55 -0
- jules_agent-0.1.2/src/jules_agent/pipeline.py +757 -0
- jules_agent-0.1.2/src/jules_agent/review.py +267 -0
- jules_agent-0.1.2/src/jules_agent.egg-info/PKG-INFO +296 -0
- jules_agent-0.1.2/src/jules_agent.egg-info/SOURCES.txt +55 -0
- jules_agent-0.1.2/src/jules_agent.egg-info/dependency_links.txt +1 -0
- jules_agent-0.1.2/src/jules_agent.egg-info/entry_points.txt +2 -0
- jules_agent-0.1.2/src/jules_agent.egg-info/requires.txt +6 -0
- jules_agent-0.1.2/src/jules_agent.egg-info/top_level.txt +1 -0
- jules_agent-0.1.2/tests/test_advance.py +329 -0
- jules_agent-0.1.2/tests/test_claude_adapter.py +67 -0
- jules_agent-0.1.2/tests/test_cli.py +210 -0
- jules_agent-0.1.2/tests/test_client.py +71 -0
- jules_agent-0.1.2/tests/test_config.py +71 -0
- jules_agent-0.1.2/tests/test_feedback.py +188 -0
- jules_agent-0.1.2/tests/test_github.py +135 -0
- jules_agent-0.1.2/tests/test_import.py +166 -0
- jules_agent-0.1.2/tests/test_interactive_selection.py +148 -0
- jules_agent-0.1.2/tests/test_merge.py +175 -0
- jules_agent-0.1.2/tests/test_next_command.py +110 -0
- jules_agent-0.1.2/tests/test_opencode.py +66 -0
- jules_agent-0.1.2/tests/test_pipeline.py +147 -0
- jules_agent-0.1.2/tests/test_review.py +155 -0
- jules_agent-0.1.2/tests/test_status.py +65 -0
- jules_agent-0.1.2/tests/test_sync.py +123 -0
- 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"]
|