ghost-reader 0.2.0

Persona-driven fiction review simulator CLI

Ghost Reader CLI

Local-first persona-driven fiction review simulator for structured beta-reader-style feedback.

Repository: https://github.com/clchinkc/ghost-reader

For AI agents

Agents with web fetch and shell access should start here:

1. Fetch agent-setup.md (short bootstrap; do not scrape HTML report templates).
2. Install uv or pipx, then install from PyPI:

uv tool install ghost-reader
# or: pipx install ghost-reader
ghost-reader help
ghost-reader update check

3. Install the skill: copy skills/ghost-reader/ into your harness skill directory, or invoke Skill(ghost-reader) when available.
4. Read the operational contract: skills/ghost-reader/SKILL.md (workflow) and skills/ghost-reader/reference.md (data model, Phase 3 roadmap).

Documentation map

Document	Audience	Role
agent-setup.md	Agents	Bootstrap, install, 11-step workflow
skills/ghost-reader/SKILL.md	Agents	Operational contract
skills/ghost-reader/reference.md	Agents	Schemas, paths, HTTP API
llms.txt	Agents	Command index
examples/README.md	Everyone	Canonical sample trace (committed)
AGENTS.md / CLAUDE.md	Harness	Pointers to the above

The CLI remains local-first and binds serve to 127.0.0.1 by default. An optional, account-free Vercel deployment can serve Supabase-backed sessions by share URL.

Current status (Phase 2.5)

• Local CLI with iterative refinement rounds (round init, refine snapshot).
• Structured YAML for personas, reviews, feedback, and revision prompts.
• Local HTML reports from report/payload.json and swappable templates.
• Bidirectional feedback via ghost-reader serve (POST /api/feedback, /api/dialogue).
• Persona dialogue (dialogue append, dialogue context).
• Content-safe local telemetry and local sync bundles.
• Optional Supabase session storage selected with GHOST_READER_STORAGE=supabase.
• Public, telemetry-disabled Vercel report serving with ?session=<id> routing.
• Verification statuses (per session): review_ready_feedback_pending → refinement_complete → phase1_complete (these are verify outputs, not separate product phases).

Artifact contracts: review and feedback schema v2 only; sessions use round-* directories (no flat legacy layout).

There are no hosted user accounts or authentication. Phase 3 persona recommendation is planned (not in the CLI yet); see roadmap below.

Share a report through Vercel

The authoring CLI writes directly to Ghost Reader's dedicated Supabase project; the deployed server is a read/write presentation layer over the same session. Keep the service-role key on trusted authoring machines and in Vercel environment variables only.

cd /path/to/your-story-project
export GHOST_READER_STORAGE=supabase
export GHOST_READER_PROJECT_ID=your-project-id
export SUPABASE_URL=https://your-project.supabase.co
export SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

ghost-reader init
session_id="<unguessable-session-id>"
ghost-reader session create --id "$session_id" --story-unit "chapter 3" --personas mara,dex,pip
ghost-reader artifact write --session "$session_id" --type source-text --from chapter-3.md
# Write the persona review artifacts, then render:
ghost-reader render --session "$session_id"

Share https://ghost-reader-six.vercel.app/?session=<session-id>. The deployed server has no login: anyone who receives a session URL can access that report. Use non-guessable session IDs for material that is not intended for broad discovery.

Deployment uses an isolated ghost_reader Supabase schema in the dedicated Ghost Reader project. Telemetry is disabled in the container, and personas and templates are packaged in the image.

The Vercel project requires SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, GHOST_READER_PROJECT_ID, and a default SESSION_ID. Vercel injects PORT. Container startup fails immediately if SESSION_ID or PORT is missing.

For Writers (human users)

Ghost Reader is designed for writers who want structured, persona-driven feedback on their drafts. You don't need to be an AI expert — the CLI handles everything.

Typical workflow (10 minutes):

# 1. Install once
uv tool install ghost-reader

# 2. Go to your story project
cd ~/writing/my-novel

# 3. Initialize Ghost Reader
ghost-reader init

# 4. Create a review session for a chapter
ghost-reader session create --id chapter-3 --personas mara,dex,pip

# 5. Have your AI assistant (Claude, ChatGPT, etc.) write review YAMLs
#    Give it this prompt: "Read the attached chapter and write a Ghost Reader
#    review as the Mara persona. Use schema v2. Save as mara.review.yaml."
#    (Repeat for Dex and Pip.)

