Skip to content

README.md

Latest commit

 

History

History
295 lines (222 loc) · 12.3 KB

README.md

File metadata and controls

295 lines (222 loc) · 12.3 KB
Raw

Codex Scripts

English | 中文

A collection of configuration scripts for the OpenAI Codex CLI tool.

Quick Start

One command to install everything:

git clone https://github.com/calmkart/vibe-coding-script.git
cd vibe-coding-script/codex
./setup.sh install              # English
./setup.sh install --lang zh    # Chinese labels

Or install a specific feature:

./setup.sh install auto-approve             # Only auto-approve
./setup.sh install iterm-status --lang zh   # Only tab indicator (Chinese)
./setup.sh install iterm-monitor --lang zh  # Only session dashboard (Chinese)
./setup.sh install dashboard                # Only terminal TUI dashboard
./setup.sh install skills/fix-review             # fix-review instruction (global ~/.codex, default)
./setup.sh install skills/fix-review --local    # fix-review instruction (current project only)
./setup.sh install skills/e2e-guard             # e2e-guard instruction (global, default)
./setup.sh install skills/e2e-guard --local     # e2e-guard instruction (current project only)
./setup.sh install skills/grafana-session-debug # Grafana Chrome session cookie jar helper

Management:

./setup.sh status                    # Show all component status
./setup.sh uninstall                 # Remove everything
./setup.sh uninstall iterm-monitor   # Remove specific feature

After install, restart iTerm2. First-time only: allow Python API dialog, then drag "Codex Sessions" to the status bar.

Features

codex/
├── setup.sh                  # Unified entry point
├── auto-approve/             # Full-auto approval mode
│   └── setup.sh
├── iterm-status/             # Tab color & title indicator
│   └── setup.sh
├── iterm-monitor/            # Session dashboard
│   ├── setup.sh
│   └── daemon.py
├── dashboard/                # Terminal TUI dashboard
│   ├── setup.sh
│   ├── app.py                # Main Textual application
│   ├── requirements.txt
│   ├── data/                 # Data layer (sessions, history, stats, search, cache)
│   ├── screens/              # UI screens (active, browser, usage, conversation)
│   ├── widgets/              # Reusable widgets (session card, chart, heatmap, etc.)
│   ├── utils/                # Formatting, pricing, export, iTerm integration
│   └── styles/               # Textual CSS theme
├── skills/                   # Codex skills (SKILL.md)
│   ├── fix-review/           # Auto-fix GitLab MR review comments
│   │   ├── setup.sh
│   │   └── AGENTS.md
│   ├── e2e-guard/            # Auto-generate & run minimal E2E test plans
│   │   ├── setup.sh
│   │   ├── AGENTS.md
│   │   ├── ref-plan-template.md
│   │   ├── ref-write-patterns.md
│   │   └── ref-gitlab-ci.md
│   └── grafana-session-debug/ # Refresh Grafana cookie jar from local Chrome session
│       ├── setup.sh
│       ├── AGENTS.md
│       └── scripts/grafana_chrome_session.py

auto-approve

Run Codex in full-auto approval mode without manual confirmation.

  • Writes approval_policy = "never" to ~/.codex/config.toml and creates a codex-auto wrapper using -a never
  • No additional dependencies required

iterm-status

iTerm2 tab color & title changes based on Codex status.

State Tab Color Tab Title
Working Green ◉ Working · project-name
Action Needed Amber ⏸ Action Needed · project-name
Ready Blue ✓ Ready · project-name

Supports --lang zh for Chinese labels (执行中 / 待确认 / 等待输入).

Status detection:

