# Humanizer Return Modes: The Three Output Formats for AI Text Rewriting

> Explore Humanizer's three return modes: pasted text, file, and embedded. Discover how these output formats control AI text rewriting delivery for your projects.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: deep-dive
- Published: 2026-09-06

---

**Humanizer supports three distinct return modes—pasted text (default), file mode, and embedded mode—that determine how rewritten content is delivered to users or downstream automation systems.**

The blader/humanizer repository is an open-source tool designed to strip AI-generated patterns from text drafts. According to the project's [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) documentation, these three return modes provide flexibility for interactive editing, file-based workflows, and programmatic integration.

## How Return Modes Are Defined in Humanizer

The core definitions for all three output behaviors reside in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) under the section **"How to return the result."** This file establishes the contract between the humanizer engine and its consumers, specifying exactly what payload each mode returns and when to use it.

## The Three Humanizer Return Modes Explained

### 1. Pasted Text Mode (Default)

**Pasted text mode** is the default behavior when no specific output configuration is provided. In this mode, the skill returns the full rewritten draft directly in the chat interface, accompanied by a short list of any remaining AI patterns detected in the text.

This mode is optimized for **interactive use**, allowing human editors to review both the cleaned content and diagnostic information about patterns that may still need manual attention. The implementation is referenced in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) under the heading "Pasted text (default)."

### 2. File Mode

**File mode** activates when the user supplies a filename parameter. Instead of returning the full text in the response, Humanizer writes only the final cleaned-up text to the specified file path. This operation preserves any code blocks, YAML metadata, or links present in the original document. After writing the file, the tool returns a concise summary to the user confirming completion.

This mode is ideal for **scripted workflows and CI pipelines** where the output needs to persist to disk rather than appear in chat logs. The specification appears in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) under "File mode."

### 3. Embedded Mode

**Embedded mode** is designed for **programmatic consumption** by other software agents, such as pull-request bots or commit-message generators. When invoked in this mode, Humanizer returns only the final rewritten text without any surrounding explanations, metadata, or pattern lists.

This minimal payload approach ensures that downstream agents receive clean, predictable input suitable for embedding within larger automated workflows. The configuration for this behavior is documented in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) under "Embedded mode" and is also exemplified in [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml).

## Code Examples for Each Return Mode

The following Python examples demonstrate how to invoke each mode programmatically:

```python

# Pasted Text Mode (Default) - Interactive usage

result = humanizer.rewrite(text)

# Returns: full draft + list of remaining AI patterns

# File Mode - Direct file output

humanizer.rewrite(text, output_file="README.md")

# Writes cleaned text to README.md; prints short summary to stdout

# Embedded Mode - Agent-to-agent communication

final_text = humanizer.rewrite(text, mode="embedded")

# Returns: only the rewritten content, ready for further processing

```

## When to Use Each Return Mode

Choose the appropriate mode based on your integration requirements:

- **Pasted text mode** suits ad-hoc editing sessions where human review of both text and diagnostics is necessary.
- **File mode** works best for batch processing, documentation pipelines, or any scenario requiring persistent file updates.
- **Embedded mode** is essential when Humanizer acts as a sub-component within agent orchestration systems, such as those configured in [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml), where extra formatting would interfere with JSON parsing or subsequent API calls.

## Summary

- **Pasted text (default)** delivers full drafts with pattern analysis for interactive chat-based editing.
- **File mode** writes clean output directly to disk while preserving document structure like code blocks and YAML frontmatter.
- **Embedded mode** provides minimal, explanation-free payloads for consumption by other automated agents.

## Frequently Asked Questions

### What is the default return mode in Humanizer?

The default return mode is **pasted text**, which returns the complete rewritten draft along with a list of any remaining AI patterns detected. This mode requires no additional parameters and is activated automatically when calling `humanizer.rewrite()` without specifying an output file or embedded flag.

### How does File mode preserve document formatting?

When operating in file mode, Humanizer writes **only** the final cleaned-up text to the specified file, explicitly preserving code blocks, YAML metadata, and links present in the original document. This ensures that technical documentation and structured content maintain their integrity during the humanization process.

### When should I use Embedded mode instead of Pasted text?

Use **embedded mode** when integrating Humanizer into automated workflows where another software agent consumes the output, such as pull-request bots or commit-message generators. Unlike pasted text mode, embedded mode returns **only** the rewritten text without diagnostic information, preventing parsing errors in downstream JSON or API processing pipelines.

### Where are the return modes documented in the source code?

The authoritative definitions for all three return modes are located in **[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)** under the section "How to return the result." Additional implementation context and agent configuration examples appear in **[`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml)**, which demonstrates how to invoke specific modes within OpenAI-compatible environments.