If you’re a creator, author, or professional who needs to produce large volumes of written content, you’ve likely faced frustrations like time-consuming brainstorming, difficulty resuming work after interruptions, or disorganized content structure. Enter Kimi Writing Agent—an autonomous writing tool powered by the kimi-k2-thinking model, designed specifically for crafting novels, books, short story collections, and more. In this comprehensive guide, we’ll break down everything you need to know about this tool: its core features, installation process, usage methods, working principles, and pro tips. By the end, you’ll be ready to leverage AI to streamline your writing workflow and bring your creative ideas to life.

What Is Kimi Writing Agent, and What Can It Do?

At its core, Kimi Writing Agent is a “self-thinking writing assistant.” Unlike traditional word processors that passively accept input, it actively plans writing tasks, executes content creation, and adjusts strategies as needed. Whether you’re working on a full-length novel, a series of short stories, or a structured nonfiction book (like a programming guide), this tool can handle the entire process—from brainstorming to final draft—independently.

Core Feature Highlights

Built around the dual pillars of “autonomy” and “efficiency,” Kimi Writing Agent offers a range of powerful capabilities:

  • End-to-End Autonomous Writing: Once you input your writing prompt, the agent independently breaks down the task (e.g., chapter division, theme development), organizes content, and executes the writing process—no need for step-by-step guidance.
  • Multi-Format Support: It excels at creating novels, books, and short story collections. You can specify the exact format you need based on your project goals.
  • Real-Time Streaming of Creation: You can watch the agent’s “thought process” (e.g., “Next, I’ll develop the protagonist’s backstory”) and content output in real time. Words appear character by character, as if you’re observing a writer work through ideas and draft simultaneously.
  • Intelligent Context Management: For long-form writing, content can quickly accumulate and exceed the model’s processing limits. The agent automatically compresses non-essential context to ensure uninterrupted creation.
  • Resume Interrupted Work: If your writing session is cut short (e.g., computer shutdown, accidental closure), the agent saves a “context summary” that lets you pick up right where you left off—no need to start over.
  • Real-Time Token Monitoring: It displays current token usage (tokens are the basic unit of text processing for AI models), helping you avoid hitting the model’s capacity limits.
  • Built-In Toolset: The agent can create project folders, write files in three modes (create, append, overwrite), and manage your writing workspace—keeping your content organized automatically.

How to Install Kimi Writing Agent?

Installing Kimi Writing Agent is straightforward, even for users with limited programming experience. The process involves setting up a basic environment, installing dependencies, and configuring your API key. Let’s walk through it step by step.

Prerequisites

We recommend using uv—a fast Python package manager—to install dependencies. If you don’t have uv installed, run the following command first:

curl -LsSf https://astral.sh/uv/install.sh | sh

If you prefer not to use uv, you can use the standard pip package manager, though uv offers significantly faster installation speeds.

Step-by-Step Installation

1. Install Dependencies

First, download the tool’s code (typically from the GitHub repository). Navigate to the folder containing the code in your terminal, then run one of the following commands to install the required Python libraries:

Using uv (Recommended):

uv pip install -r requirements.txt

Using pip:

pip install -r requirements.txt

This command will automatically install all the Python packages the tool needs to run. Wait for the installation to complete—this may take a few minutes depending on your internet speed.

2. Configure Your API Key

