Codex

ralph-status

Check status of current or previous agent loop

104 stars

byjmagly

View on GitHub Installation ↓

Best use case

ralph-status is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

It is a strong fit for teams already working in Codex.

Check status of current or previous agent loop

Teams using ralph-status should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/ralph-status/SKILL.md --create-dirs "https://raw.githubusercontent.com/jmagly/aiwg/main/.agents/skills/ralph-status/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/ralph-status/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How ralph-status Compares

Feature / Agent	ralph-status	Standard Approach
Platform Support	Codex	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Check status of current or previous agent loop

Which AI agents support this skill?

This skill is designed for Codex.

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

Related Guides

Cursor vs Codex for AI Workflows

Compare Cursor and Codex for AI coding workflows, repository assistance, debugging, refactoring, and reusable developer skills.

AI Agents for Coding

Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.

AI Agents for Marketing

Discover AI agents for marketing workflows, from SEO and content production to campaign research, outreach, and analytics.

SKILL.md Source

# Al Status

Check the status of agent loops.

## Usage

```
/ralph-status              # Current loop status
/ralph-status --verbose    # Detailed iteration history
/ralph-status --latest     # Show latest completion report
/ralph-status --all        # List all completion reports
```

## Your Actions

### Default (Current Loop)

1. Read `.aiwg/ralph/current-loop.json`
2. Display status summary

**If active loop exists**:
```
Agent Loop: ACTIVE

Task: {task}
Completion: {completion}
Progress: {current}/{max} iterations
Duration: {elapsed}
Status: {running | paused}

Last iteration:
  Result: {result}
  Learnings: {learnings}

Use /ralph-resume to continue or /ralph-abort to stop.
```

**If no active loop**:
```
No active agent loop.

Use /ralph "task" --completion "criteria" to start one.
```

### --verbose

Include full iteration history:

```
Agent Loop: ACTIVE

Task: {task}
Completion: {completion}
Progress: {current}/{max} iterations

Iteration History:
| # | Time | Action | Result | Learnings |
|---|------|--------|--------|-----------|
| 1 | 10:30 | Initial attempt | 3 failures | Need auth mocks |
| 2 | 10:32 | Added mocks | 1 failure | Date edge case |
| 3 | 10:34 | Fixed date | In progress... | - |
```

### --latest

Read and display most recent completion report:

1. Find latest `completion-*.md` in `.aiwg/ralph/`
2. Display contents

### --all

List all completion reports:

```
Agent Loop History

| Date | Task | Status | Iterations |
|------|------|--------|------------|
| 2025-01-15 10:45 | Fix auth tests | SUCCESS | 3 |
| 2025-01-14 15:20 | Migrate to ESM | SUCCESS | 8 |
| 2025-01-13 09:00 | Add coverage | MAX_ITER | 10 |

View report: /ralph-status --report 2025-01-15
```

## State File Location

- Current loop: `.aiwg/ralph/current-loop.json`
- Iterations: `.aiwg/ralph/iterations/`
- Reports: `.aiwg/ralph/completion-*.md`

## Error Handling

**No state directory**:
```
Al has not been used in this project yet.

Get started with:
  /ralph "your task" --completion "verification command"

Or:
  /ralph --interactive
```

**Corrupted state**:
```
agent loop state file is corrupted.

Options:
1. Delete and start fresh: rm -rf .aiwg/ralph/
2. Check file manually: cat .aiwg/ralph/current-loop.json
```

## References

- @$AIWG_ROOT/agentic/code/addons/ralph/README.md — Ralph addon overview and loop executor documentation
- @$AIWG_ROOT/docs/cli-reference.md — CLI reference for ralph-status and related commands
- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/vague-discretion.md — Loop completion and iteration limit rules
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/README.md — SDLC framework context