DOCSEARCHbyAlgolia
Submit Docs

StoryCraftr

repository·main·Indexed 40 days ago

https://github.com/raestrada/storycraftr

An AI-powered book creation assistant featuring a CLI and VS Code extension for worldbuilding, outlining, and chapter generation. It leverages LangChain to support LLM providers including OpenAI, OpenRouter, and Ollama. Version 0.12.0-beta1 includes tools for iterative content refinement, sub-agent background jobs for heavy operations, and a retrieval system to synchronize local markdown content.

Tokens
18.3K
Snippets
78
Records
96
Agent score
73%

What's inside StoryCraftr

  1. Manage Background Sub-agents

    main

    The storycraftr init command scaffolds a .storycraftr/subagents/ directory containing YAML files for roles like editor, continuity, worldbuilding, and marketing. Each agent has a slug, a command_whitelist, and a system_prompt.

    • Regenerate Defaults: Use storycraftr sub-agents seed --language <locale> --force to reset agent files (e.g., --language en).
    • Logs: Agent logs are stored in .storycraftr/subagents/logs/<role>/<timestamp>.md.
    • VS Code Integration: If running in a VS Code terminal, structured events are streamed to .storycraftr/vscode-events.jsonl for editor-side mirroring.
    storycraftr sub-agents seed --language en --force

  2. Run long-running tasks with Sub-Agent background jobs

    main

    For heavy operations like full chapter rewrites or large outline generations, use the :sub-agent prefix. This runs the command in the background using role-specific prompts located in .storycraftr/subagents/.

    Key Sub-Agent Commands:

    • :sub-agent !list: Inspect available roles and their whitelisted commands.
    • :sub-agent !describe <role>: Get details about a specific role (e.g., editor).
    • :sub-agent !<command> <args>: Queue a command. You can specify a role (e.g., :sub-agent !outline editor ...) or let StoryCraftr auto-select a role.
    • :sub-agent !status: Monitor background work.
    • :sub-agent !logs <role>: Inspect logs for a specific role.
    • :sub-agent !seed --language <lang> --force: Reseed role YAML files (useful after changing languages).
    :sub-agent !list
:sub-agent !describe editor
:sub-agent !outline editor general-outline "Tighten the pacing for Act II"
:sub-agent !chapters chapter 5 "Reframe the midpoint twist"
:sub-agent !status
:sub-agent !logs continuity
:sub-agent !seed --language es --force

  3. Understand StoryCraftr backup files

    main

    StoryCraftr automatically creates backups of any files it modifies to prevent data loss. Backup files are created in the same directory as the original file and use the .back extension.

    Example: If you modify chapters/chapter_1.md, StoryCraftr will create chapters/chapter_1.md.back before applying changes.

  4. How automatic refinement works in StoryCraftr

    main
    StoryCraftr uses an iterative approach where commands do not simply overwrite files. Instead, every command automatically refines, updates, or adds to existing content. If a file (such as a chapter synopsis) already exists, running a command will modify the existing text to be more detailed or adjusted based on your new input, preserving the established context while enhancing it.

  5. Use a Behavior File to Guide AI Writing

    main

    A behavior file is a creative manifesto that defines the vision, tone, and style of your book. Unlike an outline (structure) or worldbuilding (setting), the behavior file tells the AI how to write (e.g., dark, introspective, fast-paced, or character-driven).

    Common elements to include:

    • Tone & Style: (e.g., 'dark and humorous', 'concise and fast-paced')
    • Character Approach: (e.g., 'focus on emotional arcs', 'action-driven')
    • Narrative Structure: (e.g., 'three-act structure', 'experimental')
    • Themes & Focus: Overarching ideas to maintain consistency.
    echo "Write in a dark, introspective tone focusing on a morally ambiguous protagonist..." > behaviors/default.txt

  6. Configure Provider Credentials

    main

    StoryCraftr supports OpenAI, OpenRouter, and Ollama. Credentials can be provided via environment variables or by placing text files in ~/.storycraftr/.

    OpenAI

    Create a file at ~/.storycraftr/openai_api_key.txt containing your secret key, or set the OPENAI_API_KEY environment variable.

    OpenRouter

    Create a file at ~/.storycraftr/openrouter_api_key.txt containing your secret key, or set the OPENROUTER_API_KEY environment variable. You can also set OPENROUTER_BASE_URL.

    Ollama

    Ollama typically runs locally and does not require a key. Set the OLLAMA_BASE_URL environment variable (defaults to http://localhost:11434).

    # OpenAI
mkdir -p ~/.storycraftr
echo "sk-your-openai-secret" > ~/.storycraftr/openai_api_key.txt

# OpenRouter
echo "or-your-openrouter-secret" > ~/.storycraftr/openrouter_api_key.txt

# Ollama
export OLLAMA_BASE_URL="http://localhost:11434"

  7. Run heavy iterations in the background using sub-agents

    main

    If an !iterate command is expected to take a long time, you can run it using a sub-agent to continue chatting in the main interface.

    Running a Sub-agent Task

    Use the :sub-agent prefix followed by the role name and the command:

    :sub-agent !iterate editor check-consistency "Audit the revenge subplot"

    Managing Sub-agents

    • Monitor Progress: Use :sub-agent !status to watch the current progress of a sub-agent.
    • View Logs: Use :sub-agent !logs <role_name> (e.g., :sub-agent !logs editor) to open the markdown transcript of the run.

    Sub-agent Configuration

    • Roles are defined in the .storycraftr/subagents/ directory. Each role specifies which commands it is permitted to execute.
    • To regenerate or localize role definitions, use:
      storycraftr sub-agents seed --language <code] [--force]

  8. Use the VS Code Event Stream for Chat

    main

    When running storycraftr chat inside a VS Code terminal, the CLI generates a JSONL event feed at .storycraftr/vscode-events.jsonl.

    This allows the storycraftr.storycraftr extension to mirror chat turns, background jobs, and command output directly in the VS Code editor (via the Status Bar and output channels). To disable this stream, simply remove the .storycraftr/vscode-events.jsonl file.

  9. Configure embedding models and devices

    main

    StoryCraftr uses an embedded ChromaDB instance for retrieval, which is stored locally under <book>/vector_store/. Embeddings are handled via HuggingFaceEmbeddings.

    Embedding Configuration

    SettingEnvironment VariableCLI Flag
    ModelSTORYCRAFTR_EMBED_MODEL--embed-model
    DeviceSTORYCRAFTR_EMBED_DEVICE--embed-device
    Cache DirSTORYCRAFTR_EMBED_CACHE--embed-cache-dir

    Default Model: BAAI/bge-large-en-v1.5 (requires ~1.3 GB RAM). Low-resource Fallback: sentence-transformers/all-MiniLM-L6-v2.

    Managing the Vector Store

    If you change your embedding model or chunking parameters, you must rebuild the index. Use the following command to regenerate embeddings:

    storycraftr vector rebuild
    # Example: Using a low-resource embedding model on CPU