Uses Codex native hooks. The installer enables [features].hooks = true, merges managed entries into ~/.codex/hooks.json, records trust state for those managed entries, and writes /tmp/codex-sessions/*.json for the dashboard.

State Trigger Description
Working UserPromptSubmit, PostToolUse Codex is generating or executing
Action Needed PermissionRequest Codex needs user confirmation
Ready SessionStart, Stop Turn ended, waiting for next prompt

Direct launch — after install, run codex directly. The old codex-iterm wrapper is no longer used.

Directory lock — the tab title shows the project directory from the first hook event and never changes during that session, even when Codex edits files in subdirectories.

iterm-monitor

Multi-session dashboard with badges, status bar, and click-to-navigate popover.

Feature Description
Badge 📂 project / 🌿 branch — compact watermark (15% width)
Dashboard Click status bar → session cards, click card → jump to that terminal
Status Bar 🤖 3 │ ⚡2 🔔1 ✔️1 — total + count by state

Icons: ⚡ running, 🔔 waiting for input, ✔️ idle.

Sessions persist as long as the Codex process is alive (PID-based tracking, not timeout-based).

Supports --lang zh for Chinese dashboard labels (运行中 / 待确认 / 空闲).

Requires iterm-status (auto-installed if missing).

dashboard

A rich terminal TUI built with Python + Textual for managing Codex sessions from your terminal.

Requirements: Python 3, textual>=0.47.0, rich>=13.0.0 (auto-installed in a venv)

Install & launch:

./setup.sh install dashboard    # Install
codex-dashboard                 # Launch

Tabs:

# Tab Description
1 Active Real-time view of running Codex sessions with usage/cost (auto-refreshes every 2s)
2 History Dual-pane browser — projects (with cost) on the left, sessions on the right
3 Usage Daily activity, model breakdown, per-project cost, all filterable by time period (7d/30d/all)
4 Conversation Full conversation viewer with rich text rendering

Keyboard shortcuts:

Key Action
Tab / Shift+Tab Next / prev tab
1–4 Switch to specific tab
↑ / ↓ Navigate items
← / → Switch panes (History) / Change period (Usage)
Enter Open / Select
Escape Back / Close
Ctrl+F or / Search conversations
Ctrl+R Refresh all data
Ctrl+G Jump to iTerm2 tab (Active)
r Resume session (codex resume SESSION_ID)
Del / Backspace Delete session (History, with confirmation)
e Export to Markdown
t Toggle thinking blocks
s Cycle sort order (History)
Home / End Scroll to top / bottom (Conversation)
? Help overlay
q Quit

Data sources:

Data Path
Active sessions /tmp/codex-sessions/*.json
Session history ~/.codex/sessions/YYYY/MM/DD/*.jsonl
Session index ~/.codex/session_index.jsonl
Usage stats ~/.codex/stats-cache.json

How it works:

  • The dashboard reads Codex's native data files — no additional daemons or agents needed.
  • Active sessions are detected via /tmp/codex-sessions/ JSON files with PID-based liveness checks.
  • History is loaded from ~/.codex/sessions/ (date-organized JSONL files) and ~/.codex/session_index.jsonl.
  • Cost estimates use official OpenAI pricing (gpt-4o, gpt-4.1, gpt-5, gpt-5.4, o3, o4-mini).
  • An async TTL cache layer avoids redundant file reads.

skills/fix-review

A Codex skill (SKILL.md) that reads GitLab MR code review comments and auto-fixes the code. Installed to ~/.codex/skills/fix-review/.

Usage: In Codex, type /fix-review 123 (where 123 is the MR number).

Install:

./setup.sh install skills/fix-review          # Install globally (default)
./setup.sh install skills/fix-review --local  # Install to current project only

What it does:

  1. Reads GitLab MR discussions via API (configures token interactively on first use)
  2. Filters actionable review comments (skips resolved / acknowledgment-only)
  3. Locates the referenced file + line and applies the suggested fix
  4. Summarizes all changes when done

skills/e2e-guard

A Codex skill (SKILL.md) that automatically generates a minimal E2E test plan based on code changes, runs it with human-in-the-loop write operation approval, and loops through fix-and-retest until all tests pass. Installed to ~/.codex/skills/e2e-guard/.

Usage:

/e2e-guard                # Auto-detect changes (git diff)
/e2e-guard main..HEAD     # Specify git range
/e2e-guard mr:123         # GitLab MR mode — auto-fetch build artifact tags from CI pipeline

Install:

./setup.sh install skills/e2e-guard          # Install globally (default)
./setup.sh install skills/e2e-guard --local  # Install to current project only

Workflow:

  1. Analyzes code changes (git diff, git range, or GitLab MR diff via glab) to identify affected user flows
  2. GitLab CI integration (optional): when given mr:123, auto-fetches component image tags from the MR's CI pipeline build jobs — no manual copy-paste needed
  3. Generates a minimal E2E test plan as a human-readable Markdown file in .planning/e2e/
  4. Waits for human review — user fills in prerequisites (credentials, test machines, etc.) and approves. CI-sourced image tags are pre-filled automatically
  5. Executes tests step by step: read operations run automatically, write operations pause for confirmation
  6. Generates a detailed test report with failure classification (code bug / env issue / plan error / transient)
  7. On failure: AI analyzes root cause per failure type, fixes code, re-runs failed tests (up to 3 retries)

GitLab CI integration: Prefers glab CLI when available (simpler auth, glab mr diff works without local branch). Falls back to curl + .codex/gitlab.json.

Step types in generated test plans:

Tag Behavior
[READ] Auto-execute (queries, status checks)
[WRITE] Pause and ask for confirmation before executing
[WAIT] Auto-execute (polling, waiting for rollout)
[OBSERVE] Auto-execute and judge pass/fail against expected results (supports retry for eventual consistency)
[HUMAN] Pause and wait for human to complete a physical action

skills/grafana-session-debug

A Codex skill (SKILL.md) for Grafana Cloud debugging when a service account token is unavailable, the personal browser session is close to expiry, or API collection fails with 401/TLS/HTTP2 issues. It refreshes a Netscape cookie jar from the local Chrome session, verifies /api/user, and can test Grafana datasource proxy queries without printing cookie values.

Usage:

/grafana-session-debug refresh Grafana cookie from Chrome and test datasource UID DATASOURCE_UID

Install:

./setup.sh install skills/grafana-session-debug          # Install globally (default)
./setup.sh install skills/grafana-session-debug --local  # Install to current project only

Requirements: macOS Chrome profile cookies, macOS Keychain access to Chrome Safe Storage, and Python package cryptography.

Workflow:

  1. Copies a read-only snapshot of the local Chrome cookie DB and decrypts Grafana session cookies via the macOS Keychain
  2. Writes a Netscape cookie jar under /tmp with 0600 permissions by default, keeping secrets out of the repository
  3. Verifies /api/user through curl -b/-c
  4. Tests datasource proxy queries with POST + HTTP/1.1 + outer retries to reduce long-query and HTTP/2/TLS flakiness
  5. Prints only cookie names, expiry, and API status; never prints cookie values, tokens, or full Cookie headers

Boundary: this is for debugging and short-lived collection. Durable automation should use a Grafana service account token. Dashboard writes stay out of scope unless the user explicitly authorizes them.

Standalone Use

Each feature can also be run independently:

cd auto-approve && ./setup.sh install
cd iterm-status && ./setup.sh install --lang zh
cd iterm-monitor && ./setup.sh install
cd dashboard && ./setup.sh install
cd skills/fix-review && ./setup.sh install           # global (default)
cd skills/fix-review && ./setup.sh install --local   # current project only
cd skills/e2e-guard && ./setup.sh install            # global (default)
cd skills/e2e-guard && ./setup.sh install --local    # current project only
cd skills/grafana-session-debug && ./setup.sh install # global (default)