{"id":48553125,"url":"https://github.com/grp06/slop-janitor","last_synced_at":"2026-04-08T09:31:17.516Z","repository":{"id":345157330,"uuid":"1184750908","full_name":"grp06/slop-janitor","owner":"grp06","description":"Repeatable multi-turn Codex refactor loop. ⭐️ star if you like it! ⭐️","archived":false,"fork":false,"pushed_at":"2026-03-18T00:09:39.000Z","size":1027,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-18T12:38:16.513Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/grp06.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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-03-17T22:38:05.000Z","updated_at":"2026-03-18T12:23:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/grp06/slop-janitor","commit_stats":null,"previous_names":["grp06/codex-refactor-loop"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/grp06/slop-janitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grp06%2Fslop-janitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grp06%2Fslop-janitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grp06%2Fslop-janitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grp06%2Fslop-janitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grp06","download_url":"https://codeload.github.com/grp06/slop-janitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grp06%2Fslop-janitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31549332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"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-04-08T09:31:16.206Z","updated_at":"2026-04-08T09:31:17.503Z","avatar_url":"https://github.com/grp06.png","language":"Python","funding_links":[],"categories":["Codex Workflow Frameworks"],"sub_categories":[],"readme":"# `slop-janitor`\n\n![slop-janitor](slop-janitor.png)\n\n**Important: you must clone both this repo and the open-source Codex repo.** `slop-janitor` talks directly to Codex's app-server implementation, so it will not work with only this repository checked out.\n\n`slop-janitor` automatically makes a repo cleaner, simpler, and more reliable.\n\nUsing Codex well usually means manually queuing a long chain of follow-up messages:\n\n- ask Codex what the best refactor is\n- ask it to improve that plan\n- ask it to improve it again\n- ask it to implement the plan\n- ask it to review the result\n- ask it to review it again with fresh eyes\n\n`slop-janitor` runs that loop for you on one thread.\n\nIt follows the `PLANS.md` pattern from OpenAI's Codex exec plans guide: plan, improve the plan, implement, and review. That is the basic trick for keeping an agent on the same problem for a long time instead of resetting every turn. Background: [Codex Exec Plans](https://developers.openai.com/cookbook/articles/codex_exec_plans).\n\nThis tool uses the account you sign into Codex with for inference and token usage.\n\nIt also writes a complete run log, so the session is inspectable after the fact rather than something that only existed in the terminal.\n\nBy default, one cycle is:\n\n1. `execplan-create`\n2. `execplan-improve` x4\n3. `implement-execplan`\n4. `review-recent-work` x5\n\nYou can change the number of full cycles, improvement passes, and review passes.\n\n## Bundled Skills\n\nThe loop is built from a small set of repo-local skills in `.agents/skills`:\n\n- `find-best-refactor`: finds the highest-leverage refactor.\n- `execplan-create`: turns a prompt into an exec plan.\n- `execplan-improve`: pressure-tests and rewrites that plan against the real codebase.\n- `implement-execplan`: implements the plan.\n- `review-recent-work`: reviews the result with fresh eyes.\n\nThe most important step is `execplan-improve`. Fixing a weak plan is cheaper than fixing bugs later.\n\n## Prerequisites\n\n- Python 3.11 or newer.\n- Rust and `cargo`.\n- A separate clone of the open-source Codex repository.\n- A Codex login.\n\nThe bundled skills used by `slop-janitor` live in `.agents/skills` inside this repository.\n\n## Setup\n\nClone this repository and clone Codex separately:\n\n```bash\ngit clone https://github.com/grp06/slop-janitor.git\ngit clone https://github.com/openai/codex.git\n```\n\nPoint `slop-janitor` at the Codex Rust workspace:\n\n```bash\nexport CODEX_WORKSPACE=/path/to/codex/codex-rs\n```\n\nYou can also pass the path per command with `--codex-workspace /path/to/codex/codex-rs`.\n\nAuthenticate through the wrapped Codex login flow:\n\n```bash\ncd slop-janitor\n./slop-janitor auth login\n./slop-janitor auth login --device-auth\n./slop-janitor auth status\n./slop-janitor auth logout\n```\n\nThe auth wrapper keeps stdin, stdout, and stderr attached to the terminal, so it behaves like native `codex login`. If your Codex access comes through ChatGPT, it will use that account. Details: [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan).\n\n## Basic Use\n\nThe most natural use is refactor mode. Run it from the repository you want to improve:\n\n```bash\ncd /path/to/target-repo\n/path/to/slop-janitor/slop-janitor --mode refactor\n```\n\nAdd guidance if you want to steer the refactor:\n\n```bash\ncd /path/to/target-repo\n/path/to/slop-janitor/slop-janitor --mode refactor --prompt \"focus on testability and simplifying boundaries\"\n```\n\nRun the default planning-first workflow if you want to start from an open-ended implementation prompt instead:\n\n```bash\ncd /path/to/target-repo\n/path/to/slop-janitor/slop-janitor --prompt \"help me build a CRM\"\n```\n\nIncrease the amount of iteration:\n\n```bash\ncd /path/to/target-repo\n/path/to/slop-janitor/slop-janitor --prompt \"help me build a CRM\" --cycles 2 --improvements 5 --review 3\n```\n\n`slop-janitor` always targets the directory you launch it from, not the `slop-janitor` repository.\n\n## Modes And Counts\n\n`--mode pipeline` is the default. It requires `--prompt` and starts with `execplan-create`.\n\n`--mode refactor` keeps the same follow-up structure, but replaces stage 1 with `find-best-refactor`. `--prompt` is optional in refactor mode. If you omit it, the first stage asks for the single highest-leverage refactor in the current repository.\n\n`--cycles` controls how many times the full loop runs.\n\n`--improvements` controls how many `execplan-improve` turns run inside each cycle.\n\n`--review` controls how many `review-recent-work` turns run inside each cycle.\n\nDefaults:\n\n- `--cycles 1`\n- `--improvements 4`\n- `--review 5`\n\nWhen `--cycles` is greater than 1, stage labels in the run log are cycle-qualified, for example `cycle-2-execplan-create`.\n\n## Codex Workspace Configuration\n\nWhen `slop-janitor` launches the real Codex app-server or wrapped auth commands, it resolves the Codex workspace in this order:\n\n1. `--codex-workspace /path/to/codex-rs`\n2. `CODEX_WORKSPACE`\n\nIf neither is set, the command fails with a clear setup error.\n\nExamples:\n\n```bash\n./slop-janitor --codex-workspace /path/to/codex/codex-rs --prompt \"help me build a CRM\"\n./slop-janitor auth --codex-workspace /path/to/codex/codex-rs login\n```\n\n## What It Actually Does\n\nBefore stage 1, the client performs:\n\n1. `initialize` with `capabilities.experimentalApi = true`\n2. `initialized`\n3. `account/read`\n4. `thread/start`\n\nIf `account/read` says OpenAI auth is required and no account is logged in, the command fails immediately and tells you to run `./slop-janitor auth login`.\n\nAfter that, every stage runs as a `turn/start` on the same thread. That is what gives the workflow continuity. The implementation and review stages see the plan that was just created and improved.\n\n## Output Model\n\nThe terminal is intentionally sparse. During a run, it shows:\n\n- agent-message commentary\n- final agent-message text\n- token usage\n\nEverything else goes to the run log:\n\n- stage banners\n- command output\n- file-change progress\n- MCP progress\n- item lifecycle notices\n- failure details\n\nEach run writes a full log to `runs/`. Log filenames start with the basename of the directory you launched from, followed by a UTC timestamp, for example `my-repo-20260317T213000Z.log`.\n\nThis split is deliberate. The terminal stays readable while the log remains complete.\n\n## Reliability Contract\n\n- Model and sandbox settings are inherited from your current Codex config. In v1, `slop-janitor` only overrides `cwd` and `approvalPolicy`.\n- The thread uses `approvalPolicy: \"never\"`.\n- If the server asks for approvals, user input, permissions, MCP elicitation, or ChatGPT token refresh, `slop-janitor` responds deterministically, marks the stage failed, and exits after the matching `turn/completed`.\n- Successful turns require real token data from `thread/tokenUsage/updated`. If a turn completes successfully without token usage, the run fails instead of printing invented zeros.\n- Skill paths are validated before the app-server starts, so broken local setup fails early.\n\nThe tool is strict on purpose. When something is wrong, it should stop in a way you can diagnose.\n\n## Tests\n\nRun the test suite from the repository root:\n\n```bash\npython3 -m unittest discover -s tests -p 'test_*.py' -v\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrp06%2Fslop-janitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrp06%2Fslop-janitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrp06%2Fslop-janitor/lists"}