Installation
On this page
This page covers what Ghostwriter needs, installing it, the queue it runs on, and updating or removing it.
Requirements
- PHP 8.3 or later, with the GD extension (it draws the striped image placeholders).
- Statamic 6.30 or later. Ghostwriter is tested on 6.30 (with Laravel 12.40) through 6.35 (with Laravel 13). Roles, permissions and shared conversations need Statamic Pro; see Permissions.
- An API key for one writing provider: Anthropic (Claude), OpenAI (ChatGPT) or Google (Gemini). The provider bills your account for what Ghostwriter uses, pay as you go (Gemini has a limited free tier). See API keys.
- A queue worker, or PHP-FPM if your site uses the
syncqueue. See The queue.
Optional:
- An OpenAI or Gemini key, to make images. Claude doesn't make images.
- The Imagick extension. Ghostwriter sends small copies of images to the model, made with Imagick when it is loaded and with GD otherwise.
Install the addon
From your project's root:
composer require 1994/ghostwriter-statamic
This also installs 1994/ghostwriter-core (^1.10) from Packagist: the part Ghostwriter shares with its Filament and Craft versions. No extra repository is needed.
Ghostwriter doesn't use the Laravel AI SDK (laravel/ai). It has its own connection to Anthropic, OpenAI and Gemini, and doesn't read config/ai.php, except that a key still set there is used when the matching .env variable is empty. If config/ai.php was only there for Ghostwriter, you can delete it.
Then publish the Control Panel assets:
php artisan vendor:publish --tag=ghostwriter-statamic --force
Add that line to your deploy script after composer install, so the assets reach the server too. public/vendor/ghostwriter-statamic can be left out of version control.
Add your API key
First run the migration, which makes the one table Ghostwriter adds, ghostwriter_credentials, where keys set up in Connections are kept, encrypted with your APP_KEY:
php artisan migrate
A site without a database can skip this: the keys are kept in an encrypted file, storage/ghostwriter/credentials/credentials.json, instead.
Then set up the key for your provider under Tools → Ghostwriter → Connections: 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. If APP_KEY ever changes, keys kept in Connections can't be read any more: set them up again. See API keys for every key Ghostwriter can use, and Connections.
Who can use it
Ghostwriter adds one permission, Write content and edit the voice guide with Ghostwriter. Roles and permissions are part of Statamic Pro; on Statamic Core the one super user can use and manage everything. See Permissions.
The queue
Writing a draft or a guide can take a minute or more, longer than a web request should be held open.
-
With a queue connection (database, Redis and so on), each model call runs as a queued job. Keep a worker running, or nothing happens:
php artisan queue:work --timeout=960If nothing picks the work up for a while, Ghostwriter says so: "Still waiting for a queue worker to pick this up. Is “php artisan queue:work” running?" It names the queue when it isn't
default. -
On the
syncdriver, the default for a flat-file site, the call runs after the response has been sent, in the same PHP process, while the screen checks back for the result. This needs PHP-FPM, which Herd, Forge and most hosts use.php artisan servehandles one request at a time, so it blocks until the call is done.
Why 960 seconds. Each model call may take up to timeout seconds (300 by default). A provider that is busy or limiting requests is tried again, up to three attempts in all (see Busy providers and retries), so each job is allowed timeout × 3 + 60 seconds: 960 with the default. Set your worker's own limit (--timeout, or Horizon's timeout) at least that high. On the database queue, also set DB_QUEUE_RETRY_AFTER above it, for example 1020, so a long job isn't handed out twice. If you raise GHOSTWRITER_TIMEOUT, raise these too.
Updating
composer update 1994/ghostwriter-statamic
php artisan vendor:publish --tag=ghostwriter-statamic --force
php artisan queue:restart
A running worker keeps the old code until it restarts, hence the last line. See the changelog for what changed.
Upgrading from 1.2 to 1.3
composer update 1994/ghostwriter-statamic 1994/ghostwriter-core
php artisan vendor:publish --tag=ghostwriter-statamic --force
php artisan migrate
php artisan ghostwriter:revisit --full
php artisan queue:restart
- Assets. The Control Panel assets changed: publish them again with
--force, as above. - Migration. 1.3 adds one table,
ghostwriter_credentials, for keys set up in the new Connections screen. Without a database, skipmigrate: keys are kept in an encrypted file instead. - Keys move into Connections by themselves. Keys in
.envkeep working and still win. The key from Connect with OpenRouter (storage/ghostwriter/provider-keys.json) and the Shutterstock account (library-tokens.json) are moved into Connections the first time Ghostwriter runs, and the old files removed. They're encrypted withAPP_KEY, so keep it the same between deploys. - Content to revisit.
ghostwriter:revisit --fullreads every page once, so the new list is complete straight away. Otherwise it fills in over the daily pass.
From 1.0 to 1.1
Nothing to migrate.
- Config. If you published
config/ghostwriter.php, the new settings (stock,stock_path,publish,finish,drafts_unpublished) take their defaults from the package until you add them. To see them all, publish the config again with--tag=ghostwriter-config --forceand copy your changes back. - Stock photo ledger.
content/ghostwriter/stock/is made when the first stock photo goes in. Commit it with your content: it is the record of what you licensed. - Scheduler.
ghostwriter:stock-cleanupruns hourly through Laravel's scheduler (php artisan schedule:runevery minute from cron, as usual). - Publishing. Pages holding a fact to add (
[[ask: …]]), a link to choose, a link to a deleted entry, an image placeholder or an unlicensed stock preview can no longer be published until they're finished. See Finish this page; set it to Warn to publish with a warning instead. - Drafts start unpublished. Set
GHOSTWRITER_DRAFTS_UNPUBLISHED=falseto keep the 1.0 behaviour.
Uninstalling
composer remove 1994/ghostwriter-statamic
Its one table, ghostwriter_credentials, stays until you drop it. Its guides, kinds and plan stay in resources/ghostwriter/, its settings in resources/addons/ghostwriter-statamic.yaml, and its working files in storage/ghostwriter/, until you delete them. Assets it saved stay in your containers: photos, made images and the striped placeholder.
Next: Get started.