# 6. Load the reviews into Ghost Reader
ghost-reader artifact write --session chapter-3 --type review --persona mara --from mara.review.yaml
ghost-reader artifact write --session chapter-3 --type review --persona dex --from dex.review.yaml
ghost-reader artifact write --session chapter-3 --type review --persona pip --from pip.review.yaml

# 7. Render the interactive report
ghost-reader render --session chapter-3

# 8. Open it in your browser
ghost-reader serve --session chapter-3

The report shows each persona's findings side-by-side with cited passages, severity ratings, and specific revision suggestions. You can select which items to address and export a revision prompt to guide your next rewrite.

No AI assistant? You can also write review YAMLs manually — see the schema reference in skills/ghost-reader/reference.md. But Ghost Reader works best paired with an LLM that generates the structured reviews.

Key concept: Ghost Reader is the review management system. The AI generates the reviews. Ghost Reader renders, verifies, and tracks them — giving you a structured feedback loop instead of scattered chat responses.

Install (users)

Requires Python 3.11+. Install uv or pipx first.

Method	Command
uv tool (recommended)	uv tool install ghost-reader
pipx	pipx install ghost-reader
uvx (no global install)	uvx ghost-reader help
Dev (clone)	git clone [e-mail]:clchinkc/ghost-reader.git && cd ghost-reader && uv sync --extra dev then uv run ghost-reader help

uv tool install places ghost-reader on your PATH (typically ~/.local/bin).

ghost-reader init   # run from your story project directory
ghost-reader help

Build wheel locally

uv build
uv tool install dist/*.whl

Version management

Published to PyPI via OIDC trusted publishing. Version is set in pyproject.toml and released with a v* git tag. Run ghost-reader update check to compare the installed version against PyPI.

Sample trace

The repo includes a full review_ready_feedback_pending example at examples/sample-trace/. See examples/README.md.

cd examples/sample-trace
export GHOST_READER_HOME="$PWD/.ghostreader-home"
ghost-reader init
ghost-reader verify --session chapter-1
ghost-reader serve --session chapter-1

Regenerate after contract changes: uv run python scripts/refresh_sample_trace.py

Quick workflow

Run all commands from the story project directory (where .ghostreader/ lives), not from a clone of this repo unless you are developing Ghost Reader itself.

cd /path/to/your-story-project
ghost-reader init
ghost-reader session create --id chapter-3 --story-unit "chapter 3" --personas mara,dex,pip
# LLM writes review YAML per persona, then:
ghost-reader artifact write --session chapter-3 --type review --persona mara --from mara.review.yaml
ghost-reader render --session chapter-3
ghost-reader verify --session chapter-3
ghost-reader serve --session chapter-3 --timeout 600

After reviews render, serve is the primary user path: the user selects items in the browser and clicks Submit Feedback, which writes feedback/feedback.yaml. The agent then polls ghost-reader feedback summary --session chapter-3, runs ghost-reader prompt revision, rerenders, and verifies phase1_complete.

If serve is unavailable, open file:// on .ghostreader/sessions/<id>/round-<n>/report/index.html and use the copy-paste Ghost Reader Prompt fallback.

Pasted text (no story repo yet)

mkdir -p ~/ghost-reader-projects/my-chapter
cd ~/ghost-reader-projects/my-chapter
export GHOST_READER_HOME="$PWD/.ghostreader-home"
ghost-reader init
ghost-reader session create --id ch1 --story-unit "chapter 1"

Use /tmp/ghost-reader-* only for disposable tests.

Developer setup (this repo)

git clone [e-mail]:clchinkc/ghost-reader.git
cd ghost-reader
uv sync --extra dev
uv run ghost-reader update check

cd /path/to/story-project
uv run --project /path/to/ghost-reader --no-editable ghost-reader init

Report design contract

• Source text stays readable; annotations tie to cited passages.
• Full reader reasons live in persona sections, not only tooltips.
• Quiet, dense layout; no marketing-style chrome.

Test

uv lock --check
uv run --with ruff ruff check .
uv run --with pytest pytest

Code structure

Module	Role
cli.py	Command surface
server.py	Local bidirectional HTTP (serve)
feedback_store.py	Shared feedback persist + telemetry
validators.py	Artifact contracts
report.py	HTML from payload.json
verify.py	Session gates
telemetry.py / sync.py	Local events and export bundles
storage/	Local and Supabase session persistence

Roadmap: Phase 3 (planned)

Persona recommendation as a spatial HTML comparison artifact (recommendation.html) and ghost-reader recommend are not implemented yet. Until then, users choose personas manually (mara, dex, pip, or optional elena, rook). Custom personas are created by LLMs through the Ghost Reader skill — no CLI import command. Design notes: skills/ghost-reader/reference.md.