codex_list
List recent codex jobs with their status and prompt summaries to monitor progress or review completed tasks. Specify an optional limit to control the number of results returned.
Instructions
List recent codex jobs with their status and prompt summaries.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max number of jobs to return (most recent first). Default: 20. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/codex_async_mcp/server.py:39-47 (handler)The MCP tool handler function that implements codex_list. It calls list_jobs(limit) from job_manager and returns the result.
@mcp.tool() def codex_list(limit: int = 20) -> list: """ List recent codex jobs with their status and prompt summaries. Args: limit: Max number of jobs to return (most recent first). Default: 20. """ return list_jobs(limit) - src/codex_async_mcp/server.py:39-39 (registration)The @mcp.tool() decorator registers codex_list as an MCP tool named 'codex_list' on the FastMCP server instance.
@mcp.tool() - The helper function list_jobs that performs the actual work: reads job directories from JOBS_DIR, opens their meta.json files, and returns a list of job summaries (up to 'limit' entries), sorted by modification time (most recent first).
def list_jobs(limit: int = 20) -> list[dict]: if not JOBS_DIR.exists(): return [] results = [] for job_dir in sorted(JOBS_DIR.iterdir(), key=lambda p: p.stat().st_mtime, reverse=True): meta_path = job_dir / "meta.json" if not meta_path.exists(): continue with open(meta_path) as f: meta = json.load(f) results.append({ "job_id": meta["job_id"], "status": meta["status"], "prompt": meta["prompt"][:80] + ("..." if len(meta["prompt"]) > 80 else ""), "cwd": meta["cwd"], "started_at": meta["started_at"], "finished_at": meta.get("finished_at"), }) if len(results) >= limit: break return results - src/codex_async_mcp/config.py:3-7 (schema)The config constant JOBS_DIR defines where job metadata is stored; this is the path used by list_jobs to discover job directories.
JOBS_DIR = Path.home() / ".codex-async" / "jobs" DEFAULT_APPROVAL_POLICY = "suggest" CODEX_BIN = "codex" JOB_TAIL_LINES = 100 MAX_OUTPUT_CHARS = 8000