Kimi Writing Agent relies on the Moonshot AI API to function, so you’ll need to configure your API key. Follow these steps:

  • Locate the env.example file in the tool’s root directory. Copy this file and rename the copy .env:

    cp env.example .env

  • Open the .env file with a text editor. You’ll see a line that reads MOONSHOT_API_KEY=your-api-key-here. Replace your-api-key-here with your actual Moonshot API key.

    To obtain your API key, visit the Moonshot AI Platform, sign up or log in, and navigate to the “API Keys” section in your account settings to generate a key.

  • (Optional) If you need to use a custom API base URL (the default is https://api.moonshot.ai/v1), add the following line to your .env file:

    MOONSHOT_BASE_URL=your-custom-url-here

Once you’ve completed these steps, the installation is fully set up, and you’re ready to start using the tool.

How to Use Kimi Writing Agent for Writing?

After installation, you can start creating content with two primary methods: starting a new project from scratch or resuming a previously interrupted task.

Method 1: Start a New Project

For new writing tasks, you can launch the tool directly and input your prompt in one of two ways:

1. Input the Prompt Directly in the Command Line

For example, if you want the agent to create a collection of 5 sci-fi short stories about AI, run the following command:

Using uv:

uv run kimi-writer.py "Create a collection of 5 sci-fi short stories about AI"

Using Python:

python kimi-writer.py "Create a collection of 5 sci-fi short stories about AI"

You can use Chinese prompts as well, such as “Write a 10-chapter mystery novel set in Victorian London.”

2. Input the Prompt Interactively

If your prompt is long or complex, you can launch the tool first and then enter your request:

uv run kimi-writer.py  # Or python kimi-writer.py

After running the command, the tool will prompt you to enter your writing request. Type your prompt and press Enter to start the creation process.

Method 2: Resume Interrupted Work (Recovery Mode)

If your writing session is interrupted unexpectedly (e.g., pressing Ctrl+C, computer crash), don’t worry—the agent automatically saves a “context summary” that includes your previous progress and thought process. To resume, use the --recover flag followed by the path to the latest context summary file:

uv run kimi-writer.py --recover output/your-project-name/.context_summary_timestamp.md

Example:

uv run kimi-writer.py --recover output/my_sci_fi_stories/.context_summary_20250107_143022.md

The “timestamp” in the filename indicates when the summary was saved—always use the most recent file to resume your work accurately.

How Does Kimi Writing Agent Work?

Understanding the tool’s underlying mechanics will help you use it more effectively. Think of Kimi Writing Agent as a “virtual writer” with its own set of tools and a structured workflow.

What Tools Does It Have?

The agent relies on three core tools to complete writing tasks:

  1. create_project: Creates a dedicated project folder to organize your writing. For example, if you’re writing a novel, it will generate a folder named after your project and store all chapters, summaries, and related files in one place—eliminating clutter.

  2. write_file: Handles file creation and editing with three modes:

    • create: Generates a new file (fails if the file already exists to prevent overwriting).
    • append: Adds content to the end of an existing file (e.g., extending a chapter with new scenes).
    • overwrite: Replaces the entire content of an existing file (e.g., rewriting a chapter from scratch).

  3. compress_context: Manages context size. When the content approaches the model’s token limit, this tool automatically compresses non-essential information (e.g., merging redundant details, simplifying descriptions) to ensure the writing process continues without interruption.

What Is Its Workflow?

The agent follows a cyclic 5-step process to complete writing tasks, repeating until the project is finished:

  1. Receive the Task: The agent processes your writing prompt (e.g., “Write a 10-chapter mystery novel”).
  2. Plan and Reason: Using the kimi-k2-thinking model, it analyzes the task and develops a plan—for example, “First, define the protagonist’s identity, then design the murder case for Chapter 1.”
  3. Select and Execute Tools: Based on the plan, it calls the appropriate tools (e.g., create_project to make a folder, write_file to draft Chapter 1).
  4. Review Results: After completing a segment of writing, it checks if the content aligns with the task requirements and adjusts the plan if needed.
  5. Repeat the Cycle: The process continues until the entire project is finished, with a maximum of 300 iterations to prevent infinite loops.

How Does It Manage Context?

For long-form writing, previous content (context) influences subsequent创作—for example, ensuring consistent character personalities or plot continuity. However, AI models have limits on how much context they can process (token limits). To address this, the agent includes the following features:

  • Token Limit: Supports up to 200,000 tokens (roughly equivalent to 100,000–150,000 words of English text).
  • Auto-Compression Trigger: When content reaches 180,000 tokens (90% of the limit), context compression is activated automatically.
  • Automatic Backups: Saves a context summary every 50 iterations, ensuring you never lose progress.
  • Recovery Mechanism: All summaries are timestamped, making it easy to find and use the latest version to resume work.

What Is the File Structure of Kimi Writing Agent?

Understanding the tool’s file structure will help you manage your projects effectively. The code and generated content are stored separately, with a clear, organized layout:

kimi-writer/  # Tool code folder
├── kimi-writer.py        # Main program (launch the tool by running this file)
├── tools/                # Toolset folder
│   ├── __init__.py       # Tool registration file
│   ├── writer.py         # File-writing tool
│   ├── project.py        # Project management tool
│   └── compression.py    # Context compression tool
├── utils.py              # Auxiliary functions (e.g., token counting)
├── requirements.txt      # List of dependencies
├── env.example           # API key configuration example
├── .gitignore            # Git ignore rules (specifies files not to upload)
└── README.md             # Documentation (this file)

# Automatically generated content during writing
output/                   # All writing projects are stored here
├── your-project-name/    # e.g., "victorian_mystery_novel"
│   ├── chapter_01.md     # Chapter 1 content
│   ├── chapter_02.md     # Chapter 2 content
│   └── .context_summary_20250107_143022.md  # Timestamped context summary
└── another-project/      # Folder for additional writing tasks
    └── ...

In short, the kimi-writer folder contains the tool itself—you don’t need to modify any files here. The output folder is your “work library,” where all your completed content and project files are stored.

What Are Some Common Usage Examples?

Kimi Writing Agent is versatile and suitable for a wide range of writing tasks. Here are three typical examples to inspire your own prompts:

Example 1: Write a Novel

uv run kimi-writer.py "Write a mystery novel set in Victorian London with 10 chapters"

Example 2: Create a Short Story Collection

uv run kimi-writer.py "Create 7 interconnected sci-fi short stories exploring the theme of memory"

Example 3: Compose a Nonfiction Guide

uv run kimi-writer.py "Write a comprehensive guide to Python programming with 15 chapters"

These examples share a key trait: specificity. They clearly define the format (novel/short stories/guide), quantity (10 chapters/7 stories/15 chapters), and theme/setting—providing the agent with the clarity it needs to produce high-quality results.

Advanced Features: Make Writing More Transparent and Controllable

Beyond basic writing capabilities, Kimi Writing Agent offers several advanced features that give you greater visibility and control over the创作 process.

Real-Time Streaming

You can monitor two key streams in real time:

  • Reasoning Stream: The agent’s “thoughts” as it plans and writes—for example, “Introduce the antagonist in the next chapter” or “This scene should tie back to Chapter 3.”
  • Content Stream: The text appears character by character, letting you watch the content unfold as if you’re typing alongside the agent.
  • Tool Call Progress: For long-form content, the agent displays the number of characters/words written, so you always know how much progress has been made.

No more waiting for the entire draft to be completed—you can spot issues or adjust direction mid-process.

Iteration Counter

The agent displays “Iteration X/300” (Xth iteration out of 300 total), letting you track where you are in the创作 cycle. The 300-iteration limit is more than enough for most medium-length projects, ensuring the tool doesn’t run indefinitely.

Token Monitoring

Real-time token usage is displayed in the format: “Current tokens: 45,234/200,000 (22.6%)”. This means “45,234 tokens used out of a 200,000-token limit (22.6% utilization)”. When usage approaches 90%, context compression is triggered automatically—no manual intervention required.

Graceful Interruption

If you need to pause writing, press Ctrl+C to interrupt the agent. It will automatically save the current context summary, allowing you to resume work later using the --recover flag. No progress is lost.

Pro Tips: How to Get the Best Results from Kimi Writing Agent?

While the agent can write autonomously, the quality of your prompt directly impacts the outcome. Here are four pro tips to help you maximize the tool’s potential:

  1. Be Specific with Your Prompt: Vague prompts lead to vague results.

    • Good prompt: “Write a 3-chapter fantasy short story about a talking fox, set in a winter forest, with the theme of ‘friendship’.”
    • Less effective prompt: “Write something interesting.”

  2. Give the Agent Space to Work: The agent is designed to plan and execute tasks independently. For example, if you ask it to write a 10-chapter novel, it will decide chapter length, plot progression, and character development on its own—no need for constant oversight.

  3. Leverage the Recovery Feature: If the content drifts off-topic, interrupt the agent (Ctrl+C), then resume using the --recover flag with a modified prompt. For example: “Continue writing the novel, but change the antagonist’s motivation to revenge.”

  4. Check Files in Real Time: Generated files are saved to the output/your-project-name/ folder in real time. Open these files periodically to review progress and make adjustments if needed.

Frequently Asked Questions (FAQ)

Here are answers to some of the most common questions users have about Kimi Writing Agent:

1. I’m getting the error “MOONSHOT_API_KEY environment variable not set”—what should I do?

This error occurs because your API key isn’t configured properly. Solution:

  • Ensure there’s a .env file in the tool’s root directory.
  • Open the .env file and verify it contains the line MOONSHOT_API_KEY=your-actual-key (no extra spaces or typos).

2. I’m seeing a “401 Unauthorized” or authentication error—how can I fix this?

Authentication errors typically stem from incorrect API key or base URL settings. Solutions:

  • Double-check that your API key in the .env file is correct (no missing characters or extra spaces).
  • Confirm the MOONSHOT_BASE_URL is set to https://api.moonshot.ai/v1 (the default).
  • Verify your API key is valid by logging into the Moonshot AI Platform—ensure it hasn’t expired or been disabled.

3. The tool shows “Error creating project folder”—what’s wrong?

This error indicates the tool doesn’t have permission to create folders in the current directory. Solutions:

  • Check if the folder you’re running the tool from allows write access (e.g., folders like “Program Files” on Windows may restrict permissions).
  • Move the tool folder to a location with write access (e.g., your Desktop or Documents folder) and try again.

4. The agent seems stuck and isn’t producing content—what should I do?

It’s normal for complex tasks to take time— the agent can run up to 300 iterations. Solutions:

  • Check the output/your-project-name/ folder for new files—if files are being generated, the agent is working.
  • Review the reasoning stream to see if the agent is planning its next steps (it may be “thinking” rather than writing).
  • If no progress is made after 30 minutes, press Ctrl+C to interrupt, then resume using the latest context summary.

5. I’m seeing frequent “context compression” messages—Is this a problem?

No, this is normal. Context compression is triggered when content approaches the token limit, and it ensures the writing process continues smoothly. The agent retains all essential information—only non-critical details are compressed.

Technical Details: Tool Configuration Parameters

If you’re interested in the tool’s underlying settings, here are the key technical parameters. These are optimized for most writing scenarios, but you can modify them in the code if needed:

Parameter Value Description
Core Model kimi-k2-thinking The AI model responsible for reasoning and content generation.
Temperature 1.0 Controls the creativity of the output. 1.0 is optimized for this model, balancing creativity and coherence.
Max Tokens per Call 65,536 (64K) The maximum length of content generated in a single API call.
Context Window 200,000 tokens The maximum amount of historical context the model can process.
Max Iterations 300 The maximum number of cycles the agent will run to prevent infinite loops.
Compression Threshold 180,000 tokens (90% of the limit) The token count at which context compression is triggered automatically.

License and Credits

Kimi Writing Agent is available under the MIT License with an attribution requirement:

  • Non-Commercial Use: You can use and modify the tool freely, but you must retain the original author’s information.
  • Commercial Use: If you use the tool in a commercial product, you must clearly attribute it to Pietro Schirano (@Doriandarko).

Additionally, the tool uses the Moonshot AI API—ensure you comply with Moonshot AI’s terms of service when using the API.

Credits

  • Created by: Pietro Schirano (@Doriandarko)
  • Powered by: Moonshot AI’s kimi-k2-thinking model
  • Repository: https://github.com/Doriandarko/kimi-writer

Star History

Star History Chart

Whether you’re a novelist looking to streamline your draft process, a nonfiction author creating structured guides, or a content creator needing to produce consistent content, Kimi Writing Agent offers a powerful, autonomous solution. By following the installation steps, leveraging the tool’s features, and using the pro tips provided, you can transform your writing workflow—saving time, reducing frustration, and focusing on what matters most: bringing your ideas to life. With AI as your collaborative partner, the possibilities for creative and efficient writing are endless.