codex-alfred

Slack "butler" that bridges Slack threads to Codex CLI via the Codex TypeScript SDK.

Easy install (create your own Slack app)

Each user creates their own Slack app and gets their own tokens. Use the manifest link below to open Slack's app creation flow:

End-to-end setup

1. Click the button above, create the app in your workspace, then install it. Copy:
   • App-level token (xapp-...)
   • Bot token (xoxb-...)
2. Install prerequisites:
   • Docker
   • Node.js LTS (pinned via mise)
     • mise install
3. Run Alfred locally:

npx @tiberriver256/codex-alfred --appKey <app-key> --botKey <bot-key> --data-dir ./data

4. In Slack, mention @Alfred in a channel or DM to get started.

See spec.md for the product/technical spec.

Local restart (dev)

Use the npm script to restart Alfred with the same command we’ve been using. It prints the new PID.

ALFRED_PID=<old-pid> npm run alfred:restart

Notes:

• Uses ALFRED_DATA_DIR if set; otherwise defaults to ~/mom-data.
• Writes logs to $ALFRED_DATA_DIR/alfred.log.
• If you don’t pass ALFRED_PID, it just starts a new process.

Configuration

You can supply tokens via CLI flags or environment variables:

• --appKey or SLACK_APP_TOKEN
• --botKey or SLACK_BOT_TOKEN
• --data-dir or ALFRED_DATA_DIR
• --workdir or ALFRED_WORKDIR
• --sandbox or ALFRED_SANDBOX (host or docker:<name>)
• --log-level or ALFRED_LOG_LEVEL

Pass additional Codex CLI args after --:

codex-alfred --appKey ... --botKey ... -- --yolo

Testing

node --test --import=tsx

Docker sandbox

Use the helper script to create and manage the sandbox container:

./docker.sh create ./data
./docker.sh start

When running with --sandbox docker:<name>, Alfred adds --yolo to Codex args by default (unless you pass it explicitly).

To restart Alfred using the Docker sandbox in one step:

./alfred-docker.sh

Notes:

• Builds the repo and syncs dist/, schemas/, and conversations-in-blockkit.md into the data dir.
• Runs Alfred inside the Docker container and writes logs to /workspace/alfred.log.
• Installs production deps inside the container if /workspace/node_modules is missing.
• Kills any host codex-alfred processes by default (set ALFRED_STOP_HOST=0 to skip).
• Copies your Codex auth file to /workspace/.codex/auth.json and sets CODEX_HOME in the container.