ia-writer-annotations

iA Writer Annotations Plugin for Claude Code

⚠️ Terminal Version Only: This plugin currently only works with the terminal version of Claude Code. The VSCode extension does not support PostToolUse hooks that modify files.

Automatically add authorship annotations to your text files when Claude Code edits them, using the iA Writer Markdown Annotations open format.

Overview

This plugin tracks Claude's contributions to your markdown and text files by automatically appending authorship metadata at the end of files. The annotations are invisible in iA Writer's editor but can be viewed in other text editors, and help you distinguish between human-written and AI-generated content.

Features

🤖 Automatic Annotation

• Automatically annotates files when Claude Code uses Write or Edit tools
• Tracks character ranges of Claude's contributions
• Validates annotations with SHA-256 hash
• Works seamlessly in the background - no manual intervention required

⚙️ Configurable

• Default author name: @Claude
• Customizable to use @AI, @Bot, or any other author name
• Per-project or global configuration

📄 File Support

• .md - Markdown files
• .txt - Plain text files
• .text - Text files

Installation

# Add the plugin marketplace
/plugin marketplace add KazukiYunoue/claude-code-ia-writer-annotations

# Install the plugin
/plugin install ia-writer-annotations

# Enable the plugin (if not auto-enabled)
/plugin enable ia-writer-annotations

Configuration

The plugin can be configured via .claude-plugin/plugin.json:

{
  "name": "ia-writer-annotations",
  "version": "1.0.0",
  "config": {
    "authorName": "Claude",
    "authorKind": "Other"
  }
}

Configuration Options

Option	Default	Description
authorName	"Claude"	The author name to use in annotations (e.g., "AI", "Bot")
authorKind	"Other"	The kind of author for iA Writer (either "Human" or "Other")

Usage

Automatic Annotation

Once installed, the plugin works automatically:

1. Edit a markdown or text file using Claude Code
2. The plugin automatically appends annotation metadata to the end of the file
3. Open the file in iA Writer to see visual authorship indicators

Example:

When Claude writes "Hello, world!" at the beginning of a file, the annotation block is automatically added:

Hello, world!

---
Annotations: 0,13 SHA-256 a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447
@Claude: 0,13

Enable/Disable Plugin

Use Claude Code's built-in plugin management:

# Disable when you don't need annotations
/plugin disable ia-writer-annotations

# Re-enable when needed
/plugin enable ia-writer-annotations

iA Writer Setup

To visualize annotations in iA Writer, you need to register the author:

On Mac:

1. Open iA Writer
2. Go to Settings → Authors
3. Click + Add Author
4. Enter:
   • Name: Claude (or your configured authorName)
   • Identifier: noreply@anthropic.com (optional)
   • Kind: Select Other (for AI)
5. Click Add

On iPhone/iPad:

1. Open iA Writer
2. Go to Settings → Authors
3. Tap Add Author…
4. Enter the same information as above
5. Tap Add

Once registered, the author syncs across all your devices via iCloud.

How It Works

Markdown Annotations Format

The plugin uses the Markdown Annotations open format:

[Your text content here]

---
Annotations: start,length SHA-256 hash
@AuthorName: start1,length1 start2,length2 ...

Key features:

• Character ranges: Use grapheme cluster indexes (not byte offsets)
• SHA-256 hash: Validates the integrity of annotated ranges
• Multiple authors: Support for multiple contributors in the same file
• Portable: Plain text format that works across editors

PostToolUse Hook

The plugin registers a PostToolUse hook that triggers when Claude Code edits files:

1. Detects Write or Edit tool usage on .md, .txt, or .text files
2. Calculates character ranges for Claude's changes
3. Parses existing annotations (if any)
4. Merges new annotations with existing ones
5. Recalculates SHA-256 hash
6. Appends/updates annotation block at end of file

Character Range Calculation

The plugin uses JavaScript's Intl.Segmenter API to correctly count grapheme clusters, ensuring proper handling of:

• Emoji (e.g., 👍 counts as 1, not 2 or 4)
• Combined characters (e.g., é as single character)
• Surrogate pairs (e.g., 𝕳𝖊𝖑𝖑𝖔)

This ensures annotations remain valid across different environments and text encodings.

Limitations

Platform Compatibility

Terminal Version Only