codex-micro-light

KO | EN

gitlite — search

#python #typescript #react #javascript #config #github-config #nextjs #nodejs #api #rust #linux #docker

codex-micro-light

★ 14 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Codex Micro Light

[![test](https://github.com/pejmanjohn/codex-micro-light/actions/workflows/test.yml/badge.svg)](https://github.com/pejmanjohn/codex-micro-light/actions/workflows/test.yml)

Control the Agent-key LEDs and outer ambient ring on a Work Louder Codex Micro from Codex tasks and automations.

This repository distributes the `$setmicrolight` skill as a minimal Codex plugin. By default, the skill resolves the task that invoked it, finds that task's physical Agent key, and changes only that LED. It can also target the device-global outer ambient ring with `--zone ambient`.

> [!IMPORTANT]
> This is an unofficial, experimental integration. It uses a private Codex Micro HID command that could change after a ChatGPT, Work Louder Input, or firmware update.

## Requirements

- macOS
- A Work Louder Codex Micro connected to the same Mac running Codex
- The ChatGPT desktop app with Codex Micro showing **Connected**
- The Codex CLI available on `PATH` for marketplace installation
- [Work Louder Input](https://worklouder.cc/openai-micro-setup) installed (recommended)
- Node.js for repaint-resistant background holds

The plugin has no npm dependencies and makes no network requests. It uses the HID driver already bundled with Work Louder Input or ChatGPT.

## Install

### Recommended: install as a plugin

Add this repository as a Codex plugin marketplace:

```bash
codex plugin marketplace add pejmanjohn/codex-micro-light
codex plugin add codex-micro-light@codex-micro-light
```

Then restart the ChatGPT desktop app, start a new Codex task, and type `$setmicrolight green`.

You can also install through the desktop interface:

1. Restart the ChatGPT desktop app.
2. Open **Plugins** in Codex.
3. Select the **Codex Micro Light** marketplace.
4. Install **Codex Micro Light**.

Check that Codex registered the marketplace with:

```bash
codex plugin marketplace list
```

### Alternative: install only the skill

Ask Codex:

```text
$skill-installer Install the setmicrolight skill from pejmanjohn/codex-micro-light
at plugins/codex-micro-light/skills/setmicrolight.
```

Or clone the repository and copy the skill manually:

```bash
git clone https://github.com/pejmanjohn/codex-micro-light.git codex-micro-light
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ditto codex-micro-light/plugins/codex-micro-light/skills/setmicrolight \
  "${CODEX_HOME:-$HOME/.codex}/skills/setmicrolight"
```

Restart Codex if the skill does not appear immediately.

### Update or remove

Refresh the Git-backed marketplace with:

```bash
codex plugin marketplace upgrade codex-micro-light
```

Then update or reinstall **Codex Micro Light** from the Plugins screen and start a new task. To stop using it, uninstall or disable the plugin there. Remove the marketplace only if you no longer use anything from it:

```bash
codex plugin marketplace remove codex-micro-light
```

To pin a known release instead of following `main`, add the marketplace with a Git tag:

```bash
codex plugin marketplace add pejmanjohn/codex-micro-light --ref v0.1.1
```

## Use

Invoke the skill explicitly:

```text
$setmicrolight green
$setmicrolight Flash this task purple for 20 seconds.
$setmicrolight Cycle this task's light through a rainbow.
$setmicrolight Clear this task's custom light.
$setmicrolight Run a green snake around the outer ambient ring.
```

Supported named colors are `green`, `blue`, `red`, `orange`, `yellow`, `purple`, `pink`, `cyan`, and `white`. You can also use any six-digit RGB value such as `#A855F7`.

Agent-key effects are `solid`, `breath`, `shallow-breath`, and `rainbow`. The spatial `snake` and `gradient` effects require the multi-LED ambient ring and are rejected for an individual Agent key instead of silently rendering it dark.

The default notification is a green breathing light with a 30-second hold. The hold repeatedly reasserts the chosen state so Codex's normal task-status repaint does not immediately replace it. After the hold ends, the helper stops and the next normal Codex update regains control.

### Control the ambient ring

Ask Codex to target the outer ring instead of the current task key:

```text
$setmicrolight Run a green snake around the outer ring for 30 seconds.
$setmicrolight Set the outer ring to a purple gradient without a hold.
$setmicrolight Stop the active outer-ring hold and turn the ring off.
```

Ambient effects are `solid`, `snake`, `rainbow`, `breath`, `gradient`, and `shallow-breath`. The ring is device-global, so it does not use a task assignment and cannot be combined with `--slot`, `--thread-id`, or `resolve`.

## Use with automations

For a durable automation, give its task a stable physical key:

1. Open **Codex Settings → Codex Micro**.
2. Set **Agent keys** to **Custom assignments**.
3. Assign the automation's task to one Agent key.
4. Ask `$setmicrolight` to verify the assignment without changing the device. Confirm that the result reports `source: "custom"` and the expected slot from 1 through 6.

Then add a deterministic instruction to the automation:

```text
Check the requested criteria. If it is true, use $setmicrolight to make this
task's Codex Micro Agent key breathe green. If it is false or the check fails,
leave the light unchanged.
```

The automation must execute locally on the Mac connected to the Codex Micro. A cloud task cannot reach local HID hardware.

## Targeting behavior

- **Custom assignments:** required for reliable recurring automations.
- **Most recent chats:** supported for interactive use. The helper rechecks the mapping during a hold and relinquishes the light if the task moves.
- **Pinned chats and Priority chats:** fail closed because their physical order cannot be reconstructed safely.
- **Explicit slot:** available only when the user intentionally identifies physical Agent key 1 through 6.

The skill never guesses when it cannot resolve the invoking task safely.

## Safety and privacy

- Changes one Agent-key LED at a time by default. Ambient commands use the firmware's complete lighting configuration, with the general-key side off and the outer-ring side selected; Agent-key statuses remain independent.
- Does not modify firmware or keyboard layers.
- Does not install a daemon or LaunchAgent.
- Does not send task, email, notification, or credential data to the device—only color and animation settings.
- Serializes participating helper processes with macOS `lockf` so their multi-report HID messages cannot interleave.
- Does not redistribute Work Louder or OpenAI binaries; it loads a compatible HID binding from an app already installed on the user's Mac.

The ChatGPT app does not participate in the helper lock and can still repaint the LEDs. The temporary hold mitigates that behavior but cannot turn this private protocol into a supported public API.

## Troubleshooting

### The task is not assigned

Open **Codex Settings → Codex Micro**, choose **Custom assignments**, and place the current task on one of the six Agent keys. Do not force a numbered slot unless you have physically identified it.

### Nothing lights up

1. Confirm Codex Micro shows **Connected** in Codex settings.
2. Confirm the device is on Layer 1 and its USB or Bluetooth connection is active.
3. Install or update Work Louder Input.
4. Confirm ChatGPT has macOS Input Monitoring permission.
5. Try `$setmicrolight Verify this task's Agent-key assignment without changing the device.`

### The settings preview does not change

That is expected. Direct HID writes appear on the physical device; the Codex Micro settings preview shows Codex's logical task state rather than hardware readback.

## Develop

The skill source of truth is:

```text
plugins/codex-micro-light/skills/setmicrolight/
```

Run the hardware-free test suite:

```bash
node --test test/*.test.cjs
```

Check the executable and JavaScript entry points:

```bash
zsh -n plugins/codex-micro-light/skills/setmicrolight/scripts/set-micro-light
node --check plugins/codex-micro-light/skills/setmicrolight/scripts/set-micro-light.cjs
```

Real-device tests are intentionally manual. They should use an explicit test color and a short hold, and they should never run in CI.

## License

[MIT](LICENSE)

Codex, Codex Micro, ChatGPT, Work Louder, and related marks belong to their respective owners. This project is not affiliated with or endorsed by OpenAI or Work Louder.

codex-micro-light

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README