BookGenAI - AI Book Writing Assistant

An intelligent command-line interface for creative writing powered by multiple AI models through OpenRouter. BookGenAI ("Libro") helps authors plan, structure, and write complete books with specialized tools for outlining, character development, world-building, and content generation.

Overview

BookGenAI transforms the book writing process by providing an interactive console environment where authors can collaborate with AI to create compelling narratives. Inspired by development tools like Claude Code and Cursor AI, but focused entirely on creative writing workflows.

Key Features

🎯 Interactive Writing Tools

• Story outline generation and management
• Character profile creation and development
• Setting and world-building assistance
• Chapter drafting with context awareness
• Text editing and refinement suggestions

🤖 Multi-Model AI Integration

• OpenRouter API integration for model flexibility
• Support for Claude, GPT-4, and other leading models
• Per-tool model configuration for optimal results
• Cost optimization with model-specific assignments

📚 Professional Document Export

• DOCX export with proper heading structure
• Seamless integration with Google Docs, MS Word, Pages
• Multiple format support (Markdown, HTML, Plain Text)
• Automatic table of contents generation

🎨 Rich Console Interface

• Colored output with professional styling
• Interactive menus and guided workflows
• Progress indicators for long operations
• Formatted tables and structured displays

🔧 Extensible Architecture

• Modular tool system for easy expansion
• Plugin-ready design for custom tools
• Project-based organization with persistence
• Global installation for system-wide access

Quick Start

Installation

From npm (Public)

# Install globally from npm
npm install -g @bramatom/bookgenai

# Verify installation
bookgenai --version
libro --version  # Italian alias

From Source

# Clone the repository
git clone https://github.com/bramatom/bookgenai.git
cd bookgenai

# Install dependencies and build
npm install
npm run build

# Link globally for development
npm link

Both methods provide access to the Italian alias libro.

First Steps

# Initialize a new book project
bookgenai init

# Or use the Italian command
libro inizia

# Follow the interactive setup to configure your book

Basic Workflow

1. Project Setup: Create a new book project with metadata
2. Outline Creation: Generate or define your story structure
3. Character Development: Create detailed character profiles
4. World Building: Define settings and locations
5. Content Generation: Write chapters using AI assistance
6. Export: Compile your book into professional formats

Commands

Core Commands

bookgenai init                    # Initialize new book project
bookgenai outline                 # Create or update story outline
bookgenai character create <name> # Create character profiles with AI
bookgenai character list          # Show all characters with formatting
bookgenai character relationships # Generate character relationship maps
bookgenai character arc [name]    # Create character development arcs
bookgenai setting <location>      # Define locations and world-building
bookgenai write chapter <n>       # Generate chapter content
bookgenai edit chapter <n>        # Refine existing chapters
bookgenai export [format]         # Export completed manuscript

Italian Commands (Aliases)

libro inizia                      # Initialize project
libro scaletta                   # Story outline
libro personaggio create <nome>   # Character creation with AI
libro personaggio list           # Show all characters
libro personaggio relationships  # Character relationship maps
libro personaggio arc [nome]     # Character development arcs
libro ambientazione <luogo>       # Setting definition
libro scrivi capitolo <n>        # Write chapter
libro modifica capitolo <n>      # Edit chapter
libro esporta [formato]           # Export manuscript

Configuration

BookGenAI features a comprehensive configuration system with interactive setup wizard, dynamic model selection from OpenRouter, and full Italian localization.

📖 Complete Configuration System Documentation

bookgenai config setup            # Interactive configuration wizard (recommended)
bookgenai config show             # Display current configuration
bookgenai config models           # Show available AI models
bookgenai config validate         # Test configuration and API connectivity
bookgenai config set <key> <value> # Set specific configuration value
bookgenai config get <key>        # Get specific configuration value
bookgenai config reset            # Reset to defaults

# Italian commands
libro configurazione configura    # Wizard di configurazione
libro configurazione mostra       # Mostra configurazione
libro configurazione modelli      # Mostra modelli disponibili

Project Structure

When you initialize a project, BookGenAI creates this structure:

