# Codex Exec Sub Agent

> Delegate a task to a separate Codex process by running `codex exec --json` and logging the full JSONL event stream to a timestamped folder under `~/.codex/sub_agent_runs/`. Use when you want a lightweight “sub-agent” workflow where the main agent provides only a prompt, and the runner script handles run folders, prompt capture, and printing the JSONL path.

- Skill: `chandeldivyam/codex-exec-sub-agent` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add chandeldivyam/codex-exec-sub-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chandeldivyam/codex-exec-sub-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: chandeldivyam (https://skillmd.com/u/chandeldivyam)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/chandeldivyam/codex-exec-sub-agent

---


# Run a sub-agent (Codex exec) and capture JSONL

Use the bundled runner script to avoid manually picking filenames/paths for the JSONL log.

## Runner

- Script: `~/.codex/skills/codex-exec-sub-agent/scripts/run.sh`
- Default runs dir: `~/.codex/sub_agent_runs/` (override with `CODEX_SUBAGENT_RUNS_DIR`)
- Prints: the full path to `run.jsonl` as the **last line** on stdout

## How to call

Important: when you ask a “main agent” to run this, configure that main agent’s timeout to **at least ~10 minutes**. Otherwise the *parent* may time out while the nested `codex exec` is still running (even though the sub-agent would eventually finish).

Pass the prompt via stdin (recommended for long prompts):

```bash
cat prompt.txt | ~/.codex/skills/codex-exec-sub-agent/scripts/run.sh
```

Or pass it as an argument (ok for short prompts):

```bash
~/.codex/skills/codex-exec-sub-agent/scripts/run.sh "Do X, then write results to /full/path/output.md"
```

## How to think about the prompt

Treat the sub-agent prompt like a mini-brief:

- **Be explicit about the outcome**: what “done” looks like.
- **Limit scope**: what to include vs what to ignore.
- **Set output rules**: format, length, tone, structure (especially if non-technical).
- **Prefer deterministic artifacts**: if you want a file created/updated, tell it the **full path**.

## Notes

- Prefer full paths in prompts for any files you want created/updated.
- The JSONL log is for inspection/debugging; treat the “real output” as a file path you instruct in the prompt.