{"id":50405622,"url":"https://github.com/nikuscs/codex-multitask","last_synced_at":"2026-05-31T01:30:26.566Z","repository":{"id":357347942,"uuid":"1225446606","full_name":"nikuscs/codex-multitask","owner":"nikuscs","description":"Run parallel Codex workers from one prompt with explicit file ownership, tracked jobs, and isolated workspace support.","archived":false,"fork":false,"pushed_at":"2026-05-12T10:39:03.000Z","size":3322,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T12:32:37.462Z","etag":null,"topics":["ai-coding","codex","codex-cli","codex-plugin","developer-tools","parallel-agents"],"latest_commit_sha":null,"homepage":"https://github.com/nikuscs/codex-multitask","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikuscs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","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-04-30T09:32:48.000Z","updated_at":"2026-05-12T10:39:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nikuscs/codex-multitask","commit_stats":null,"previous_names":["nikuscs/codex-multitask"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/nikuscs/codex-multitask","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikuscs%2Fcodex-multitask","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikuscs%2Fcodex-multitask/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikuscs%2Fcodex-multitask/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikuscs%2Fcodex-multitask/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikuscs","download_url":"https://codeload.github.com/nikuscs/codex-multitask/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikuscs%2Fcodex-multitask/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33716338,"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-05-30T02:00:06.278Z","response_time":92,"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":["ai-coding","codex","codex-cli","codex-plugin","developer-tools","parallel-agents"],"created_at":"2026-05-31T01:30:22.069Z","updated_at":"2026-05-31T01:30:26.533Z","avatar_url":"https://github.com/nikuscs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# codex-multitask\n\n[![CI](https://github.com/nikuscs/codex-multitask/actions/workflows/ci.yml/badge.svg)](https://github.com/nikuscs/codex-multitask/actions/workflows/ci.yml)\n[![Marketplace](https://img.shields.io/badge/Codex-local%20marketplace-blue)](https://developers.openai.com/codex/plugins/build)\n\n`codex-multitask` runs one Codex splitter, validates a JSON worker plan, then fans out parallel `codex exec --json` workers with explicit file ownership.\n\nThis plugin is for Codex users who want a first-class Codex skill surface for parallel, file-owned Codex worker runs.\n\n![codex-multitask screenshot](assets/codex-demo.png)\n\n## What You Get\n\n- `multitask-setup` to verify Codex CLI availability and runtime state\n- `multitask-plan` to run the splitter only and inspect the worker plan\n- `multitask-run` to execute parallel Codex workers from one prompt\n- `multitask-status`, `multitask-result`, and `multitask-cancel` for tracked jobs\n- Shared-workspace mode by default, with optional `--isolated-workspaces`\n\n## Why This Exists\n\nNative Codex subagents are useful for in-session delegation. `codex-multitask` is different: it is a deterministic external orchestrator that creates an explicit JSON plan, assigns disjoint owned files, runs independent `codex exec --json` workers, and keeps per-worker logs, summaries, and patches.\n\n## Requirements\n\n- Codex CLI installed and on `PATH`\n- Codex CLI authenticated\n- Node.js `20+`\n- Git repository for normal workspace auditing\n\n## Install\n\n### Codex App\n\nPublished plugin install, once this repo has a marketplace release:\n\n```sh\ncodex plugin marketplace add nikuscs/codex-multitask\n```\n\nThis installs the Multitask plugin for Codex once the repo is published as a marketplace source.\n\n### Local Plugin Checkout\n\nFrom this repository root:\n\n```sh\ncodex plugin marketplace add .\n```\n\nThis works because this repo includes `.agents/plugins/marketplace.json`, matching the sibling `codex-cc-plugin` local marketplace shape. The marketplace name is `codex-multitask-local` so it can coexist with the Claude plugin's `local-repo` marketplace. Restart Codex after adding or changing the local marketplace.\n\nThe local marketplace entry points Codex at:\n\n```text\n./plugins/multitask\n```\n\n### Standalone CLI\n\nStandalone release install, once binaries are published:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/nikuscs/codex-multitask/main/scripts/install.sh | bash\n```\n\nThat installs:\n\n- `codex-multitask`\n- `multitask`\n\nto `~/.local/bin`.\n\nIn Codex CLI, use it as a shell command:\n\n```text\n!multitask setup\n!multitask plan --workers 4 \"Split this work\"\n!multitask run --workers 4 \"Implement this change\"\n```\n\n## First Run\n\nAfter install, Codex app should expose the plugin skills in the skill picker and plugin directory. Codex may render installed plugin actions with UI labels, but the stable skill names are lowercase.\n\nLook for:\n\n- `multitask-setup`\n- `multitask-plan`\n- `multitask-run`\n- `multitask-status`\n- `multitask-result`\n- `multitask-cancel`\n\nTry:\n\n```text\nUse the skill multitask-setup\n```\n\nIf Codex runs the skill instead of searching for `SKILL.md`, the plugin is installed correctly.\n\n## Usage\n\n### `multitask-plan`\n\nRuns the splitter only and prints the planned workers without spawning them.\n\n```text\nUse the skill multitask-plan to split the auth refactor into 4 workers\n```\n\nStandalone CLI:\n\n```sh\ncodex-multitask plan --workers 4 \"Refactor the auth module\"\n```\n\n### `multitask-run`\n\nRuns the splitter, validates the plan, and fans out Codex workers.\n\n```text\nUse the skill multitask-run to implement the docs cleanup in 3 workers\n```\n\nStandalone CLI:\n\n```sh\ncodex-multitask run --workers 4 \"Implement the auth refactor\"\ncodex-multitask run --workers 4 --isolated-workspaces \"Implement the auth refactor\"\n```\n\n### `multitask-status`, `multitask-result`, `multitask-cancel`\n\nUse these to inspect, fetch, or stop tracked multitask jobs.\n\n```sh\ncodex-multitask status \u003cjobId\u003e\ncodex-multitask result \u003cjobId\u003e\ncodex-multitask cancel \u003cjobId\u003e\n```\n\n## Codex CLI Usage\n\nUse the standalone binary from Codex CLI with `!multitask ...`.\n\n```text\n!multitask setup\n!multitask plan --workers 4 \"Split this task\"\n!multitask run --workers 4 \"Implement this change\"\n```\n\n## Test\n\n```sh\nbun run check\n```\n\n```sh\ncodex-multitask run --workers 4 \"Implement the auth refactor\"\ncodex-multitask plan --plan-file plan.md --workers 5\ncodex-multitask status \u003cjobId\u003e\ncodex-multitask result \u003cjobId\u003e\ncodex-multitask cancel \u003cjobId\u003e\n```\n\nDefault mode runs workers in the primary workspace and audits the final diff. Pass `--isolated-workspaces` to run each worker in a temporary git worktree and copy back only owned files after validation.\n\n## State\n\nRuntime state is stored under:\n\n`~/.codex/cache/multitask-handoff/\u003cworkspace-slug\u003e-\u003chash\u003e/`\n\nEach workspace gets:\n\n- `workspace.json`\n- `jobs/\u003cjob-id\u003e.json`\n- `logs/`\n- `sessions/\u003ccodex-session-id\u003e.json`\n- `runtime.json`\n\nPer-job worker traces are stored under each job directory.\n\n## Hooks\n\nRepo-local hook config is wired through:\n\n- `.codex/config.toml`\n- `.codex/hooks.json`\n\nThe plugin also ships reference hook config in `plugins/multitask/hooks/hooks.json`.\n\n## Development\n\nRun the full local check suite:\n\n```sh\nbun install\nbun run check\n```\n\nThat runs:\n\n- `oxlint`\n- `oxfmt --check`\n- `node --test tests/runtime.test.mjs`\n\n## Credits\n\n- Sibling implementation: [nikuscs/codex-cc-plugin](https://github.com/nikuscs/codex-cc-plugin)\n- This repo adapts that plugin shape for Codex-to-Codex parallel worker orchestration.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikuscs%2Fcodex-multitask","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikuscs%2Fcodex-multitask","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikuscs%2Fcodex-multitask/lists"}