{"id":50610687,"url":"https://github.com/shipwebdotjp/jules-agent-orchestra","last_synced_at":"2026-06-06T03:30:37.976Z","repository":{"id":358195729,"uuid":"1240391209","full_name":"shipwebdotjp/jules-agent-orchestra","owner":"shipwebdotjp","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-24T11:55:44.000Z","size":290,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T13:25:20.987Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shipwebdotjp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-16T04:45:37.000Z","updated_at":"2026-05-24T11:55:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shipwebdotjp/jules-agent-orchestra","commit_stats":null,"previous_names":["shipwebdotjp/jules-agent-orchestra"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shipwebdotjp/jules-agent-orchestra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shipwebdotjp%2Fjules-agent-orchestra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shipwebdotjp%2Fjules-agent-orchestra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shipwebdotjp%2Fjules-agent-orchestra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shipwebdotjp%2Fjules-agent-orchestra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shipwebdotjp","download_url":"https://codeload.github.com/shipwebdotjp/jules-agent-orchestra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shipwebdotjp%2Fjules-agent-orchestra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33968711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-06T03:30:37.211Z","updated_at":"2026-06-06T03:30:37.962Z","avatar_url":"https://github.com/shipwebdotjp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jules-agent\n\n`jules-agent` is a CLI for handing off work to Jules with a little more structure around it.\nIt turns a task into a plan, sends the work to Jules, and helps you keep moving through feedback, review, and merge.\n\n- 日本語版: [README_ja.md](README_ja.md)\n\n## What it does\n\n`jules-agent` helps with the full loop around a coding task:\n\n- turn a single request into a workable plan\n- surface clarification questions before the work starts\n- send the task to Jules\n- collect feedback and move the task forward\n- review the result and merge the pull request when it is ready\n\nIt is useful whether you want a light planning pass or a more hands-on loop around implementation and review.\n\n## Requirements\n\n- Python 3.12 or newer\n- `git` available on `PATH`\n- `JULES_API_KEY` set in the environment, or `api_key` configured in TOML\n- `GITHUB_TOKEN` set when you want review, merge, or PR status syncing\n\nRepository assumptions:\n\n- you are inside a Git repository\n- the repository has a GitHub remote\n- Jules is already set up for the GitHub account as an app and has access to the repository\n\n`jules-agent` talks to the Jules API directly, so a local `jules` CLI binary is not required.\n\nIf you do not run the command inside a git repository, pass `--repo owner/name`.\n\n## Install\n\nFrom GitHub:\n\n```bash\npipx install git+https://github.com/shipwebdotjp/jules-agent-orchestra.git\n```\n\n```bash\nuv tool install git+https://github.com/shipwebdotjp/jules-agent-orchestra.git\n```\n\nFrom a local checkout:\n\n```bash\npip install -e .\n```\n\nAfter installing, the `jules-agent` command is available on your `PATH`.\n\n## Usage\n\n```bash\njules-agent [flags] \u003ccommand\u003e [args]\n```\n\nThe common flow is:\n\n1. Create a task with `run`.\n2. Check progress with `status` and `sync`.\n3. Approve, give feedback, or send a direct message if needed.\n4. Review the pull request.\n5. Merge when it is ready.\n\n### Subcommands\n\n- `run [flags] \u003ctask\u003e`: Analyze a new task with the configured planning tool and dispatch it to Jules.\n  - In interactive mode, it may first ask clarification questions before generating a plan.\n  - `--no-confirm`: Skip the confirmation loop and dispatch immediately.\n  - `--auto-plan-approval`: Automatically approve the task plan (forces `requirePlanApproval=false`).\n  - `--automation-mode \u003cmode\u003e`: Specify the automation mode for the Jules session.\n    - `AUTO_CREATE_PR` (default): Whenever a final code patch is generated in the session, automatically create a branch and a pull request for it.\n    - `AUTOMATION_MODE_UNSPECIFIED`: The automation mode is unspecified. Default to no automation.\n- `import \u003csession_id\u003e`: Import an existing Jules session into the local state.\n  - Supports both bare IDs (e.g., `12345`) and full session names (e.g., `sessions/12345`).\n- `status`: Show the current local state, including runs and tasks. By default, it only shows runs with `planned` or `running` status.\n  - `-a`, `--all`: Show all runs, including completed, failed, and cancelled.\n  - `--show-activities`: Show detailed session activities for each task.\n- `sync`: Synchronize the local state with the Jules API and GitHub (to update PR status).\n- `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.\n- `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.\n- `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.\n- `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\"`).\n- `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.\n- `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.\n- `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.\n- `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.\n  - `--automation-mode \u003cmode\u003e`: Specify the automation mode for the Jules session (e.g., `AUTO_CREATE_PR` or `AUTOMATION_MODE_UNSPECIFIED`).\n- `delete run [run_id]`: Delete a run and its tasks from the local state.\n- `delete task [task_id]`: Delete a specific task from the local state. If the run becomes empty, it is also removed.\n- `rm`: An alias for `delete`.\n  - Omitting `run_id` or `task_id` triggers an interactive selection prompt.\n  - `--dry-run`: Show what would be deleted without making changes.\n  - `--yes`, `-y`: Skip confirmation prompts and proceed immediately.\n\n### Global Flags\n\n- `--repo owner/name`: Override the target repository.\n- `--tool-bin /path/to/tool`: Path to the backend tool executable.\n- `--tool \u003cname\u003e`: Backend tool to use.\n- `--gemini-skip-trust`: Pass `--skip-trust` to the Gemini CLI adapter.\n- `--plan-tool \u003cname\u003e`: Tool override for the planning phase.\n- `--approve-tool \u003cname\u003e`: Tool override for the approval phase.\n- `--feedback-tool \u003cname\u003e`: Tool override for the feedback phase.\n- `--review-tool \u003cname\u003e`: Tool override for the review phase.\n- `--config /path/to/config.toml`: Specify a custom configuration file.\n\nSupported backend tools are `codex`, `claude`, `gemini`, `opencode`, `copilot`, and `cline`.\nUse `--tool` to set one default backend, or override individual phases with `--plan-tool`, `--approve-tool`, `--feedback-tool`, and `--review-tool`.\n\nThe `--tool-bin` flag and `tool_bin` config field let you point at a specific backend binary.\n\n### Automation Flags (for `advance` and `cron`)\n\n- `--auto-plan-approval`: Automatically approve plans when recommended by the planning tool.\n- `--auto-feedback`: Automatically send suggested feedback messages.\n- `--auto-merge`: Automatically merge pull requests when they are ready.\n- `--auto`: Enable both plan approval and feedback (does NOT include merge).\n- `--json`: Emit the result as a single JSON object.\n\n### Examples\n\n```bash\n# 1. Create a task\njules-agent run \"Split the parser from the dispatcher\"\n\n# 2. Check progress and capture the run/task IDs\njules-agent status\n\n# 3. Refresh local state from Jules and GitHub\njules-agent sync\n\n# 4. If the task is waiting for a plan decision, approve it\njules-agent approve RUN_ID:TASK_ID\n\n#    Or, if the plan needs changes, give feedback instead\njules-agent feedback RUN_ID:TASK_ID\n\n# 5. Review the pull request once Jules opens one\njules-agent review RUN_ID:TASK_ID\n\n# 6. Merge the pull request when it is ready\njules-agent merge RUN_ID:TASK_ID\n```\n\nFor a sequential run, you can keep going with:\n\n```bash\n# Dispatch the next planned task in the run\njules-agent next RUN_ID\n\n# Or let the tool advance work and merge automatically\njules-agent advance --auto\n```\n\n## Configuration\n\n`jules-agent` can be configured using TOML files. It searches for configuration in the following locations (in order of increasing priority):\n\n1. `~/.jules-agent.toml`\n2. `~/.config/jules-agent/config.toml`\n3. `./.jules-agent.toml`\n4. `./jules-agent.toml`\n5. A custom file specified via `--config`\n\nSettings in the configuration file have lower priority than environment variables and command-line flags. For automation flags, the priority is:\n1. Individual CLI flag (e.g., `--auto-merge`, `--automation-mode`)\n2. The `--auto` flag (sets approval and feedback to true)\n3. Configuration file settings\n4. Default values (auto_plan_approval=true, others=false, automation_mode=\"AUTO_CREATE_PR\")\n\n### GitHub Token\n\n`jules-agent` reads `GITHUB_TOKEN` from the environment, or `github_token` from the TOML configuration file.\n\nNeed permissions:\n- pull-requests: write\n- issues: write\n- contents: write\n\n### Supported Settings\n\n```toml\napi_key = \"your-jules-api-key\"\nrepo = \"owner/repo\"\ngithub_token = \"ghp_your-github-token\"\ntool_bin = \"path/to/tool\"\ntool = \"codex\"\ngemini_skip_trust = false\nplan_tool = \"claude\"\napprove_tool = \"gemini\"\nfeedback_tool = \"opencode\"\nreview_tool = \"copilot\"\nbase_url = \"https://jules.googleapis.com/v1alpha\"\nmerge_method = \"rebase\"\nmerge_delete_branch = true\nmerge_pull = true\nautomation_mode = \"AUTO_CREATE_PR\"\n```\n\nExample:\n\n```bash\njules-agent --repo example-org/example-repo \"Split the parser from the dispatcher\"\n```\n\n## Output\n\nThe CLI prints one line per dispatch result:\n\n```text\nJules dispatch result(s): 2\n1. [success] [123456] Update the parser\n2. [success] [123457] Add tests\n```\n\nIf the planning tool fails, the command exits non-zero and includes the command plus captured stdout and stderr.\nIf a Jules dispatch fails, the CLI prints `failure` for that subtask, shows the captured command output, and exits non-zero after the first failure.\nIf confirmation mode is enabled and stdin is not interactive, the CLI exits with an error and tells you to use `--no-confirm`.\nIf a command is run without a `task_id` and stdin is not interactive, the CLI exits with an error.\n\n## How It Works\n\nThe planning step expects JSON shaped like this:\n\n```json\n{\n  \"strategy\": \"single_session\",\n  \"tasks\": [\n    { \"title\": \"First task\" }\n  ]\n}\n```\n\n`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.\n\n## Development\n\nRun the tests with:\n\n```bash\npython3 -m pytest\n```\n\nThe tests cover JSON parsing, subtask normalization, session ID extraction, and the end-to-end pipeline error path.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshipwebdotjp%2Fjules-agent-orchestra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshipwebdotjp%2Fjules-agent-orchestra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshipwebdotjp%2Fjules-agent-orchestra/lists"}