codexapi 0.3.4__tar.gz → 0.5.0__tar.gz

{codexapi-0.3.4/src/codexapi.egg-info → codexapi-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.3.4
+Version: 0.5.0
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -9,6 +9,8 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.64
 
 # CodexAPI
 
@@ -70,6 +72,7 @@ echo "Say hello." | codexapi run
 
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
+codexapi task -f task.yaml
 ```
 
 Show running sessions and their latest activity:
@@ -85,6 +88,8 @@ Resume a session and print the thread id to stderr:
 codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off."
 ```
 
+Use `--no-yolo` to run Codex with `--full-auto` instead.
+
 Ralph loop mode repeats the same prompt until a completion promise or a max
 iteration cap is hit (0 means unlimited). Cancel by deleting
 `.codexapi/ralph-loop.local.md` or running `codexapi ralph --cancel`.
@@ -95,29 +100,36 @@ codexapi ralph --ralph-fresh "Try again from scratch." --max-iterations 3
 codexapi ralph --cancel --cwd /path/to/project
 ```
 
+Run a task file across a list file:
+
+```bash
+codexapi foreach list.txt task.yaml
+codexapi foreach list.txt task.yaml -n 4
+```
+
 ## API
 
-### `agent(prompt, cwd=None, yolo=False, flags=None) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None) -> str`
 
 Runs a single Codex turn and returns only the agent's message. Any reasoning
 items are filtered out.
 
 - `prompt` (str): prompt to send to Codex.
 - `cwd` (str | PathLike | None): working directory for the Codex session.
-- `yolo` (bool): pass `--yolo` to Codex when true.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `Agent(cwd=None, yolo=False, thread_id=None, flags=None)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
 
 - `__call__(prompt) -> str`: send a prompt to Codex and return the message.
 - `thread_id -> str | None`: expose the underlying session id once created.
-- `yolo` (bool): pass `--yolo` to Codex when true.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `task(prompt, check=None, n=10, cwd=None, yolo=False, flags=None) -> str`
+### `task(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> str`
 
 Runs a task with checker-driven retries and returns the success summary.
 Raises `TaskFailed` when the maximum attempts are reached.
@@ -125,12 +137,12 @@ Raises `TaskFailed` when the maximum attempts are reached.
 - `check` (str | None | False): custom check prompt, default checker, or `False` to skip.
 - `n` (int): maximum number of retries after a failed check.
 
-### `task_result(prompt, check=None, n=10, cwd=None, yolo=False, flags=None) -> TaskResult`
+### `task_result(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> TaskResult`
 
 Runs a task with checker-driven retries and returns a `TaskResult` without
 raising `TaskFailed`.
 
-### `Task(prompt, max_attempts=10, cwd=None, yolo=False, thread_id=None, flags=None)`
+### `Task(prompt, max_attempts=10, cwd=None, yolo=True, thread_id=None, flags=None)`
 
 Runs a Codex task with checker-driven retries. Subclass it and implement
 `check()` to return an error string when the task is incomplete, or return
@@ -139,7 +151,7 @@ Runs a Codex task with checker-driven retries. Subclass it and implement
 - `__call__() -> TaskResult`: run the task.
 - `set_up()`: optional setup hook.
 - `tear_down()`: optional cleanup hook.
-- `check() -> str | None`: return an error description or `None`/`""`.
+- `check(output=None) -> str | None`: return an error description or `None`/`""`. `output` is the last agent response.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
 
@@ -161,12 +173,31 @@ Exception raised by `task()` when retries are exhausted.
 - `attempts` (int | None): attempts made when the task failed.
 - `errors` (str | None): last checker error, if any.
 
+### `foreach(list_file, task_file, n=None, cwd=None, yolo=True, flags=None) -> ForeachResult`
+
+Runs a task file over a list of items, updating the list file in place.
+
+- `list_file` (str | PathLike): path to the list file to process.
+- `task_file` (str | PathLike): YAML task file (must include `prompt`).
+- `n` (int | None): limit parallelism to N (default: run all items in parallel).
+- `cwd` (str | PathLike | None): working directory for the Codex session.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
+- `flags` (str | None): extra CLI flags to pass to Codex.
+
+### `ForeachResult(succeeded, failed, skipped, results)`
+
+Simple result object returned by `foreach()`.
+
+- `succeeded` (int): number of successful items.
+- `failed` (int): number of failed items.
+- `skipped` (int): number of items skipped (already marked in the list file).
+- `results` (list[tuple]): `(item, success, summary)` entries for items that ran.
+
 ## Behavior notes
 
 - Uses `codex exec --json` and parses JSONL events for `agent_message` items.
 - Automatically passes `--skip-git-repo-check` so it can run outside a git repo.
-- Passes `--full-auto` unless `--yolo` is enabled.
-- Passes `--yolo` when enabled (use with care).
+- Passes `--yolo` by default (use `--no-yolo` or `yolo=False` for `--full-auto`).
 - Raises `RuntimeError` if Codex exits non-zero or returns no agent message.
 
 ## Configuration

