{"id":51670902,"url":"https://github.com/scottconverse/antistallcodex","last_synced_at":"2026-07-15T00:03:44.378Z","repository":{"id":365930768,"uuid":"1274048686","full_name":"scottconverse/antistallcodex","owner":"scottconverse","description":"Codex Desktop Stop-hook sprint gate: AntistallON / AntistallOFF","archived":false,"fork":false,"pushed_at":"2026-06-19T13:06:55.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T15:12:10.052Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scottconverse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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-06-19T06:10:01.000Z","updated_at":"2026-06-19T13:06:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/scottconverse/antistallcodex","commit_stats":null,"previous_names":["scottconverse/antistallcodex"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/scottconverse/antistallcodex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fantistallcodex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fantistallcodex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fantistallcodex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fantistallcodex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scottconverse","download_url":"https://codeload.github.com/scottconverse/antistallcodex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fantistallcodex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35483861,"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-07-14T02:00:06.603Z","response_time":114,"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-07-15T00:03:43.685Z","updated_at":"2026-07-15T00:03:44.370Z","avatar_url":"https://github.com/scottconverse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AntiStallCodex\n\nA Codex Desktop Stop-hook sprint gate that keeps autonomous work from ending early.\n\nVersion 0.1.0 - MIT licensed - built for Codex Desktop and Codex hooks\n\n[Landing page](https://scottconverse.github.io/antistallcodex/)\n\nAntiStallCodex is the Codex-specific sibling of AntiStallClaude. It uses Codex's `Stop` hook to prevent the announce-then-halt failure: the agent says what it will do next, writes a tidy progress summary, and then stops with authorized work still sitting on the table.\n\n## The short version\n\nIn Codex Desktop, say:\n\n```text\nAntistallON: finish this task completely before stopping.\n```\n\nTo turn it off:\n\n```text\nAntistallOFF\n```\n\nThat is the intended interface. The Python helper exists so Codex can wire the hook and maintain state.\n\n## How it works\n\nCodex supports lifecycle hooks. `Stop` runs when a turn is about to stop. If a Stop hook returns:\n\n```json\n{\n  \"decision\": \"block\",\n  \"reason\": \"Keep working...\"\n}\n```\n\nCodex creates a continuation prompt from `reason` and keeps going.\n\nAntiStallCodex installs a global Stop hook inline in `~/.codex/config.toml`. The hook is inert unless a sprint has been armed for the current project directory. Once armed, Codex can stop only by writing a fresh one-use ticket:\n\n- `DONE` - the whole authorized queue is complete and the sprint disarms\n- `BLOCKED` - a human-only decision or external access blocks all useful progress\n- `QUESTION` - Codex asked the user something and needs the answer\n\n## Install\n\nClone and run:\n\n```bash\ngit clone https://github.com/scottconverse/antistallcodex.git\npython antistallcodex/install.py\n```\n\nThen in Codex Desktop, open `/hooks` and trust the AntiStallCodex hook if prompted. Hooks may require a fresh thread or app reload before they fire.\n\nThe installer:\n\n- copies `skill/antistall-codex/` into `~/.codex/skills/antistall-codex/`\n- writes or merges a global `~/.codex/config.toml` Stop hook\n- leaves the hook inert until `AntistallON` is used in a project\n\n## Desktop usage\n\nStart an enforced sprint:\n\n```text\nAntistallON: finish the installer fixes, run tests, and report only when done.\n```\n\nTurn it off:\n\n```text\nAntistallOFF\n```\n\nMark a legitimate stop:\n\n```text\nDone: all requested work is complete and verified.\n```\n\nor:\n\n```text\nBlocked: I need Scott to choose the release target.\n```\n\nor:\n\n```text\nQuestion: should this support Windows only or all platforms?\n```\n\nThe skill teaches Codex to map those plain-language requests to the helper's ticket commands.\n\n## Helper commands\n\nYou usually do not type these yourself in Codex Desktop. Codex can run them for you.\n\n```bash\npython ~/.codex/skills/antistall-codex/scripts/antistall.py on \"finish this sprint\"\npython ~/.codex/skills/antistall-codex/scripts/antistall.py off\npython ~/.codex/skills/antistall-codex/scripts/antistall.py status\npython ~/.codex/skills/antistall-codex/scripts/antistall.py done \"complete\"\npython ~/.codex/skills/antistall-codex/scripts/antistall.py blocked \"need credentials\"\npython ~/.codex/skills/antistall-codex/scripts/antistall.py question \"which option?\"\n```\n\nOn Windows the same script lives under:\n\n```text\n%USERPROFILE%\\.codex\\skills\\antistall-codex\\scripts\\antistall.py\n```\n\n## Safety\n\nAntiStallCodex is intentionally fail-open.\n\n- If no sprint is armed, the hook returns `{\"continue\": true}`.\n- If `stop_hook_active` is true, the hook allows the stop so it cannot loop on its own continuation.\n- If the per-session block counter is unreadable, corrupt, or unwritable, the hook allows the stop.\n- If the block cap is reached, the hook allows the stop and reports stale sprint state.\n\nThis protects against token-burning continuation loops.\n\n## State\n\nState lives under:\n\n```text\n~/.codex/antistall-codex/\n```\n\nSprints are keyed by normalized current working directory, so one global hook can protect many projects without affecting inactive ones.\n\n## Limitations\n\n- Codex must load and trust the hook. If hooks are disabled or untrusted, AntiStallCodex cannot enforce anything.\n- `Stop` hook continuation depends on Codex's hook implementation. Some Codex releases have had hook UI or continuation bugs; see `docs/MANUAL.md`.\n- This enforces \"do not stop early\"; it does not prove the work is correct. Pair it with tests, audits, and review.\n- The agent can still write a false `DONE` ticket. That changes a passive silent drift into an explicit, logged claim.\n\n## Verify\n\nRun the unit tests:\n\n```bash\npython tests/test_antistall.py\n```\n\nBehavioral test inside Codex Desktop:\n\n1. Use `AntistallON: gate test`.\n2. Ask Codex to stop with work remaining.\n3. The Stop hook should continue the session with an AntiStallCodex message.\n4. Use `AntistallOFF` after the test.\n\n## Removal\n\nDelete `~/.codex/skills/antistall-codex/`, remove the marked AntiStallCodex block from `~/.codex/config.toml`, and optionally delete `~/.codex/antistall-codex/`.\n\n## License\n\nMIT - see `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottconverse%2Fantistallcodex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscottconverse%2Fantistallcodex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottconverse%2Fantistallcodex/lists"}