home / skills / openclaw / skills / codexmonitor

codexmonitor skill

safe

This skill helps you monitor local OpenAI Codex sessions from the CLI and VS Code, simplifying browsing, listing, and inspecting sessions.

npx playbooks add skill openclaw/skills --skill codexmonitor

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.7 KB

---
name: codexmonitor
version: 0.2.1
description: >
  List/inspect/watch local OpenAI Codex sessions (CLI + VS Code) using the
  CodexMonitor Homebrew formula. Reads sessions from ~/.codex/sessions by default
  (or via CODEX_SESSIONS_DIR / CODEX_HOME overrides). Requires the cocoanetics/tap
  Homebrew tap.
homepage: https://github.com/Cocoanetics/CodexMonitor
metadata:
  moltbot:
    emoji: "🧾"
    os: ["darwin"]
    requires:
      bins: ["codexmonitor"]
    install:
      - id: brew
        kind: brew
        formula: cocoanetics/tap/codexmonitor
        bins: ["codexmonitor"]
        label: "Install codexmonitor (brew)"
  openclaw:
    requires:
      bins: ["codexmonitor"]
    install:
      - id: brew
        kind: brew
        formula: cocoanetics/tap/codexmonitor
        bins: ["codexmonitor"]
        label: "Install codexmonitor via Homebrew"
---

# codexmonitor

Use `codexmonitor` to browse local OpenAI Codex sessions.

## Setup

See [SETUP.md](SETUP.md) for prerequisites and setup instructions.

## Common commands

- List sessions (day): `codexmonitor list 2026/01/08`
- List sessions (day, JSON): `codexmonitor list --json 2026/01/08`
- Show a session: `codexmonitor show <session-id>`
- Show with ranges: `codexmonitor show <session-id> --ranges 1...3,26...28`
- Show JSON: `codexmonitor show <session-id> --json`
- Watch all: `codexmonitor watch`
- Watch specific: `codexmonitor watch --session <session-id>`

## Notes
- Sessions live under `~/.codex/sessions/YYYY/MM/DD/` by default.
- If your sessions live somewhere else, set `CODEX_SESSIONS_DIR` (preferred) or `CODEX_HOME`.
- Sessions can be resumed/appended by id via Codex: `codex exec resume <SESSION_ID> "message"`.

Overview

This skill lets you list, inspect, and watch local OpenAI Codex sessions from the command line or VS Code. It reads session files stored under ~/.codex/sessions by default and supports JSON output and range slicing. Installation uses the codexmonitor Homebrew formula from the cocoanetics/tap tap.

How this skill works

codexmonitor scans a sessions directory (default ~/.codex/sessions or overridden by CODEX_SESSIONS_DIR / CODEX_HOME) and presents session metadata and content. Commands include list, show (with range selection), and watch to tail active sessions in real time. The tool can output plain text or JSON for integration with scripts and editors.

When to use it

Audit recent Codex activity by day or session ID.
Inspect the full transcript or selected message ranges from a session.
Monitor live or appending sessions with watch during development.
Export session data in JSON for tooling, archiving, or analysis.
Resume or append messages to a session using codex exec resume with the session ID.

Best practices

Set CODEX_SESSIONS_DIR if your sessions are stored outside ~/.codex/sessions.
Use --json for deterministic output when piping to other tools or scripts.
Use --ranges when you only need specific message slices to reduce noise.
Combine watch with session-specific filtering to follow a single conversation.
Keep regular backups of your sessions folder if you rely on historical transcripts.

Example use cases

Quickly list all sessions from a specific date to find recent work.
Open a session in VS Code and use show --ranges to focus on relevant messages.
Stream live session updates during interactive debugging with watch.
Export a session as JSON to import into an analysis pipeline or archive.
Resume an interrupted conversation by passing its session ID to codex exec resume.

FAQ

How do I change where codexmonitor looks for sessions?

Set CODEX_SESSIONS_DIR to the desired path or set CODEX_HOME. The tool falls back to ~/.codex/sessions if neither is defined.

Do I need a special Homebrew tap to install?

Yes. Install codexmonitor from the cocoanetics/tap Homebrew tap as a prerequisite.