{codexapi-0.3.4 → codexapi-0.5.0}/README.md

@@ -58,6 +58,7 @@ echo "Say hello." | codexapi run
 
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
+codexapi task -f task.yaml
 ```
 
 Show running sessions and their latest activity:
@@ -73,6 +74,8 @@ Resume a session and print the thread id to stderr:
 codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off."
 ```
 
+Use `--no-yolo` to run Codex with `--full-auto` instead.
+
 Ralph loop mode repeats the same prompt until a completion promise or a max
 iteration cap is hit (0 means unlimited). Cancel by deleting
 `.codexapi/ralph-loop.local.md` or running `codexapi ralph --cancel`.
@@ -83,29 +86,36 @@ codexapi ralph --ralph-fresh "Try again from scratch." --max-iterations 3
 codexapi ralph --cancel --cwd /path/to/project
 ```
 
+Run a task file across a list file:
+
+```bash
+codexapi foreach list.txt task.yaml
+codexapi foreach list.txt task.yaml -n 4
+```
+
 ## API
 
-### `agent(prompt, cwd=None, yolo=False, flags=None) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None) -> str`
 
 Runs a single Codex turn and returns only the agent's message. Any reasoning
 items are filtered out.
 
 - `prompt` (str): prompt to send to Codex.
 - `cwd` (str | PathLike | None): working directory for the Codex session.
-- `yolo` (bool): pass `--yolo` to Codex when true.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `Agent(cwd=None, yolo=False, thread_id=None, flags=None)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
 
 - `__call__(prompt) -> str`: send a prompt to Codex and return the message.
 - `thread_id -> str | None`: expose the underlying session id once created.
-- `yolo` (bool): pass `--yolo` to Codex when true.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `task(prompt, check=None, n=10, cwd=None, yolo=False, flags=None) -> str`
+### `task(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> str`
 
 Runs a task with checker-driven retries and returns the success summary.
 Raises `TaskFailed` when the maximum attempts are reached.
@@ -113,12 +123,12 @@ Raises `TaskFailed` when the maximum attempts are reached.
 - `check` (str | None | False): custom check prompt, default checker, or `False` to skip.
 - `n` (int): maximum number of retries after a failed check.
 
-### `task_result(prompt, check=None, n=10, cwd=None, yolo=False, flags=None) -> TaskResult`
+### `task_result(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> TaskResult`
 
 Runs a task with checker-driven retries and returns a `TaskResult` without
 raising `TaskFailed`.
 
-### `Task(prompt, max_attempts=10, cwd=None, yolo=False, thread_id=None, flags=None)`
+### `Task(prompt, max_attempts=10, cwd=None, yolo=True, thread_id=None, flags=None)`
 
 Runs a Codex task with checker-driven retries. Subclass it and implement
 `check()` to return an error string when the task is incomplete, or return
@@ -127,7 +137,7 @@ Runs a Codex task with checker-driven retries. Subclass it and implement
 - `__call__() -> TaskResult`: run the task.
 - `set_up()`: optional setup hook.
 - `tear_down()`: optional cleanup hook.
-- `check() -> str | None`: return an error description or `None`/`""`.
+- `check(output=None) -> str | None`: return an error description or `None`/`""`. `output` is the last agent response.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
 
@@ -149,12 +159,31 @@ Exception raised by `task()` when retries are exhausted.
 - `attempts` (int | None): attempts made when the task failed.
 - `errors` (str | None): last checker error, if any.
 
+### `foreach(list_file, task_file, n=None, cwd=None, yolo=True, flags=None) -> ForeachResult`
+
+Runs a task file over a list of items, updating the list file in place.
+
+- `list_file` (str | PathLike): path to the list file to process.
+- `task_file` (str | PathLike): YAML task file (must include `prompt`).
+- `n` (int | None): limit parallelism to N (default: run all items in parallel).
+- `cwd` (str | PathLike | None): working directory for the Codex session.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
+- `flags` (str | None): extra CLI flags to pass to Codex.
+
+### `ForeachResult(succeeded, failed, skipped, results)`
+
+Simple result object returned by `foreach()`.
+
+- `succeeded` (int): number of successful items.
+- `failed` (int): number of failed items.
+- `skipped` (int): number of items skipped (already marked in the list file).
+- `results` (list[tuple]): `(item, success, summary)` entries for items that ran.
+
 ## Behavior notes
 
 - Uses `codex exec --json` and parses JSONL events for `agent_message` items.
 - Automatically passes `--skip-git-repo-check` so it can run outside a git repo.
-- Passes `--full-auto` unless `--yolo` is enabled.
-- Passes `--yolo` when enabled (use with care).
+- Passes `--yolo` by default (use `--no-yolo` or `yolo=False` for `--full-auto`).
 - Raises `RuntimeError` if Codex exits non-zero or returns no agent message.
 
 ## Configuration

