Installation
On this page
This page covers installing Ghostwriter on a Craft site, the queue it runs on, and updating and uninstalling it.
Requirements
- PHP 8.2 or later
- Craft CMS 5.8 or later
- An API key for one writing provider: Anthropic (Claude), OpenAI (ChatGPT) or Google (Gemini), or an OpenRouter account (connect it from the settings). See API keys.
Optional:
- An OpenAI or Gemini key, to make images. Claude doesn't make images.
- The Imagick PHP extension, for sending smaller copies of images to the model. Without it, images are sent at their original size, up to 1 MB.
Install the plugin
Install Ghostwriter from the Plugin Store in the control panel, or from your project's root with Composer:
composer require 1994/ghostwriter-craft
php craft plugin/install ghostwriter
Composer also installs 1994/ghostwriter-core (^1.10) from Packagist, the package Ghostwriter shares with its Statamic and Filament versions. It holds the providers, the prompts, the draft handling, the layout algorithms and the rules for pieces of writing, the content plan and images. No extra repository is needed.
Once it's required, you can also install it from Settings → Plugins.
Add your API key
Set up the key for your writing provider under Ghostwriter → Connections (an admin): open the provider's page, make a key, paste it, Check & save. Or add it to .env, for example ANTHROPIC_API_KEY=sk-ant-..., which always wins. See API keys for every key Ghostwriter can use, and Connections.
Who can use it
People need the Use Ghostwriter permission, and admins manage it. See Permissions.
The queue
Writing a draft or a guide can take a minute or more, which is longer than a web request should be held open. So each model call runs as a job in Craft's queue, and the screen checks back until the answer is ready.
- No setup needed. By default Craft runs its queue from control panel requests, so jobs start as soon as you ask.
- With a queue worker. If your site sets
runQueueAutomaticallytofalseand runs a worker (php craft queue/listen, Supervisor, or your host's daemon), the jobs run there instead. Make sure the worker is running, or nothing will happen. - The job time limit is set for you. Each job is allowed the time limit × 3 + 60 seconds: 960 seconds with the default 300. That's because a busy provider is tried up to three times (see Busy providers and retries). A worker with its own, shorter limit stops jobs early.
Daily jobs
Content to revisit and the list of pages a draft can link to are kept current by a daily pass, and the optional check of links to other sites runs weekly. Craft has no scheduler, so add them to cron:
0 3 * * * php /path/to/craft ghostwriter/revisit/refresh
0 4 * * 0 php /path/to/craft ghostwriter/revisit/check-links
Neither calls a model. Without cron, Craft's garbage collection queues the daily pass once it's over a day old. The link check does nothing until an admin turns it on.
Updating
composer update 1994/ghostwriter-craft
php craft up
php craft up runs Ghostwriter's migrations. See CHANGELOG.md for what changed. Updating from an early build, which kept its guides and plan in files, imports them into the database (see Configuration).
Upgrading from 1.2 to 1.3
composer update 1994/ghostwriter-craft 1994/ghostwriter-core
php craft up
php craft ghostwriter/revisit/refresh --full
php craft upadds the new tables (keys set up in Connections, Suggest edits' reviews, Content to revisit and the index of your pages) and moves the OpenRouter key and Shutterstock account into Connections. Keys in.envkeep working and still win.- Keys in Connections are encrypted with your security key, so keep
CRAFT_SECURITY_KEYthe same on each environment. ghostwriter/revisit/refresh --fullreads every page once, so Content to revisit and the links Ghostwriter suggests are complete straight away. Otherwise they fill in over the daily pass (see Daily jobs).- Restart your queue workers, if you run them, so they pick up the new code.
Uninstalling
Uninstall from Settings → Plugins, or:
php craft plugin/uninstall ghostwriter
composer remove 1994/ghostwriter-craft
Uninstalling drops Ghostwriter's tables, with its guides, kinds, plan, conversations, reviews and Content to revisit. The stock image ledger is written to storage/ghostwriter-stock-ledger-<date>.json first. Prompt overrides in config/ghostwriter/prompts/ stay until you delete them. Assets it saved (photos, made images, the striped placeholder) stay in your volumes.
Next: Get started.