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`	`"./docs/style-guide.md"`	Path to your brand voice / style guide markdown
`copyBible`	`"./docs/copy-bible.md"`	Path to your copy bible markdown
`referenceGuide`	`"./reference/saas-and-services-copy-guide.md"`	Path to any additional reference doc for generation
`sourcePatterns`	`["components/*/.{tsx,jsx,ts,js,mdx,md,html,htm}", "src/*/.{tsx,jsx,ts,js,mdx,md,html,htm}", ...]`	Glob patterns for source files to search during write-back
`excludePatterns`	`["node_modules", ".next", "dist", "build"]`	Patterns to exclude from write-back search
`writeAdapter`	`"react"`	Write-back strategy (`react` or `generic`)
`shortcut`	`"ctrl+shift+h"`	Keyboard shortcut to toggle the overlay
`notepadShortcut`	`"alt+shift+h"`	Reserved for notepad mode (currently hidden)
`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/style-guide.md",
  copyBible: "./docs/copy-bible.md",
  referenceGuide: "./reference/saas-and-services-copy-guide.md",
  sourcePatterns: [
    "components/**/*.{tsx,jsx,ts,js,mdx,md,html,htm}",
    "src/**/*.{tsx,jsx,ts,js,mdx,md,html,htm}",
    "app/**/*.{tsx,jsx,ts,js,mdx,md,html,htm}",
    "pages/**/*.{tsx,jsx,ts,js,mdx,md,html,htm}",
    "content/**/*.{tsx,jsx,ts,js,mdx,md,html,htm}",
    "site/**/*.{tsx,jsx,ts,js,mdx,md,html,htm}",
    "packages/**/*.{tsx,jsx,ts,js,mdx,md,html,htm}",
  ],
  excludePatterns: ["node_modules", ".next", "dist", "build"],
  writeAdapter: "react",
  shortcut: "ctrl+shift+h",
  notepadShortcut: "alt+shift+h", // reserved; notepad UI is currently hidden
  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 (or Ctrl+Shift+H on Windows/Linux) 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.