{codexapi-0.3.4 → codexapi-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.3.4"
+version = "0.5.0"
 description = "Minimal Python API for running the Codex CLI."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -15,7 +15,10 @@ classifiers = [
   "Operating System :: OS Independent",
 ]
 
-dependencies = []
+dependencies = [
+  "PyYAML>=6.0",
+  "tqdm>=4.64",
+]
 
 [project.scripts]
 codexapi = "codexapi.cli:main"

{codexapi-0.3.4 → codexapi-0.5.0}/src/codexapi/__init__.py

@@ -1,15 +1,18 @@
 """Minimal Python API for running the Codex CLI."""
 
 from .agent import Agent, agent
+from .foreach import ForeachResult, foreach
 from .task import Task, TaskFailed, TaskResult, task, task_result
 
 __all__ = [
     "Agent",
+    "ForeachResult",
     "Task",
     "TaskFailed",
     "TaskResult",
     "agent",
+    "foreach",
     "task",
     "task_result",
 ]
-__version__ = "0.3.4"
+__version__ = "0.5.0"

{codexapi-0.3.4 → codexapi-0.5.0}/src/codexapi/agent.py

@@ -8,7 +8,7 @@ import subprocess
 _CODEX_BIN = os.environ.get("CODEX_BIN", "codex")
 
 
-def agent(prompt, cwd=None, yolo=False, flags=None):
+def agent(prompt, cwd=None, yolo=True, flags=None):
     """Run a single Codex turn and return only the agent's message.
 
     Args:
@@ -36,7 +36,7 @@ class Agent:
     def __init__(
         self,
         cwd=None,
-        yolo=False,
+        yolo=True,
         thread_id=None,
         flags=None,
     ):

{codexapi-0.3.4 → codexapi-0.5.0}/src/codexapi/cli.py

@@ -12,8 +12,10 @@ from datetime import datetime
 from pathlib import Path
 
 from .agent import Agent, agent
+from .foreach import foreach
 from .ralph import cancel_ralph_loop, run_ralph_loop
 from .task import TaskFailed, task
+from .taskfile import AutoTask, load_task_file
 
 _SESSION_ID_RE = re.compile(
     r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
@@ -38,6 +40,7 @@ _COLUMN_TITLES = {
     "in": "IN",
     "out": "OUT",
     "turn": "TURN",
+    "turns": "NTRN",
     "model": "MODEL",
     "effort": "EFF",
     "perm": "PERM",
@@ -121,6 +124,27 @@ def _tail_lines(path):
     return text.splitlines()
 
 
+def _count_turns(path):
+    event_count = 0
+    response_count = 0
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            for line in handle:
+                if "\"type\":\"event_msg\"" in line and "\"type\":\"user_message\"" in line:
+                    event_count += 1
+                    continue
+                if "\"type\":\"response_item\"" in line and "\"role\":\"user\"" in line and "\"type\":\"message\"" in line:
+                    response_count += 1
+    except OSError:
+        return None
+
+    if event_count:
+        return event_count
+    if response_count:
+        return response_count
+    return None
+
+
 def _extract_text(content):
     if isinstance(content, str):
         return content
@@ -364,6 +388,7 @@ def _summarize_session(path, mtime):
     total_usage = None
     meta = {}
     subagent = None
+    turns = _count_turns(path)
 
     for line in _tail_lines(path):
         try:
@@ -485,6 +510,7 @@ def _summarize_session(path, mtime):
         "last_user_ts": last_user_ts,
         "last_agent_ts": last_agent_ts,
         "last_event_kind": last_event_kind,
+        "turns": turns,
         "meta": meta,
     }
 
@@ -604,6 +630,7 @@ def _layout_columns(width, id_width, show):
         ("in", ">"),
         ("out", ">"),
         ("turn", ">"),
+        ("turns", ">"),
     ]
     widths = {
         "id": id_width,
@@ -612,6 +639,7 @@ def _layout_columns(width, id_width, show):
         "in": 7,
         "out": 7,
         "turn": 7,
+        "turns": 5,
     }
     mins = {}
 
@@ -684,6 +712,8 @@ def _format_session(session, layout):
         else:
             turn_seconds = None
     turn_str = _format_duration(turn_seconds)
+    turns = session.get("turns")
+    turns_str = "-" if turns is None else str(turns)
     meta = session.get("meta") or {}
     model = meta.get("model") or meta.get("model_provider") or "-"
     effort = meta.get("effort") or "-"
@@ -702,6 +732,7 @@ def _format_session(session, layout):
         "in": total_in,
         "out": total_out,
         "turn": turn_str,
+        "turns": _truncate_head(str(turns_str), widths.get("turns", 0)),
         "model": _truncate_head(str(model), widths.get("model", 0)),
         "effort": _truncate_head(str(effort), widths.get("effort", 0)),
         "perm": _truncate_head(str(perm), widths.get("perm", 0)),
@@ -908,7 +939,12 @@ def main(argv=None):
         help="Prompt to send. Use '-' or omit to read from stdin.",
     )
     run_parser.add_argument("--cwd", help="Working directory for the Codex session.")
-    run_parser.add_argument("--yolo", action="store_true", help="Pass --yolo to Codex.")
+    run_parser.add_argument(
+        "--no-yolo",
+        action="store_false",
+        dest="yolo",
+        help="Disable --yolo and use --full-auto.",
+    )
     run_parser.add_argument(
         "--flags",
         help="Additional raw CLI flags to pass to Codex (quoted as needed).",
@@ -927,6 +963,11 @@ def main(argv=None):
         "task",
         help="Run a task with verification retries.",
     )
+    task_parser.add_argument(
+        "-f",
+        "--task-file",
+        help="YAML task file to run.",
+    )
     task_parser.add_argument(
         "prompt",
         nargs="?",
@@ -939,11 +980,16 @@ def main(argv=None):
     task_parser.add_argument(
         "--max-iterations",
         type=int,
-        default=10,
-        help="Max verification retries after a failed check (0 means no retries).",
+        default=None,
+        help="Max verification retries after a failed check (0 means no retries). Defaults to 10.",
     )
     task_parser.add_argument("--cwd", help="Working directory for the Codex session.")
-    task_parser.add_argument("--yolo", action="store_true", help="Pass --yolo to Codex.")
+    task_parser.add_argument(
+        "--no-yolo",
+        action="store_false",
+        dest="yolo",
+        help="Disable --yolo and use --full-auto.",
+    )
     task_parser.add_argument(
         "--flags",
         help="Additional raw CLI flags to pass to Codex (quoted as needed).",
@@ -986,12 +1032,46 @@ def main(argv=None):
         help="Start each iteration with a fresh Agent context.",
     )
     ralph_parser.add_argument("--cwd", help="Working directory for the Codex session.")
-    ralph_parser.add_argument("--yolo", action="store_true", help="Pass --yolo to Codex.")
+    ralph_parser.add_argument(
+        "--no-yolo",
+        action="store_false",
+        dest="yolo",
+        help="Disable --yolo and use --full-auto.",
+    )
     ralph_parser.add_argument(
         "--flags",
         help="Additional raw CLI flags to pass to Codex (quoted as needed).",
     )
 
+    foreach_parser = subparsers.add_parser(
+        "foreach",
+        help="Run a task file over a list file.",
+    )
+    foreach_parser.add_argument(
+        "list_file",
+        help="Path to the list file to process.",
+    )
+    foreach_parser.add_argument(
+        "task_file",
+        help="Path to the YAML task file.",
+    )
+    foreach_parser.add_argument(
+        "-n",
+        type=int,
+        help="Limit parallelism to N.",
+    )
+    foreach_parser.add_argument("--cwd", help="Working directory for the Codex session.")
+    foreach_parser.add_argument(
+        "--no-yolo",
+        action="store_false",
+        dest="yolo",
+        help="Disable --yolo and use --full-auto.",
+    )
+    foreach_parser.add_argument(
+        "--flags",
+        help="Additional raw CLI flags to pass to Codex (quoted as needed).",
+    )
+
     subparsers.add_parser(
         "top",
         help="Show running Codex sessions.",
@@ -1005,6 +1085,21 @@ def main(argv=None):
         _run_top([])
         return
 
+    if args.command == "foreach":
+        if args.n is not None and args.n < 1:
+            raise SystemExit("-n must be >= 1.")
+        result = foreach(
+            args.list_file,
+            args.task_file,
+            args.n,
+            args.cwd,
+            args.yolo,
+            args.flags,
+        )
+        if result.failed:
+            raise SystemExit(1)
+        return
+
     if args.command == "ralph":
         if args.cancel:
             if args.prompt:
@@ -1016,6 +1111,29 @@ def main(argv=None):
             print(cancel_ralph_loop(args.cwd))
             return
 
+    if args.command == "task" and args.task_file:
+        if args.prompt:
+            raise SystemExit("task -f does not take a prompt.")
+        if args.check is not None:
+            raise SystemExit("--check is not allowed with -f.")
+        if args.max_iterations is not None:
+            raise SystemExit("--max-iterations is not allowed with -f.")
+        task_def = load_task_file(args.task_file)
+        task_runner = AutoTask(
+            task_def,
+            None,
+            10,
+            args.cwd,
+            args.yolo,
+            None,
+            args.flags,
+        )
+        result = task_runner()
+        print(result.summary)
+        if not result.success:
+            raise SystemExit(1)
+        return
+
     prompt = _read_prompt(args.prompt)
     exit_code = 0
 
@@ -1033,6 +1151,8 @@ def main(argv=None):
         )
         return
     if args.command == "task":
+        if args.max_iterations is None:
+            args.max_iterations = 10
         if args.max_iterations < 0:
             raise SystemExit("--max-iterations must be >= 0.")
         check = args.check if args.check is not None else prompt

codexapi-0.5.0/src/codexapi/foreach.py

@@ -0,0 +1,230 @@
+"""Run a task file over a list of items with resumable progress."""
+
+import sys
+import threading
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from tqdm import tqdm
+
+from .taskfile import AutoTask, load_task_file
+
+_STATUS_RUNNING = "⏳"
+_STATUS_SUCCESS = "✅"
+_STATUS_FAILED = "❌"
+_STATUS_SET = {_STATUS_RUNNING, _STATUS_SUCCESS, _STATUS_FAILED}
+
+
+class ForeachResult:
+    """Outcome summary for a foreach run."""
+
+    def __init__(self, succeeded, failed, skipped, results):
+        self.succeeded = succeeded
+        self.failed = failed
+        self.skipped = skipped
+        self.results = results
+
+    def __repr__(self):
+        return (
+            "ForeachResult("
+            f"succeeded={self.succeeded}, "
+            f"failed={self.failed}, "
+            f"skipped={self.skipped}, "
+            f"results={self.results!r}"
+            ")"
+        )
+
+
+def foreach(
+    list_file,
+    task_file,
+    n=None,
+    cwd=None,
+    yolo=True,
+    flags=None,
+):
+    """Run a task file over each item in list_file and update the file."""
+    task_def = load_task_file(task_file)
+    lines, ends_with_newline = _read_lines(list_file)
+    items, skipped = _collect_items(lines)
+
+    if not items:
+        return ForeachResult(0, 0, skipped, [])
+
+    max_workers = _max_workers(n, len(items))
+    lock = threading.Lock()
+    results = []
+    counts = {
+        "running": 0,
+        "success": 0,
+        "failed": 0,
+    }
+
+    progress = tqdm(total=len(items))
+    try:
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = []
+            for index, item in items:
+                futures.append(
+                    executor.submit(
+                        _run_item,
+                        index,
+                        item,
+                        task_def,
+                        lines,
+                        ends_with_newline,
+                        list_file,
+                        cwd,
+                        yolo,
+                        flags,
+                        counts,
+                        results,
+                        progress,
+                        lock,
+                    )
+                )
+            for future in as_completed(futures):
+                future.result()
+    finally:
+        progress.close()
+
+    return ForeachResult(
+        counts["success"],
+        counts["failed"],
+        skipped,
+        results,
+    )
+
+
+def _max_workers(n, total):
+    if n is None:
+        return total
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    if n > total:
+        return total
+    return n
+
+
+def _read_lines(path):
+    with open(path, "r", encoding="utf-8") as handle:
+        data = handle.read()
+    ends_with_newline = data.endswith("\n")
+    return data.splitlines(), ends_with_newline
+
+
+def _write_lines(path, lines, ends_with_newline):
+    text = "\n".join(lines)
+    if ends_with_newline:
+        text += "\n"
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(text)
+
+
+def _collect_items(lines):
+    items = []
+    skipped = 0
+    for index, line in enumerate(lines):
+        if not line.strip():
+            continue
+        if _status_marker(line):
+            skipped += 1
+            continue
+        items.append((index, line))
+    return items, skipped
+
+
+def _status_marker(line):
+    if not line:
+        return None
+    marker = line[0]
+    if marker in _STATUS_SET:
+        return marker
+    return None
+
+
+def _status_text(counts):
+    return (
+        f"{_STATUS_RUNNING}: {counts['running']}, "
+        f"{_STATUS_SUCCESS}: {counts['success']}, "
+        f"{_STATUS_FAILED}: {counts['failed']}"
+    )
+
+
+def _single_line(text):
+    if not text:
+        return ""
+    return text.replace("\r", " ").replace("\n", " ")
+
+
+def _format_turns(used, total):
+    used_text = "?" if used is None else str(used)
+    total_text = "?" if total is None else str(total)
+    return f"[turns: {used_text}/{total_text}]"
+
+
+def _run_item(
+    index,
+    item,
+    task_def,
+    lines,
+    ends_with_newline,
+    list_file,
+    cwd,
+    yolo,
+    flags,
+    counts,
+    results,
+    progress,
+    lock,
+):
+    running_line = f"{_STATUS_RUNNING} {item}"
+    with lock:
+        lines[index] = running_line
+        _write_lines(list_file, lines, ends_with_newline)
+        counts["running"] += 1
+        progress.set_postfix_str(_status_text(counts))
+
+    summary = ""
+    success = False
+    attempts = None
+    max_attempts = None
+    try:
+        task = AutoTask(
+            task_def,
+            item,
+            10,
+            cwd,
+            yolo,
+            None,
+            flags,
+        )
+        max_attempts = task.max_attempts
+        result = task()
+        success = result.success
+        attempts = result.attempts
+        summary = result.summary or ""
+    except Exception as exc:
+        summary = f"{type(exc).__name__}: {exc}"
+        success = False
+
+    summary = _single_line(summary)
+    turns = _format_turns(attempts, max_attempts)
+    if summary:
+        summary = f"{summary} {turns}"
+    else:
+        summary = turns
+    status = _STATUS_SUCCESS if success else _STATUS_FAILED
+    final_line = f"{status} {item} | {summary}"
+
+    with lock:
+        lines[index] = final_line
+        _write_lines(list_file, lines, ends_with_newline)
+        counts["running"] -= 1
+        if success:
+            counts["success"] += 1
+        else:
+            counts["failed"] += 1
+        results.append((item, success, summary))
+        progress.update(1)
+        progress.set_postfix_str(_status_text(counts))
+        tqdm.write(final_line, file=sys.stdout)

{codexapi-0.3.4 → codexapi-0.5.0}/src/codexapi/ralph.py

@@ -15,7 +15,7 @@ _PROMISE_RE = re.compile(r"<promise>(.*?)</promise>", re.DOTALL)
 def run_ralph_loop(
     prompt,
     cwd=None,
-    yolo=False,
+    yolo=True,
     flags=None,
     max_iterations=0,
     completion_promise=None,
@@ -135,7 +135,7 @@ def run_ralph_loop(
             elif runner is None:
                 runner = Agent(cwd, yolo, None, flags)
 
-            message = runner(prompt + '\nIf there are multiple paths forward, please use your own best judgement as to which to try first - I trust you!\n')
+            message = runner(prompt + '\nIf there are multiple paths forward, you MUST use your own best judgement as to which to try first! Do not ask the user to choose an option, they hereby give you explciit permission to pick the best one yourself.\n')
             print(message)
             last_message = message
 

{codexapi-0.3.4 → codexapi-0.5.0}/src/codexapi/task.py

@@ -10,8 +10,9 @@ _logger = logging.getLogger(__name__)
 
 _CHECK_PREFIX = (
     "You are a verification agent. Explore this workspace and carefully evaluate it "
-    "against the check below. Collect evidence by running any tests and/or reading "
+    "against the task below. Collect evidence by running any tests and/or reading "
     "and tracing through code, but do not change any of the code.\n"
+    "Act as a collaborator who wants to give the task owner all the information they need to succeed.\n"
     "Return only JSON with keys: success (boolean) and reason (string).\n"
     "Set success to true only if everything matches the intent."
 )
@@ -141,9 +142,11 @@ def _print_progress(
 
 def _fix_prompt(error):
     return (
-        "The verification check failed:\n"
+        "Thanks for your work. An automated verifier reported these issues:\n"
         f"{error}\n\n"
-        "Please fix the issues while staying close to the original intent."
+        "Take another look and see whether you agree and, if so, please take this "
+        "feedback into consideration and use it to continue to make progress "
+        "towards our original goal and intent."
     )
 
 
@@ -176,7 +179,7 @@ def task(
     check=None,
     n=10,
     cwd=None,
-    yolo=False,
+    yolo=True,
     flags=None,
     progress=False,
 ):
@@ -209,7 +212,7 @@ def task_result(
     check=None,
     n=10,
     cwd=None,
-    yolo=False,
+    yolo=True,
     flags=None,
     progress=False,
 ):
@@ -319,7 +322,7 @@ class Task:
         prompt,
         max_attempts=10,
         cwd=None,
-        yolo=False,
+        yolo=True,
         thread_id=None,
         flags=None,
     ):
@@ -328,6 +331,7 @@ class Task:
         self.prompt = prompt
         self.max_attempts = max_attempts
         self.cwd = cwd
+        self.last_output = None
         self.agent = Agent(
             cwd,
             yolo,
@@ -341,8 +345,9 @@ class Task:
     def tear_down(self):
         """Delete the directory etc."""
 
-    def check(self):
+    def check(self, output=None):
         """ Check if the task is done, return a string describing the problems if not.
+            The output argument is the last agent response.
             This can be any combination of running tests, python code or running an agent
             with a specific prompt in self.cwd.
          """
@@ -356,9 +361,11 @@ class Task:
     def fix_prompt(self, error):
         """Build a prompt that asks the agent to fix checker failures."""
         return (
-            "The following checks failed:\n"
+            "Thanks for your work. An automated verifier reported these issues:\n"
             f"{error}\n\n"
-            "Can you please dive in and see if you agree with this assessment, then fix these issues while staying as close as you can to the spirit of the original task?"
+            "Take another look and see whether you agree and, if so, please take "
+            "this feedback into consideration and use it to continue to make "
+            "progress towards our original goal and intent."
         )
 
     def success_prompt(self):
@@ -382,18 +389,20 @@ class Task:
 
             # Start with the initial prompt
             output = self.agent(self.prompt)
+            self.last_output = output
             if debug:
                 _logger.debug("Initial output: %s", output)
             
             # Try correcting it up to max_attempts times
             for attempt in range(self.max_attempts):
-                error = self.check()
+                error = self.check(self.last_output)
                 if debug:
                     _logger.debug("Check error: %s", error)
                     
                 if error:
                     # if there were errors, tell the agent to fix them
                     output = self.agent(self.fix_prompt(error))
+                    self.last_output = output
                     if debug:
                         _logger.debug("Fix output: %s", output)
                 else:

codexapi-0.5.0/src/codexapi/taskfile.py

@@ -0,0 +1,108 @@
+"""Load YAML task files and map them onto Task hooks."""
+
+import yaml
+
+from .agent import agent
+from .task import Task
+
+_ITEM_TOKEN = "{{item}}"
+
+
+def load_task_file(path):
+    """Load a YAML task file and return a normalized task definition."""
+    if not path:
+        raise ValueError("task file path is required")
+    with open(path, "r", encoding="utf-8") as handle:
+        data = yaml.safe_load(handle) or {}
+    if not isinstance(data, dict):
+        raise ValueError("Task file must be a YAML mapping.")
+
+    prompt = data.get("prompt")
+    if not isinstance(prompt, str) or not prompt.strip():
+        raise ValueError("Task file missing non-empty 'prompt'.")
+
+    return {
+        "prompt": prompt,
+        "set_up": _optional_str(data.get("set_up")),
+        "tear_down": _optional_str(data.get("tear_down")),
+        "check": _optional_str(data.get("check")),
+        "on_success": _optional_str(data.get("on_success")),
+        "on_failure": _optional_str(data.get("on_failure")),
+    }
+
+
+def _optional_str(value):
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value if value.strip() else None
+    raise ValueError("Task file values must be strings.")
+
+
+def _render(text, item):
+    if text is None:
+        return None
+    if item is None:
+        return text
+    return text.replace(_ITEM_TOKEN, item)
+
+
+class AutoTask(Task):
+    """Task subclass that maps YAML strings onto Task hooks."""
+
+    def __init__(
+        self,
+        config,
+        item=None,
+        max_attempts=10,
+        cwd=None,
+        yolo=True,
+        thread_id=None,
+        flags=None,
+    ):
+        if not isinstance(config, dict):
+            raise TypeError("config must be a task definition dict")
+        self._config = config
+        self._item = "" if item is None else str(item)
+        self._yolo = yolo
+        self._flags = flags
+        prompt = _render(config.get("prompt"), self._item)
+        super().__init__(prompt, max_attempts, cwd, yolo, thread_id, flags)
+
+    def _hook(self, name):
+        return _render(self._config.get(name), self._item)
+
+    def set_up(self):
+        text = self._hook("set_up")
+        if text:
+            agent(text, self.cwd, self._yolo, self._flags)
+
+    def tear_down(self):
+        text = self._hook("tear_down")
+        if text:
+            agent(text, self.cwd, self._yolo, self._flags)
+
+    def check(self, output=None):
+        text = self._hook("check")
+        if not text:
+            return None
+        last_output = output if output is not None else self.last_output
+        last_output = last_output or ""
+        if last_output:
+            prompt = f"{text}\n\nAGENT OUTPUT:\n{last_output}"
+        else:
+            prompt = text
+        result = agent(prompt, self.cwd, self._yolo, self._flags)
+        if not isinstance(result, str) or not result.strip():
+            return None
+        return result
+
+    def on_success(self, result):
+        text = self._hook("on_success")
+        if text:
+            agent(text, self.cwd, self._yolo, self._flags)
+
+    def on_failure(self, result):
+        text = self._hook("on_failure")
+        if text:
+            agent(text, self.cwd, self._yolo, self._flags)

{codexapi-0.3.4 → codexapi-0.5.0/src/codexapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.3.4
+Version: 0.5.0
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -9,6 +9,8 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.64
 
 # CodexAPI
 
@@ -70,6 +72,7 @@ echo "Say hello." | codexapi run
 
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
+codexapi task -f task.yaml
 ```
 
 Show running sessions and their latest activity:
@@ -85,6 +88,8 @@ Resume a session and print the thread id to stderr:
 codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off."
 ```
 
+Use `--no-yolo` to run Codex with `--full-auto` instead.
+
 Ralph loop mode repeats the same prompt until a completion promise or a max
 iteration cap is hit (0 means unlimited). Cancel by deleting
 `.codexapi/ralph-loop.local.md` or running `codexapi ralph --cancel`.
@@ -95,29 +100,36 @@ codexapi ralph --ralph-fresh "Try again from scratch." --max-iterations 3
 codexapi ralph --cancel --cwd /path/to/project
 ```
 
+Run a task file across a list file:
+
+```bash
+codexapi foreach list.txt task.yaml
+codexapi foreach list.txt task.yaml -n 4
+```
+
 ## API
 
-### `agent(prompt, cwd=None, yolo=False, flags=None) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None) -> str`
 
 Runs a single Codex turn and returns only the agent's message. Any reasoning
 items are filtered out.
 
 - `prompt` (str): prompt to send to Codex.
 - `cwd` (str | PathLike | None): working directory for the Codex session.
-- `yolo` (bool): pass `--yolo` to Codex when true.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `Agent(cwd=None, yolo=False, thread_id=None, flags=None)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
 
 - `__call__(prompt) -> str`: send a prompt to Codex and return the message.
 - `thread_id -> str | None`: expose the underlying session id once created.
-- `yolo` (bool): pass `--yolo` to Codex when true.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `task(prompt, check=None, n=10, cwd=None, yolo=False, flags=None) -> str`
+### `task(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> str`
 
 Runs a task with checker-driven retries and returns the success summary.
 Raises `TaskFailed` when the maximum attempts are reached.
@@ -125,12 +137,12 @@ Raises `TaskFailed` when the maximum attempts are reached.
 - `check` (str | None | False): custom check prompt, default checker, or `False` to skip.
 - `n` (int): maximum number of retries after a failed check.
 
-### `task_result(prompt, check=None, n=10, cwd=None, yolo=False, flags=None) -> TaskResult`
+### `task_result(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> TaskResult`
 
 Runs a task with checker-driven retries and returns a `TaskResult` without
 raising `TaskFailed`.
 
-### `Task(prompt, max_attempts=10, cwd=None, yolo=False, thread_id=None, flags=None)`
+### `Task(prompt, max_attempts=10, cwd=None, yolo=True, thread_id=None, flags=None)`
 
 Runs a Codex task with checker-driven retries. Subclass it and implement
 `check()` to return an error string when the task is incomplete, or return
@@ -139,7 +151,7 @@ Runs a Codex task with checker-driven retries. Subclass it and implement
 - `__call__() -> TaskResult`: run the task.
 - `set_up()`: optional setup hook.
 - `tear_down()`: optional cleanup hook.
-- `check() -> str | None`: return an error description or `None`/`""`.
+- `check(output=None) -> str | None`: return an error description or `None`/`""`. `output` is the last agent response.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
 
@@ -161,12 +173,31 @@ Exception raised by `task()` when retries are exhausted.
 - `attempts` (int | None): attempts made when the task failed.
 - `errors` (str | None): last checker error, if any.
 
+### `foreach(list_file, task_file, n=None, cwd=None, yolo=True, flags=None) -> ForeachResult`
+
+Runs a task file over a list of items, updating the list file in place.
+
+- `list_file` (str | PathLike): path to the list file to process.
+- `task_file` (str | PathLike): YAML task file (must include `prompt`).
+- `n` (int | None): limit parallelism to N (default: run all items in parallel).
+- `cwd` (str | PathLike | None): working directory for the Codex session.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
+- `flags` (str | None): extra CLI flags to pass to Codex.
+
+### `ForeachResult(succeeded, failed, skipped, results)`
+
+Simple result object returned by `foreach()`.
+
+- `succeeded` (int): number of successful items.
+- `failed` (int): number of failed items.
+- `skipped` (int): number of items skipped (already marked in the list file).
+- `results` (list[tuple]): `(item, success, summary)` entries for items that ran.
+
 ## Behavior notes
 
 - Uses `codex exec --json` and parses JSONL events for `agent_message` items.
 - Automatically passes `--skip-git-repo-check` so it can run outside a git repo.
-- Passes `--full-auto` unless `--yolo` is enabled.
-- Passes `--yolo` when enabled (use with care).
+- Passes `--yolo` by default (use `--no-yolo` or `yolo=False` for `--full-auto`).
 - Raises `RuntimeError` if Codex exits non-zero or returns no agent message.
 
 ## Configuration

{codexapi-0.3.4 → codexapi-0.5.0}/src/codexapi.egg-info/SOURCES.txt

@@ -5,10 +5,13 @@ src/codexapi/__init__.py
 src/codexapi/__main__.py
 src/codexapi/agent.py
 src/codexapi/cli.py
+src/codexapi/foreach.py
 src/codexapi/ralph.py
 src/codexapi/task.py
+src/codexapi/taskfile.py
 src/codexapi.egg-info/PKG-INFO
 src/codexapi.egg-info/SOURCES.txt
 src/codexapi.egg-info/dependency_links.txt
 src/codexapi.egg-info/entry_points.txt
+src/codexapi.egg-info/requires.txt
 src/codexapi.egg-info/top_level.txt

codexapi-0.5.0/src/codexapi.egg-info/requires.txt

@@ -0,0 +1,2 @@
+PyYAML>=6.0
+tqdm>=4.64