Installation

Hemingway runs as a local server alongside your dev environment. You'll be up in five minutes.

Step 1 — Install

npm install hemingway-ai

Or use your preferred package manager:

yarn add hemingway-ai
pnpm add hemingway-ai
bun add hemingway-ai

Step 2 — Init

npx hemingway-ai init

This creates a hemingway.config.mjs file in your project root with sensible defaults. Open it and set sourcePatterns to glob patterns that match your component files — this is what Hemingway uses to find files when writing changes back.

Step 3 — API key

export ANTHROPIC_API_KEY=sk-ant-...

Add this to your shell profile (~/.zshrc, ~/.bashrc, etc.) so it's available every session. The server won't error on startup without it, but generation requests will fail.

Step 4 — Start

npx hemingway-ai

The server starts on port 4800 by default: http://localhost:4800. Set the HEMINGWAY_PORT environment variable to use a different port.

Step 5 — Add to your site

Drop the client script into your HTML:

<script src="http://localhost:4800/client.js"></script>

For React projects, use the component instead and wrap it in a dev-only guard:

import { Hemingway } from 'hemingway-ai/react';

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === 'development' && <Hemingway port={4800} />}
    </>
  );
}

Step 6 — Activate

Open your dev site in the browser and press Cmd+Shift+H (Mac) or Ctrl+Shift+H (Windows/Linux) to toggle the Hemingway overlay.

Configuration

All options in hemingway.config.mjs:

Option	Default	Description
`port`	`4800`	Server port
`model`	`"claude-sonnet-4-6"`	Claude model to use for generation
`styleGuide`	`""`	Path to your brand voice / style guide markdown
`copyBible`	`""`	Path to your copy bible markdown
`referenceGuide`	`""`	Path to any additional reference doc for generation
`sourcePatterns`	`["src/*/.{tsx,astro,vue}"]`	Glob patterns for source files to search during write-back
`excludePatterns`	`["node_modules", "dist"]`	Patterns to exclude from write-back search
`writeAdapter`	`"auto"`	Write-back strategy (`auto`, `heuristic`, or `exact`)
`shortcut`	`"meta+shift+h"`	Keyboard shortcut to toggle the overlay
`accentColor`	`"#3b82f6"`	Accent color for the overlay UI

Full config example

// hemingway.config.mjs
export default {
  port: 4800,
  model: "claude-sonnet-4-6",
  styleGuide: "./docs/brand-voice.md",
  copyBible: "./docs/copy-bible.md",
  referenceGuide: "",
  sourcePatterns: ["src/**/*.{{tsx,astro,vue}}"],
  excludePatterns: ["node_modules", "dist"],
  writeAdapter: "auto",
  shortcut: "meta+shift+h",
  accentColor: "#3b82f6",
}

Environment variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	Required	Your Anthropic API key. Get one at console.anthropic.com.
`HEMINGWAY_PORT`	Optional	Override the server port. Takes precedence over the config file value.

Verify it's working

The Hemingway server is running and shows a startup message in your terminal.
http://localhost:4800/health returns {"ok": true}.
The client script is loading without errors in the browser console.
Pressing Cmd+Shift+H toggles the overlay on your dev site.
Clicking a text element outlines it and shows the Hemingway panel.

You're ready. Questions? Check the FAQ or open an issue on GitHub.