export STORYCRAFTR_EMBED_MODEL='sentence-transformers/all-MiniLM-L6-v2'
export STORYCRAFTR_EMBED_DEVICE='cpu'

  10. Install StoryCraftr

    main

    You can install StoryCraftr using pipx to ensure it runs in an isolated virtual environment, or run it directly without installation using uvx.

    To install via pipx:

    pipx install git+https://github.com/raestrada/storycraftr.git@v0.12.0-beta10

    To run without installing via uvx:

    uvx --from git+https://github.com/raestrada/storycraftr.git@v0.12.0-beta10 storycraftr

  11. Use the `iterate` command to refine your book

    main

    The iterate command suite allows you to perform targeted refinements across your book's structure and content.

    Character Management

    • Check and Fix Character Names: Scans all chapters for name consistency and provides fixes or recommendations.
      storycraftr iterate check-names "Check character names for consistency."
    • Fix a Specific Name: Updates a specific character name across the entire book.
      storycraftr iterate fix-name Zevid Rhaedin
    • Refine Character Motivation: Ensures character motivations remain consistent and deep throughout the narrative.
      storycraftr iterate refine-motivation "Rahedin" "Refine its motivations in a story about rebellion against gods."

    Story Structure and Plot

    • Strengthen Story Argument: Reiterates and strengthens the core theme or argument across the book.
      storycraftr iterate strengthen-argument "Ensure the argument of rebellion against divine control is clear."
    • Insert Chapters: Inserts a new chapter at a specific position and automatically adjusts the numbering of all subsequent chapters.
      storycraftr iterate insert-chapter 2 "Insert a new chapter that explores a critical event..."
    • Split a Chapter: Splits a long chapter into two and adjusts subsequent numbering.
      storycraftr iterate split-chapter 3 "Split chapter into two chapters."
    • Add Flashbacks: Inserts a flashback scene between two chapters.
      storycraftr iterate add-flashback 3 "Insert a flashback revealing a hidden alliance..."
    • Update Plot Points: Refines key plot points to align with recent developments.
      storycraftr iterate update-plot-points "Refine the plot points around the rebellion’s climax."

    Global Consistency

    • Consistency Check: Reviews the entire structure (character arcs, motivations, plot points, worldbuilding) for alignment.
      storycraftr iterate check-consistency "Ensure consistency of character arcs and motivations throughout the story."