Ralph

Ralph is an autonomous AI article writing agent that runs Claude Code to write a complete article in a single run. Memory persists via git history and progress.txt.

Based on Geoffrey Huntley's Ralph pattern.

Prerequisites

• Claude Code installed and authenticated (npm install -g @anthropic-ai/claude-code)
• A git repository for your article project

Setup

Option 1: Copy to your project

Copy the ralph files into your project:

# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md

chmod +x scripts/ralph/ralph.sh

Option 2: Install skills globally

Copy the skills to your Claude config for use across all projects:

cp -r .claude/skills/article-outline ~/.claude/skills/
cp -r .claude/skills/ralph ~/.claude/skills/
cp -r .claude/skills/article-research ~/.claude/skills/

Workflow

1. Plan Your Article

Use the article-outline skill to plan a detailed article structure:

Load the article-outline skill and plan an article about [your topic]

Answer the clarifying questions about audience, depth, and goals. The skill will:

• Research existing content and key topics
• Search your local files for notes and research
• Generate article.json with the article definition

2. Run Ralph

./ralph.sh

Ralph will:

1. Create a feature branch (from branchName)
2. Conduct deep research on the article's topics (saved to research/)
3. Write the article as an MDX file with sources
4. Commit if quality checks pass
5. Output <promise>COMPLETE</promise> when finished

Key Files

File	Purpose
ralph.sh	The bash script that runs Claude Code
CLAUDE.md	Prompt template for Claude Code
article.json	Article definition with title, description, research topics
article.json.example	Example article format for reference
progress.txt	Writing patterns and completion notes
articles/	Output directory for MDX article files
research/	Research reports generated before writing
.claude/skills/article-outline/	Skill for planning articles with research
.claude/skills/ralph/	Skill for converting ideas to JSON
.claude/skills/article-research/	Skill for deep research on article topics

Critical Concepts

Single Run = Complete Article

Ralph writes one complete article per run. The workflow is:

1. Read article definition from article.json
2. Conduct deep research
3. Write the complete article
4. Commit and signal completion

Deep Research with Sources

Before writing, Ralph conducts deep research:

1. Checks if research/article-research.md exists
2. If not, uses web-search-agent for each research topic
3. Compiles findings into a research report with sources
4. Uses the report to ensure article accuracy

Each article includes a Sources section citing the materials used.

Article Sizing

Articles should be 1,000-3,000 words depending on topic complexity. Right-sized articles cover:

• One focused topic or technique
• A single tutorial or walkthrough
• A deep dive into a specific concept

Writing Patterns

Ralph can update progress.txt with discovered patterns:

• Voice and tone decisions
• Terminology definitions
• Formatting conventions

These patterns help maintain consistency if you write multiple articles.

Output Format

Articles are written as MDX files in articles/:

articles/
└── building-fast-apis-with-go.mdx

Each file follows this structure:

---
title: "Article Title"
description: "Brief article description"
author: "Author Name"
date: "YYYY-MM-DD"
---

# Article Title

[Article content...]

## Conclusion

[Key takeaways]

## Sources

- [Source Title](URL) - What this source contributed
- [Source Title](URL) - Description

Debugging

Check current state:

# See article definition
cat article.json | jq '.article'

# See writing patterns
cat progress.txt

# Check git history
git log --oneline -10

# List written articles
ls -la articles/

# View research report
cat research/article-research.md

Customizing the Prompt

After copying CLAUDE.md to your project, customize for your articles:

• Add style guidelines
• Include voice and tone preferences
• Add domain-specific terminology

References

• Geoffrey Huntley's Ralph article
• Claude Code documentation