{"id":50217954,"url":"https://github.com/joeyteng/codex-background-task-handler","last_synced_at":"2026-05-26T10:02:30.226Z","repository":{"id":353582675,"uuid":"1217822314","full_name":"JoeyTeng/codex-background-task-handler","owner":"JoeyTeng","description":"Companion Rust CLI for supervised background work around Codex, with managed sessions, task supervision, and safe result delivery.","archived":false,"fork":false,"pushed_at":"2026-05-24T11:35:22.000Z","size":1888,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-24T13:21:07.564Z","etag":null,"topics":["automation","background-tasks","cli","codex","developer-tools","rust","task-supervision"],"latest_commit_sha":null,"homepage":"https://github.com/JoeyTeng/codex-background-task-handler#readme","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JoeyTeng.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["JoeyTeng"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2026-04-22T08:52:26.000Z","updated_at":"2026-05-24T11:35:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JoeyTeng/codex-background-task-handler","commit_stats":null,"previous_names":["joeyteng/codex-background-task-handler"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/JoeyTeng/codex-background-task-handler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoeyTeng%2Fcodex-background-task-handler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoeyTeng%2Fcodex-background-task-handler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoeyTeng%2Fcodex-background-task-handler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoeyTeng%2Fcodex-background-task-handler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JoeyTeng","download_url":"https://codeload.github.com/JoeyTeng/codex-background-task-handler/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoeyTeng%2Fcodex-background-task-handler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33514912,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["automation","background-tasks","cli","codex","developer-tools","rust","task-supervision"],"created_at":"2026-05-26T10:02:19.714Z","updated_at":"2026-05-26T10:02:30.211Z","avatar_url":"https://github.com/JoeyTeng.png","language":"Rust","funding_links":["https://github.com/sponsors/JoeyTeng"],"categories":[],"sub_categories":[],"readme":"# codex-background-task-handler\n\nLanguages: [English (en-GB)](README.md) | [简体中文 (zh-CN)](README.zh-CN.md)\n\n`codex-background-task-handler` provides the `cbth` companion CLI for supervised background work around Codex without modifying the upstream `codex` repository. It is a local, same-user helper for launching managed Codex CLI sessions, supervising long-running shell tasks, and delivering task results back to the bound Codex thread when the local safety checks allow it.\n\n## Status\n\nThe project is currently suitable for local dogfooding on dedicated macOS or Linux single-user workstations.\n\n- CLI dogfood v1 is the main supported path. It can launch managed `codex` foreground sessions, supervise local tasks, keep durable daemon state, and attempt automatic delivery with explicit `trusted-all` opt-in.\n- Desktop bridge work is still a foundation and validation surface. It is not an enabled automatic Desktop delivery path yet.\n- The implementation is intentionally outside the upstream `codex` repository. This repo contains the companion Rust binary, integration experiments, and documentation for the external control surfaces.\n\n## Install\n\nRelease assets are currently available for Linux x86_64 glibc and macOS arm64. Intel macOS release assets are not published; Apple Silicon hosts launched from a Rosetta shell are mapped to the macOS arm64 asset by the installer.\n\nInstall the latest GitHub Release:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/JoeyTeng/codex-background-task-handler/HEAD/scripts/install.sh | sh\ncommand -v cbth\ncbth doctor cli\n```\n\nInstall a specific release or directory:\n\n```bash\nCBTH_VERSION=v0.2.2 CBTH_INSTALL_DIR=\"$HOME/.local/bin\" \\\n  sh scripts/install.sh\n```\n\nUpgrade an installed binary:\n\n```bash\ncbth self update --check\ncbth self update -i\ncbth self update --yes\n```\n\nFor local development from a checkout:\n\n```bash\ncargo install --path .\ncbth doctor cli\n```\n\n## Quick Start\n\nStart a managed fresh Codex thread:\n\n```bash\ncbth new \\\n  --session-allows-approval false \\\n  --session-allows-network false \\\n  --session-allows-write-access false \\\n  --auto-delivery-policy trusted-all \\\n  --model gpt-5.5\n```\n\nCopy the thread id from:\n\n```text\ncbth: bound thread id: \u003cthread-id\u003e\n```\n\nManaged foreground startup requires an interactive terminal. With Codex CLI\n0.132 or newer, run `cbth new` from a supported terminal with `TERM` set to a\nreal terminal type such as `xterm-256color`; `TERM=dumb` and non-TTY shells fail\nbefore cbth starts the managed app-server.\n\nCodex app-server configuration overrides are applied to both foreground Codex\nand the managed `codex app-server`: `--config` / `-c`, `--enable`,\n`--disable`, and `--strict-config` stay consistent across the remote session.\n\nFrom another shell, run a supervised task for that thread:\n\n```bash\ncbth task run \\\n  --source-thread-id \u003cthread-id\u003e \\\n  --summary \"run a slow local check\" \\\n  --delivery-read-only true \\\n  --delivery-requires-approval false \\\n  --delivery-requires-network false \\\n  --delivery-requires-write-access false \\\n  --cwd \"$PWD\" \\\n  --timeout-seconds 3600 \\\n  -- cargo test\n```\n\nInspect task and delivery state:\n\n```bash\ncbth task list --source-thread-id \u003cthread-id\u003e\ncbth batch inspect-head --source-thread-id \u003cthread-id\u003e\ncbth audit list --source-thread-id \u003cthread-id\u003e --limit 50\n```\n\n## Documentation\n\n- [Usage guide](docs/USAGE.en-GB.md): installation, managed sessions, task supervision, daemon state, and operator commands.\n- [Design overview](docs/DESIGN_OVERVIEW.en-GB.md): the high-level design, trust boundaries, and evolution path.\n- [Operator recovery](docs/OPERATOR_RECOVERY.en-GB.md): manual recovery for `manual_resolution_only`, task logs, sessions, and maintenance.\n- [Development guide](docs/DEVELOPMENT.en-GB.md): local development install, deterministic tests, hooks, and repo conventions.\n- [Live E2E guide](docs/LIVE_E2E.en-GB.md): opt-in checks that use a real Codex login, network, and model access.\n- [Codex Review Gate](https://github.com/JoeyTeng/codex-review-gate): reusable GitHub status check for Codex review completion.\n- [Documentation index](docs/README.md): user-facing docs, internal design notes, plans, validation records, and project tracking entrypoints.\n\n## License\n\nThis project is licensed under the Apache License 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoeyteng%2Fcodex-background-task-handler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoeyteng%2Fcodex-background-task-handler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoeyteng%2Fcodex-background-task-handler/lists"}