my-book/
├── project.json              # Book metadata and configuration
├── outline.yaml              # Story structure and chapter planning
├── characters/               # Character profile files (YAML)
│   ├── elena-rossi.yaml
│   ├── marco-bianchi.yaml
│   └── sofia-neri.yaml
├── settings/                 # Location and world-building
│   ├── main-location.json
│   └── secondary-places.json
├── chapters/                 # Individual chapter files
│   ├── 01-opening.md
│   ├── 02-inciting-incident.md
│   └── ...
├── exports/                  # Generated documents
│   ├── my-book.docx
│   └── my-book.md
└── .bookgenairc             # Local project preferences

Writing Tools

Outline Tool

Creates structured story outlines with:

• Chapter-by-chapter breakdowns
• Plot point identification
• Pacing and structure analysis
• Character arc integration

📖 Complete Outline Command Documentation

Character Tool

Develops rich character profiles including:

• Personality traits and motivations
• Background and history
• Character relationships
• Growth arcs and development
• Dialogue voice and style

📖 Complete Character Management Documentation

Setting Tool

Builds immersive world details:

• Location descriptions
• Cultural and social contexts
• Historical backgrounds
• Visual and sensory details
• Consistency tracking

Draft Writer

Generates chapter content with:

• Context awareness from outline and characters
• Style consistency maintenance
• Proper narrative structure
• Scene description and dialogue
• Chapter flow and transitions

Editor Tool

Refines and improves text through:

• Grammar and style checking
• Consistency analysis
• Tone and voice alignment
• Structure and pacing suggestions
• Character voice maintenance

AI Model Configuration

BookGenAI features a comprehensive AI integration system powered by OpenRouter, providing access to multiple state-of-the-art models with intelligent optimization for different writing tasks.

📖 Complete AI Integration Documentation

Default Model Setup

# Set your preferred default model
bookgenai config model claude-3-opus

# Configure OpenRouter API key
export OPENROUTER_API_KEY="your-api-key-here"

Per-Tool Model Assignment

# Use different models for different tasks
bookgenai config outline-model gpt-4          # Structural work
bookgenai config character-model claude-3     # Character development  
bookgenai config writing-model claude-3-opus  # Creative writing
bookgenai config editing-model gpt-4          # Text refinement

Enterprise Features

• Automatic Rate Limiting: Built-in request queuing and throttling
• Response Caching: Intelligent caching with TTL for improved performance
• Usage Analytics: Detailed tracking of tokens, costs, and performance
• Error Recovery: Automatic retry with exponential backoff
• Health Monitoring: Connection testing and service status tracking

Cost Optimization

• Use faster/cheaper models for outlining and editing
• Reserve premium models for creative content generation
• Monitor token usage with built-in tracking
• Automatic model fallback for availability
• Smart caching reduces duplicate API calls

Export Options

BookGenAI features a comprehensive multi-format export system designed for professional publishing workflows.

📖 Complete Export System Documentation

DOCX Export (Professional)

• Advanced typographic formatting with Times New Roman
• Structured headings (Chapter titles as Heading 1, sections as Heading 2)
• Automatic table of contents with page numbers
• Professional title page with metadata
• Character and setting appendices
• Page breaks and proper document structure
• Compatible with MS Word, Google Docs, Apple Pages

HTML Export (Interactive)

• Responsive web design for all devices
• Interactive table of contents with smooth scrolling
• Reading progress indicator
• Multiple themes (Default, Elegant, Modern)
• Print-optimized CSS styles
• Professional typography with web fonts

Markdown Export (Structured)

• YAML front matter with complete metadata
• Clean, standardized markdown formatting
• Character and setting appendices
• Chapter-by-chapter organization
• Perfect for version control and collaboration

Plain Text Export (Universal)

• Elegant ASCII formatting and borders
• Clean text layout with proper spacing
• Chapter separators and structured sections
• Universal compatibility across all systems
• Optimized for printing and simple distribution

Advanced Features

