An autonomous AI writing system powered by Claude Code. Supports two modes:
- Fiction Mode - Generate novels and stories chapter by chapter
- Dissertation Mode - Write academic dissertations with an expert ensemble
Based on the Ralph pattern by snarktank.
Ralph runs Claude Code in a loop, generating one chapter at a time. Each iteration starts with fresh context—no memory fatigue, no creative drift. The system reads your requirements, writes a chapter, reviews it, and continues until complete.
┌─────────────────────────────────────────────────────────────────┐
│ ./scripts/ralph.sh my-project 20 │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ 1. Read prd.json → find next incomplete chapter │ │
│ │ 2. Read framework (STORY_BIBLE or DISSERTATION_FRAMEWORK) │ │
│ │ 3. Read progress.txt → learn from past chapters │ │
│ │ 4. Plan → Write → Review → Revise (skill ensemble) │ │
│ │ 5. Save chapter & update prd.json │ │
│ │ 6. Loop until all chapters complete │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
| Requirement | Installation |
|---|---|
| Claude Code | npm install -g @anthropic-ai/claude-code then claude to authenticate |
| jq | brew install jq (macOS) or apt install jq (Linux) |
| bash | Usually pre-installed |
# 1. Create a new story
./scripts/init-story.sh my-fantasy-novel
# 2. Edit your story bible
open stories/my-fantasy-novel/STORY_BIBLE.md
# 3. Define chapters in prd.json
open stories/my-fantasy-novel/prd.json
# 4. Run Ralph
./scripts/ralph.sh my-fantasy-novel 20# 1. Create a new dissertation
./scripts/init-dissertation.sh my-dissertation
# 2. Add your source material (existing drafts, PDFs, notes)
cp ~/dissertation-draft.pdf stories/my-dissertation/source-material/
# 3. Edit your framework
open stories/my-dissertation/DISSERTATION_FRAMEWORK.md
# 4. Define chapters in prd.json
open stories/my-dissertation/prd.json
# 5. Run Ralph
./scripts/ralph.sh my-dissertation 15Both modes use the stories/ directory:
ralph-storywriter/
├── scripts/
│ ├── ralph.sh # Main loop (both modes)
│ ├── init-story.sh # Create fiction project
│ ├── init-dissertation.sh # Create dissertation project
│ └── list-stories.sh # Show all projects and status
├── stories/ # YOUR PROJECTS LIVE HERE
│ ├── my-novel/ # Fiction project
│ │ ├── prd.json # Chapter definitions
│ │ ├── STORY_BIBLE.md # World, characters, guidelines
│ │ ├── progress.txt # Learning log
│ │ ├── writing-sample.md # Style reference (optional)
│ │ ├── chapters/ # Generated chapters
│ │ ├── characters/ # Character detail files
│ │ └── world-building/ # World detail files
│ └── my-dissertation/ # Dissertation project
│ ├── prd.json # Chapter definitions (mode: "dissertation")
│ ├── DISSERTATION_FRAMEWORK.md # Thesis, methodology, framework
│ ├── progress.txt # Learning log
│ ├── writing-sample.md # Voice reference (optional)
│ ├── source-material/ # PRIMARY CONTENT (PDFs, drafts, notes)
│ ├── literature/ # Notes on key sources
│ ├── chapters/ # Generated chapters
│ ├── drafts/ # Working drafts from expert writers
│ └── reviews/ # Critic feedback
├── .claude/skills/ # Writing skills Ralph uses
├── templates/ # Templates for new projects
└── prompt.md # Instructions Ralph follows
┌─────────────────────────────────────────────────────────────┐
│ FICTION WORKFLOW │
├─────────────────────────────────────────────────────────────┤
│ │
│ STORY_BIBLE.md ──────┐ │
│ characters/ │ │
│ world-building/ ├──→ /story-planner ──→ Plan │
│ writing-sample.md │ │ │
│ prd.json ────────────┘ ▼ │
│ /story-writer ──→ Draft │
│ │ │
│ ▼ │
│ /story-critic ──→ Review │
│ │ │
│ ▼ │
│ chapters/ch-[ID]-*.md │
│ │
└─────────────────────────────────────────────────────────────┘
1. Define your concept before running init-story.sh:
- Genre (Fantasy, Sci-Fi, Mystery, Romance, etc.)
- Logline (one sentence capturing your story)
- Tone (dark, lighthearted, epic, intimate)
2. Build your Story Bible (STORY_BIBLE.md):
### Maya Chen
**Role:** Protagonist
**Personality:**
- Analytical and curious
- Struggles with emotional vulnerability
**Speech Pattern:**
Short sentences. Questions everything.
**Example Dialogue:**
> "That does not add up. Show me the data."
### Magic System
- Magic draws from emotional energy
- Overuse causes "burnout"
- Only works within line of sight
### Style Notes
- Third person limited, Maya's POV
- Past tense
- Sparse prose, focus on dialogue
- Avoid: info-dumps, "said bookisms"3. Define chapters in prd.json with specific acceptance criteria:
{
"id": "CH-003",
"title": "The Discovery",
"description": "Maya finds the hidden lab.",
"acceptanceCriteria": [
"Chapter is 3000-4000 words",
"Maya breaks into the laboratory",
"Discovery of father's journal",
"Ends with Maya deciding to continue"
],
"priority": 3,
"passes": false
}| Skill | Purpose |
|---|---|
/story-planner |
Plan chapter beats and structure |
/story-writer |
Generate prose |
/story-critic |
Review quality and consistency |
Dissertation mode uses an expert ensemble pattern. Multiple domain experts contribute sections, then the author skill synthesizes them into a unified voice.
┌─────────────────────────────────────────────────────────────────┐
│ DISSERTATION WORKFLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ source-material/ ─────┐ │
│ DISSERTATION_FRAMEWORK│ ┌──────────────────────────────┐ │
│ literature/ ├──→ │ /dissertation-planner │ │
│ writing-sample.md │ │ Creates chapter plan │ │
│ prd.json ─────────────┘ └──────────────┬───────────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ methodology │ │ literature │ │ theory │ │
│ │ expert │ │ expert │ │ expert │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ evidence │ │ formatting │ │ (domain) │ │
│ │ expert │ │ expert │ │ experts │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └─────────────────┼─────────────────┘ │
│ ▼ │
│ ┌──────────────────────────┐ │
│ │ /dissertation-writer- │ │
│ │ author │ │
│ │ Synthesizes & unifies │ │
│ └────────────┬─────────────┘ │
│ ▼ │
│ ┌──────────────────────────┐ │
│ │ /dissertation-critic │ │
│ │ Reviews scholarly rigor │ │
│ └────────────┬─────────────┘ │
│ ▼ │
│ chapters/ch-[ID]-*.md │
│ │
└─────────────────────────────────────────────────────────────────┘
The source-material/ directory contains your primary content—existing drafts, PDFs, notes. Ralph's job is to synthesize and organize this content, not generate from scratch.
source-material/= PRIMARY CONTENT (what you've already written)writing-sample.md= VOICE GUIDE ONLY (how you write, not what)
1. Add your source material:
cp ~/dissertation-draft.pdf stories/my-diss/source-material/
cp ~/chapter-notes.md stories/my-diss/source-material/2. Fill out DISSERTATION_FRAMEWORK.md:
- Thesis statement
- Theoretical framework
- Methodology
- Chapter structure
- Voice characteristics
3. Document key sources in literature/:
# Doležel - Heterocosmica
## Summary
Adapts possible worlds theory to fiction.
## How I Use It
I extend his concept of "texture" to argue that AI systems
threaten productive incompleteness.
## Key Quotes
> "Fictional worlds are necessarily incomplete" (1998, 169)4. Define chapters in prd.json:
{
"mode": "dissertation",
"chapters": [
{
"id": "CH-001",
"title": "Introduction",
"acceptanceCriteria": [
"Chapter is 4000-6000 words",
"Core argument: [claim]",
"Engages with: [scholars]",
"Connects to thesis"
],
"passes": false
}
]
}Generic Expert Writers (for any dissertation):
| Skill | Purpose |
|---|---|
/dissertation-planner |
Plan argument structure and literature engagement |
/dissertation-writer-methodology |
Research design, methods, analytical approach |
/dissertation-writer-literature |
Scholarly sources, field positioning |
/dissertation-writer-theory |
Theoretical frameworks, conceptual analysis |
/dissertation-writer-evidence |
Case studies, primary sources, examples |
/dissertation-writer-formatting |
Structure, citations, transitions |
/dissertation-writer-author |
Synthesize expert contributions, maintain voice |
/dissertation-critic |
Review argument validity and scholarly rigor |
Domain-Specific Expert Writers (optional, for specialized topics):
| Skill | Purpose |
|---|---|
/dissertation-writer-ai |
AI/ML/prediction expertise |
/dissertation-writer-worldbuilding |
Narrative design expertise |
/dissertation-writer-newmedia |
Digital art/practice expertise |
The critic saves feedback to reviews/ch-[ID]-review.md. On subsequent iterations, all writers read this feedback and address the issues before the chapter can pass.
| Command | Description |
|---|---|
./scripts/init-story.sh [name] |
Create a fiction project |
./scripts/init-dissertation.sh [name] |
Create a dissertation project |
./scripts/ralph.sh <project> [iterations] |
Write chapters |
./scripts/list-stories.sh |
Show all projects and status |
TOOL=amp ./scripts/ralph.sh <project> |
Use Amp instead of Claude |
Review each chapter before Ralph continues:
{
"ralph_settings": {
"interactive_mode": true
}
}{
"ralph_settings": {
"citation_style": "chicago-author-date"
}
}Options: chicago-author-date, chicago-notes, mla, apa
| Good | Too Big |
|---|---|
| "Hero meets mentor, begins training" | "Hero completes all training" |
| "Detective interviews first suspect" | "Detective solves entire case" |
Rule: If you can't summarize it in 2-3 sentences, split it.
| Good | Bad |
|---|---|
| "2500-3500 words" | "good length" |
| "Hero fails first magic attempt" | "Hero learns magic" |
| "Ends with villain arriving" | "Ends with tension" |
Ralph works best when you provide existing content to synthesize. The more material in source-material/, the better the output matches your actual research.
./scripts/init-story.sh your-story-name
# or
./scripts/init-dissertation.sh your-dissertation-nameCheck the review:
cat stories/your-project/reviews/ch-001-review.mdCommon fixes:
- Loosen acceptance criteria
- Add guidance to progress.txt
- Update framework with missing details
Add more content to source-material/. Ralph should be synthesizing your existing work, not generating from scratch.
Q: How much does it cost? A: Fiction: ~$15-40 for a 25-chapter novel in high-quality with full review processes. Dissertations vary based on complexity.
Q: Can I edit chapters manually?
A: Yes. Edit files in chapters/, then continue with Ralph.
Q: Can I use existing writing?
A: Yes! For dissertations, put your drafts in source-material/. For fiction, use writing-sample.md for style matching.
Q: What if I change direction mid-project? A: Update prd.json and your framework file, then continue. Ralph adapts.
Q: What's the difference between domain-specific and generic expert writers? A: Generic experts (methodology, literature, theory, evidence) work for any dissertation. Domain experts (ai, worldbuilding, newmedia) add specialized knowledge for specific topics.
- Ralph pattern: snarktank/ralph
- Ralph concept: Geoffrey Huntley
- Powered by: Claude Code
Happy writing!