gatherbrained 0.3.0

gatherbrained is an AI writing agent
Documentation

Gatherbrained

Gatherbrained is your AI writing companion that helps you systematically improve your manuscripts, one paragraph at a time. Think of it as having a thoughtful editor sitting next to you, ready to dive deep into your writing and offer detailed, actionable feedback whenever you need it.

What Does It Do?

Gatherbrained takes your manuscript and breaks it down paragraph by paragraph, then uses Claude 4 Sonnet to analyze each section according to your specific instructions. Whether you want to fix grammar, improve clarity, check for plot consistency, or work on character development, Gatherbrained processes your text systematically and adds TODO comments right into your document so you know exactly what needs attention.

The tool works in two modes: an interactive terminal interface where you can work with your manuscript in real-time, and a headless CI mode for automated batch processing. Both approaches give you the same thoughtful AI analysis, just delivered in different ways depending on your workflow.

Getting Started

The simplest way to use Gatherbrained is to point it at your manuscript:

gatherbrained --ci "My directive" my-novel.md

This processes your entire manuscript without any interaction and exits when done.

Working in Interactive Mode

Interactive mode removed in 0.3.0. Install 0.2.0 or wait for 0.4.0.

Context Files

If you have a file called GATHERBRAINED.md in your project directory, its contents are automatically included as context for the AI. This is where you can put information about your story, characters, world-building notes, style preferences, or any other context that will help the AI give more relevant feedback.

Using in CI and Automated Workflows

Gatherbrained works great in continuous integration environments. You can set up automated editing passes that run whenever you push changes to your manuscript:

# In your CI script
gatherbrained --ci "Check for consistency with previous chapters" chapter-12.md
gatherbrained --ci "Proofread for publication" final-draft.md

The CI mode processes the entire specified range and exits cleanly, making it perfect for automated workflows.

IT is future work to build a tool that will open a PR with comments stemming from the changes.

Environment Setup

Gatherbrained uses the Anthropic API, so you'll need to set up your API key. The tool respects standard environment variable conventions for API configuration. Make sure you have access to Claude 4.1 Opus, which is what Gatherbrained uses for its analysis.

How the AI Works

Gatherbrained uses a sophisticated prompting approach that gives Claude 4 Opus context about your specific editing needs. The AI is instructed to:

  • Be specific and actionable rather than vague
  • Quote problematic text when giving feedback
  • Only add TODOs for things that actually need work
  • Respect your instructions without trying to "correct" them
  • Provide detailed reasoning for its suggestions

The AI processes one paragraph at a time and adds exactly one TODO per paragraph that needs attention. This keeps the feedback focused and prevents overwhelming you with too many suggestions at once.

File Handling

Gatherbrained is designed to work seamlessly with your existing writing workflow. It watches your manuscript file for changes and automatically reloads when you edit it in another program. The tool preserves your original formatting and file structure, only adding TODO comments where needed.

All file paths support UTF-8, so you can use international characters in your filenames and manuscript content without issues.

Error Handling

When something goes wrong (network issues, API problems, file access errors), Gatherbrained displays clear error messages in the interface. In interactive mode, you can dismiss error messages and continue working. In CI mode, errors cause the program to exit with appropriate status codes for scripting.

Performance and Rate Limits

Gatherbrained processes paragraphs sequentially to respect API rate limits.

Contributing and Development

Gatherbrained is built in Rust using modern async patterns. The codebase follows clean architecture principles with separate concerns for manuscript handling, AI integration, and user interface. The project uses standard Rust tooling (Cargo, Clippy, etc.) and maintains high code quality standards.

The terminal interface is built with ratatui for cross-platform compatibility, and the AI integration uses a custom client for the Anthropic API that handles all the nuances of Claude's capabilities.

Philosophy

Gatherbrained embodies the idea that good editing is systematic, thoughtful, and collaborative. Rather than trying to automate the creative process, it amplifies your editing capabilities by providing consistent, detailed feedback that helps you make your writing stronger. The AI serves as a knowledgeable editing partner, not a replacement for your creative judgment.

Every feature is designed around the core principle that writing improvement happens through iteration and attention to detail. Gatherbrained gives you the tools to systematically work through your manuscript, paragraph by paragraph, with AI assistance that scales to your needs.