• Selective Export: Choose specific chapters to include
• Appendices Control: Optional character and setting sections
• Custom Output Names: Specify exact file names
• Interactive Mode: Guided configuration with full options
• Batch Processing: Export multiple formats simultaneously
• Progress Tracking: Real-time export progress with spinners

Usage Examples

# Basic exports
bookgenai export                    # Default DOCX format
bookgenai export html              # Interactive HTML
bookgenai export markdown          # Structured Markdown
bookgenai export txt               # Plain text

# Advanced options
bookgenai export docx -o "MyBook.docx" --characters --settings
bookgenai export html --theme elegant --no-toc
bookgenai export markdown --chapters "1,3,5"

# Interactive mode with full configuration
bookgenai export -i

# Italian commands
libro esporta docx
libro esporta html --tema elegante
libro esporta -i

Configuration Files

Global Configuration (~/.bookgenairc.json)

{
  "defaultModel": "claude-3-opus",
  "modelOverrides": {
    "outline": "gpt-4",
    "character": "claude-3",
    "writing": "claude-3-opus",
    "editing": "gpt-4"
  },
  "interface": {
    "theme": "dark",
    "language": "en"
  },
  "export": {
    "defaultFormat": "docx",
    "includeMetadata": true
  }
}

Project Configuration (project.json)

{
  "title": "My Novel",
  "author": "Author Name",
  "genre": "Fantasy",
  "targetLength": 80000,
  "style": {
    "tone": "adventurous",
    "perspective": "third-person",
    "tense": "past"
  },
  "chapters": [],
  "created": "2024-01-01T00:00:00.000Z",
  "modified": "2024-01-01T00:00:00.000Z"
}

Requirements

• Node.js: Version 16 or higher
• OpenRouter Account: For AI model access
• Terminal: Modern terminal with color support
• Storage: Minimum 100MB for projects and dependencies

Development

Prerequisites

• Node.js 18+
• TypeScript
• OpenRouter API access

Setup

git clone https://github.com/yourusername/bookgenai.git
cd bookgenai
npm install
npm run dev

Testing

npm test                    # Run all tests
npm run test:watch         # Watch mode
npm run test:coverage      # Coverage report

Building

npm run build              # Compile TypeScript
npm run package            # Create distribution package

Italian Localization

BookGenAI includes full Italian language support:

• Command aliases in Italian (libro, scaletta, personaggio)
• Italian error messages and help text
• Cultural considerations for creative writing
• Italian literary conventions and style preferences

Enable Italian mode:

bookgenai config language it
# or
libro config lingua it

Examples

Creating a Fantasy Novel

# Initialize project
bookgenai init
> Enter book title: The Dragon's Legacy
> Select genre: Fantasy
> Writing style: Epic/Adventurous

# Create outline
bookgenai outline
> Generating epic fantasy outline with hero's journey structure...

# Develop main character
bookgenai character "Aria Stormwind"
> Role: Protagonist
> Creating brave warrior with mysterious past...

# Define primary setting  
bookgenai setting "Kingdom of Valdris"
> Creating medieval fantasy kingdom with political intrigue...

# Write first chapter
bookgenai write chapter 1
> Writing opening chapter with character introduction...

# Export finished manuscript
bookgenai export
> Generating professional DOCX format...

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

• New writing tools and plugins
• Additional export formats
• UI/UX improvements
• Documentation and tutorials
• Language localizations
• Model integrations

License

MIT License - see LICENSE for details.

Support

• 📚 Documentation: docs.bookgenai.com
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]

Roadmap

Version 1.0 (Current Development)

• Core writing tools implementation
• DOCX export functionality
• Basic OpenRouter integration
• Italian localization

Version 1.1 (Planned)

• PDF export support
• Advanced character relationship mapping
• Plot consistency checking
• Performance optimizations

Version 1.2 (Future)

• Google Docs API integration
• Collaborative writing features
• Advanced style analysis
• Custom tool development framework

Version 2.0 (Vision)

• Visual interface option
• Cloud synchronization
• Multi-language translation
• Publishing platform integration

BookGenAI - Transforming creative writing through intelligent assistance.

"Every great story begins with a single word. Let AI help you find the rest."