woke_novel

English | 简体中文

Fully automated long-form novel generation workflow for Claude CLI or Codex CLI.

██╗    ██╗ ██████╗ ██╗  ██╗███████╗    ███╗   ██╗ ██████╗ ██╗   ██╗███████╗██╗
██║    ██║██╔═══██╗██║ ██╔╝██╔════╝    ████╗  ██║██╔═══██╗██║   ██║██╔════╝██║
██║ █╗ ██║██║   ██║█████╔╝ █████╗      ██╔██╗ ██║██║   ██║██║   ██║█████╗  ██║
██║███╗██║██║   ██║██╔═██╗ ██╔══╝      ██║╚██╗██║██║   ██║╚██╗ ██╔╝██╔══╝  ██║
╚███╔███╔╝╚██████╔╝██║  ██╗███████╗    ██║ ╚████║╚██████╔╝ ╚████╔╝ ███████╗███████╗
╚══╝╚══╝  ╚═════╝ ╚═╝  ╚═╝╚══════╝    ╚═╝  ╚═══╝ ╚═════╝   ╚═══╝  ╚══════╝╚══════╝

Turn Claude / Codex into Your "Automated Chinese Web Novel Generator"

Pipeline · Multi-Act · Resume from Breakpoint · Strict Template-Driven

woke_novel turns an external model CLI into a structured Chinese web-novel writing pipeline. The tool does not write prose by itself. Instead, it feeds the hard-constrained Markdown templates in steps/ to Claude or Codex, asks the model to create each artifact, and writes the outputs into projects/<novel_name>/.

The workflow is designed for resumable, template-driven generation of a roughly 30-chapter Chinese web novel, from idea selection through worldbuilding, characters, story arc, chapter drafts, state tracking, and act summaries.

Screenshots

Features

• Claude CLI and Codex CLI support: choose either backend from the interactive menu or pass --provider claude/codex on the command line.
• Template-driven pipeline: 20 workflow templates plus shared writing rules under steps/.
• Resumable execution: progress is stored in projects/<name>/.project_info.json; continue resumes from the recorded cursor.
• Multi-session orchestration: workflow phases are split into separate CLI sessions to keep context boundaries manageable.
• Dry-run mode: use --dry to verify pipeline wiring without calling an external model CLI.
• Project-local artifacts: generated files are organized under 00_baseline, 01_plots, 02_guides, 02_output, 03_state, and 04_characters.

Requirements

• Python 3.10+
• At least one supported model CLI installed and authenticated:
  • claude / claude.cmd
  • codex / codex.cmd
• Git, optional but recommended

Install Python dependencies:

pip install -r requirements.txt

Current Python dependencies are:

• colorama
• rich

Quick Start

Clone the repository:

git clone https://github.com/keyboardgdy/woke_novel.git
cd woke_novel

Verify your model CLI:

claude --version
codex --version

Start the interactive menu:

python menu.py

Platform launchers are also included:

menu.bat       # Windows
./menu.sh      # Linux / macOS
./menu.command # macOS

The first run asks you to choose a backend, then guides you through genre selection, project naming, optional user description, idea selection, and full workflow execution.

Visual Console

The project also includes a local web console for managing projects, running/resuming workflows, reading chapters, editing chapter text, viewing logs, and exporting MD/TXT/EPUB.

Build the frontend once:

cd frontend
npm install
npm run build
cd ..

Start the console:

python -m app_server.main

Then open:

http://127.0.0.1:8787

On Windows, woke.bat can start the backend quietly and open the browser:

woke

If you want woke to work from any terminal, add the repository root to your user PATH.

Command Line Usage

python run_workflow.py <command> [args]

Available commands:

Examples:

# Dry-run a single step after editing its template
python run_workflow.py single 11 -p my_novel -g fantasy --dry

# Run one step for real
python run_workflow.py single 11 -p my_novel -g fantasy

# Use Codex CLI as the backend
python run_workflow.py single 11 -p my_novel -g fantasy --provider codex

# Run the full workflow
python run_workflow.py loop --project-name my_novel --genre fantasy --option-count 3

# Continue after interruption
python run_workflow.py continue --project-name my_novel

Backend Behavior

Each workflow step sends a resolved prompt to the selected external CLI process and expects the model to write artifacts into the project directory.

Current backend invocation behavior:

Use this project only inside a local workspace you trust. If you want a more conservative Codex setup, adjust the Codex arguments in workflow_runner.py to use a workspace sandbox policy that fits your environment.

Workflow Overview

The full workflow is organized into these major phases:

The runner extracts act counts and chapter counts from generated framework files, then loops through the remaining chapters accordingly. For the first act, the opening chapter is created before the normal chapter loop.

Project Layout

woke_novel/
├── cli.py
├── menu.py
├── run_workflow.py
├── ui.py
├── workflow_runner.py
├── path_resolver.py
├── project_info.py
├── project_structure.py
├── steps/
├── docs/
├── logs/
└── projects/
    └── <novel_name>/
        ├── .project_info.json
        ├── CLAUDE.md
        ├── 00_baseline/
        ├── 01_plots/
        ├── 02_guides/
        ├── 02_output/
        ├── 03_state/
        └── 04_characters/

Main modules:

Template Variables

PathResolver.resolve() replaces variables used in the Markdown templates. Common variables include:

Avoid hard-coding absolute paths in templates. When changing artifact paths, update both the template and the resolver mapping.

Resume Metadata

Progress is stored in projects/<name>/.project_info.json. A typical file contains:

{
  "novel_name": "<final title>",
  "genre": "fantasy",
  "last_step": "14",
  "current_round": 7,
  "selected_option": 2,
  "ref_works": ["Reference A", "Reference B"],
  "act_count": 3,
  "chapter_counts": [12, 10, 8],
  "total_chapters": 30
}

Use continue after Ctrl+C, a failed CLI call, or a machine restart.

Development Notes

• Use --dry before running expensive model calls.
• After editing a step template, validate it with single <step> --dry.
• If you add a workflow step, update the step maps in workflow_runner.py and the orchestration logic in run_workflow.py.
• The repository-level CLAUDE.md describes this tool. The generated projects/<name>/CLAUDE.md is an output artifact for future continuation and should not be confused with the repository guide.

License

MIT. See LICENSE.