{"id":51767159,"url":"https://github.com/scf4/codex-midi","last_synced_at":"2026-07-22T22:01:12.450Z","repository":{"id":371793791,"uuid":"1303308085","full_name":"scf4/codex-midi","owner":"scf4","description":"Emulate Codex Micro with arbitrary input devices","archived":false,"fork":false,"pushed_at":"2026-07-18T21:32:27.000Z","size":126,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-19T19:32:59.291Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/scf4.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-07-16T22:28:08.000Z","updated_at":"2026-07-19T09:43:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/scf4/codex-midi","commit_stats":null,"previous_names":["scf4/codex-midi"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/scf4/codex-midi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scf4%2Fcodex-midi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scf4%2Fcodex-midi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scf4%2Fcodex-midi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scf4%2Fcodex-midi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scf4","download_url":"https://codeload.github.com/scf4/codex-midi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scf4%2Fcodex-midi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35664169,"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-19T02:00:06.923Z","response_time":112,"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-19T19:33:02.085Z","updated_at":"2026-07-20T20:01:01.501Z","avatar_url":"https://github.com/scf4.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eCodex MIDI\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eControl Codex on macOS with almost any input device.\u003c/strong\u003e\u003cbr\u003e\n\n  Don't have a Codex Micro? No problem. Codex MIDI emulates a Codex Micro and implements its full set of features — and a few more.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#requirements\"\u003e\u003cimg alt=\"macOS only\" src=\"https://img.shields.io/badge/macOS-only-111111?logo=apple\u0026amp;logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"#requirements\"\u003e\u003cimg alt=\"Bun 1.3.14 or newer\" src=\"https://img.shields.io/badge/Bun-1.3.14%2B-fbf0df?logo=bun\u0026amp;logoColor=111111\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"MIT license\" src=\"https://img.shields.io/badge/license-MIT-2563eb\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick start\u003c/a\u003e ·\n  \u003ca href=\"#compatibility\"\u003eCompatibility\u003c/a\u003e ·\n  \u003ca href=\"#how-it-works\"\u003eHow it works\u003c/a\u003e ·\n  \u003ca href=\"docs/architecture.md\"\u003eArchitecture\u003c/a\u003e\n\u003c/p\u003e\n\n`codex-midi` is a [Codex Micro](https://worklouder.cc/codex-micro) emulator and bridge for Codex, allowing you to control ChatGPT Codex with almost any device as if it were a Codex Micro — from MIDI controllers and Stream Decks to game controllers, custom hardware, and more.\n\nThe PreSonus ATOM MIDI controller is the first implemented device and current reference implementation. It mirrors the Codex Micro's layout, functionality, and RGB feedback, while its extra controls provide additional shortcuts. Adding another input device is designed to be simple with the included `add-controller` skill for Codex.\n\n## Quick start\n\nConnect or pair your device and paste the following into a fresh Codex session/project, along with the type/model of hardware:\n\n\u003e Follow the instructions at https://github.com/scf4/codex-midi/blob/main/docs/setup-with-codex.md and set up \\\u003cmy-device-model\\\u003e\n\n---\n\nThe [setup instructions for Codex](docs/setup-with-codex.md) tell it to clone\nthis repository, find and confirm your device, propose a sensible layout, and\nhandle the implementation and verification. You can accept its recommendation,\nadjust a few controls, or define a completely custom mapping.\n\nFor the complete workflow and contribution requirements, see\n[Adding a controller](docs/adding-a-controller.md).\n\n### Requirements\n\n- macOS with the ChatGPT desktop app installed\n- A suitable input device\n- [Bun](https://bun.sh/) 1.3.14 or newer\n\n## Manual setup\n\nClone the project, install its locked dependencies, and launch ChatGPT through\nthe bridge:\n\n```sh\ngit clone https://github.com/scf4/codex-midi.git\ncd codex-midi\nbun install\nbun run launch\n```\n\nThe launcher does not modify ChatGPT, install a background service, or create a login item.\n\n## Compatibility\n\n| Area | Current state |\n| --- | --- |\n| **PreSonus ATOM** | Bundled reference adapter with verified Codex Micro controls and RGB feedback. Its additional controls can show or hide sidebars, toggle Plan mode, expand/restore panels, navigate between tasks more easily, and scroll through chats using the additional rotary encoders and side controls. |\n| **Other controllers** | Use the `add-controller` skill to create an adapter for whatever device you can find. |\n\n\n### PreSonus ATOM\n\nThe provided [ATOM](docs/controllers/atom.md) adapter maps its 16 pads, three encoders, and selected side\ncontrols to the Codex Micro surface along with additional controller actions.\n\n| ATOM surface | Codex behavior |\n| --- | --- |\n| Six task pads | Select task slots and display idle, thinking, complete, needs-input, and error states. |\n| Pads 2 and 3 | Operate the double-width microphone control. |\n| Pads 4–8 | Submit, Fast, Approve, Reject, and Fork, each with a distinct color. |\n| Encoder 1 | Controls reasoning or moves through highlighted options, depending on Codex Micro settings. |\n| Encoders 2 and 4 | Move between tasks and scroll the visible task. |\n| Direction controls | Emit the Micro's digital up, down, left, and right actions. |\n| Selected side controls | Toggle panels and Plan mode, run the default environment action, and open Codex Micro settings. |\n\nPads 1, 13, and 16 have no Codex Micro counterpart and remain dark. See the\n[ATOM reference](docs/controllers/atom.md) for the complete physical layout,\nMIDI messages, encoder behavior, lighting rules, and verification status.\n\n## Configuration\n\nThe guided setup creates `codex-midi.json` automatically. To select an\nadapter manually, create it in the project root:\n\n```json\n{\n  \"controller\": {\n    \"type\": \"atom\"\n  }\n}\n```\n\nIf a MIDI device uses different port names, run `bun run midi:list` and add only\nthe needed overrides: `inputName`, plus `outputName` when it has a separate\noutput port. Although the file keeps a `.json` extension, comments and trailing\ncommas are accepted. Non-MIDI adapters normally need only their `type`.\n\n## How it works\n\n```mermaid\nflowchart LR\n    A[\"Supported controller\"] \u003c--\u003e B[\"Controller surface\"]\n    B --\u003e|\"Micro inputs\"| C[\"Project2077 engine\"]\n    C \u003c--\u003e D[\"Private Unix socket\u003cbr/\u003escoped preload\"]\n    D \u003c--\u003e E[\"ChatGPT\u003cbr/\u003eCodex Micro integration\"]\n    B --\u003e|\"Allowlisted controller actions\"| D\n    C --\u003e|\"Optional feedback\"| B\n```\n\nThe project has three replaceable boundaries:\n\n1. The **controller surface** turns hardware input into normalized Micro events\n   and, where useful, allowlisted controller actions. MIDI is one implementation.\n2. The **Project2077 engine** implements the Codex Micro HID/RPC report model.\n3. The **ChatGPT host transport** exposes the synthetic device and forwards\n   controller actions to the launched ChatGPT process over a private socket.\n\nSee [Architecture](docs/architecture.md) for protocol and lifecycle details.\n\n## Development\n\nRun the complete automated gate with:\n\n```sh\nbun run verify\n```\n\nThis type-checks the project and runs the Bun test suite. The preload\ncompatibility test launches a Node subprocess, so contributors also need\n`node` on `PATH`. Normal bridge use requires only Bun.\n\nAutomation does not establish hardware support. A controller is supported only\nafter its documented physical-device pass succeeds; until then, its adapter is\n**implemented but unverified**.\n\n## Security and privacy\n\n- The bridge adds no network listener; reports stay on a private Unix socket.\n- Manual launch uses a fresh per-launch token scoped to the launched ChatGPT\n  process.\n- The preload intercepts only the Work Louder device kit's matching `node-hid`\n  request and delegates unrelated HID calls unchanged.\n- Controller actions use a fixed allowlist; adapters cannot request arbitrary\n  code or keyboard input.\n- A physical Codex Micro takes precedence over the synthetic descriptor.\n- Firmware, proprietary SDKs, application bundles, credentials, and task\n  content do not belong in this repository.\n\nThis is a compatibility shim around a private app integration, not a security\nboundary guaranteed by OpenAI or Electron. Review the source before running it.\n\n## Legal\n\n`codex-midi` is an independent project and is not affiliated with or endorsed\nby OpenAI, Work Louder, PreSonus, or other hardware manufacturers. Product\nnames and trademarks belong to their respective owners.\n\n## License\n\n[MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscf4%2Fcodex-midi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscf4%2Fcodex-midi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscf4%2Fcodex-midi/lists"}