Metadata-Version: 2.4
Name: codex-listener
Version: 0.1.1
Summary: A daemon that lets AI agents orchestrate OpenAI Codex CLI tasks
Project-URL: Homepage, https://github.com/TalexCK/Codex-Listener
Project-URL: Repository, https://github.com/TalexCK/Codex-Listener
Project-URL: Issues, https://github.com/TalexCK/Codex-Listener/issues
Author-email: Alex Tang <talexcks@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Alex Tang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,ai,cli,codex,daemon
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.115
Requires-Dist: pydantic>=2.0
Requires-Dist: uvicorn[standard]>=0.30
Description-Content-Type: text/markdown

# Codex-Listener

A daemon that lets AI agents (Claude, ChatGPT, etc.) orchestrate [OpenAI Codex CLI](https://github.com/openai/codex) tasks. Submit coding tasks, track progress, and collect results — all through simple shell commands that any AI can call.

## Architecture

```
AI Agent  ──  scripts/*.py (submit)  ──▶  codex-listener daemon (FastAPI)
User     ◀── Feishu Bot card                              │
                                                          │ subprocess
                                                          ▼
                                                  codex exec --json --full-auto
```

AI agents run standalone Python scripts via their shell tool. Each script talks to the daemon over HTTP on localhost and prints structured JSON to stdout. No curl or HTTP knowledge needed in prompts.

## Installation

```bash
# From source
uv pip install -e .

# From PyPI
uv tool install codex-listener

# Verify
codex-listener --version
```

Requires Python 3.10+ and [OpenAI Codex CLI](https://github.com/openai/codex) on PATH.

## Quick Start

```bash
# Start the daemon
uv run codex-listener start

# Submit a task (fire-and-forget — daemon notifies user via Feishu on completion)
python3 skills/Codex-Listener/scripts/submit.py --prompt "fix the bug in auth.py" --cwd /path/to/project

# Stop the daemon
uv run codex-listener stop
```

## Daemon Management

```bash
uv run codex-listener start [--port 19823] [--host 127.0.0.1]   # Start daemon
uv run codex-listener stop                                        # Stop daemon
uv run codex-listener status                                      # Check if running
uv run codex-listener logs [-f] [-n 50]                           # View logs
```

## AI Skill Scripts

Standalone Python scripts in `skills/Codex-Listener/scripts/` for AI agents to submit tasks to the daemon. All output a single JSON object to stdout. Exit code 0 = success, 1 = error. The daemon notifies the user via Feishu Bot on completion.

```bash
python3 skills/Codex-Listener/scripts/submit.py --prompt "..." [--model gpt-5.3-codex] [--cwd .] [--sandbox workspace-write]
python3 skills/Codex-Listener/scripts/status.py --task-id <id>
python3 skills/Codex-Listener/scripts/list_tasks.py [--status running]
python3 skills/Codex-Listener/scripts/cancel.py --task-id <id>
python3 skills/Codex-Listener/scripts/health.py
```

## Configuration

Config file: `~/.codex-listener/config.json` (auto-created on first run).

```json
{
  "feishu": {
    "enabled": true,
    "appId": "cli_xxxx",
    "appSecret": "xxxxx",
    "encryptKey": "",
    "verificationToken": "",
    "allowFrom": ["ou_xxxx"]
  },
  "telegram": {
    "enabled": false,
    "token": "",
    "allowFrom": [],
    "proxy": null
  }
}
```

**`feishu`** — Feishu Bot notification settings. When a task completes or fails, the daemon parses the Codex session JSONL (extracting the last assistant message, token usage, and completion time) and sends an interactive card to the configured recipients.

| Field | Description |
|-------|-------------|
| `enabled` | Set to `true` to enable Feishu notifications |
| `appId` | Feishu app ID (from [Feishu Open Platform](https://open.feishu.cn)) |
| `appSecret` | Feishu app secret |
| `encryptKey` | Event encryption key (optional, for webhook verification) |
| `verificationToken` | Event verification token (optional) |
| `allowFrom` | List of Feishu `open_id`s to receive notifications |

**`telegram`** — Telegram Bot notification settings. Similar to Feishu, sends formatted messages when tasks complete or fail.

| Field | Description                                                                   |
|-------|-------------------------------------------------------------------------------|
| `enabled` | Set to `true` to enable Telegram notifications                                |
| `token` | Telegram Bot token (from [@BotFather](https://t.me/botfather))                |
| `allowFrom` | List of Telegram chat IDs to receive notifications (Get from NanoBot console) |
| `proxy` | Optional HTTP/HTTPS proxy URL (e.g., `"http://proxy.example.com:8080"`)       |

## AI Integration

Copy the skill file for your AI tool:

- **Claude Code**: Copy `skills/Codex-Listener/SKILL.md` to your project's `.claude/skills/` directory.

The skill file teaches the AI how to use the Python scripts in `skills/Codex-Listener/scripts/`.

## Testing

See [TEST.md](TEST.md) for manual test procedures covering daemon operations and AI skill commands.

## Project Structure

```
src/codex_listener/
├── __init__.py          # Package version
├── cli.py               # CLI entry point (start/stop/status/logs)
├── daemon.py            # Daemon lifecycle (PID file, background process)
├── server.py            # FastAPI HTTP server
├── task_manager.py      # Codex subprocess lifecycle & state management
├── models.py            # Pydantic models (TaskCreate, TaskStatus, etc.)
├── config.py            # Configuration loading (~/.codex-listener/config.json)
├── session_parser.py    # Parse Codex session JSONL for results & token usage
└── channels/            # External bot notification channels
    ├── __init__.py      # Channel exports
    ├── feishu.py        # Feishu Bot API (send card notifications)
    └── telegram.py      # Telegram Bot API (send text notifications)

skills/Codex-Listener/
├── SKILL.md             # AI skill definition
└── scripts/
    ├── codex_client.py  # Shared HTTP client (stdlib only)
    ├── submit.py        # Submit a task (fire-and-forget)
    ├── status.py        # Check task status (optional)
    ├── list_tasks.py    # List tasks (optional)
    ├── cancel.py        # Cancel a task
    └── health.py        # Daemon health check
```
