Audition

Audition turns Ollama into a persistent, local-first test audience for written work. Each Audition project points to one external writing document and keeps the simulated audience history for that evolving work.

Edit the manuscript in your normal editor. Return to Audition to inspect prior runs, ask questions about stored reactions, or run a completely fresh audience against the current revision.

Audition produces simulated language-model reactions. It is not human feedback, user research, or statistically representative evidence about any population. Treat its output as a way to explore plausible readings, not as a replacement for real readers.

The project model

A project is an ongoing piece of writing, not one hash of one revision:

Novel Draft
├── source: ~/Writing/novel.md
├── Run 12 — SHA-256 aaa…
└── Run 13 — SHA-256 bbb…

The project stores the canonical source path and its own model, audience, audience size, reading mode, concurrency, temperature, token limit, timeout, and synthesis defaults. Each run snapshots the exact source SHA-256, path, settings, and full audience profile it actually used. Editing a profile or manuscript later never changes an old run.

Audition never copies, moves, or modifies the source document. If the source moves, use M in the project pane to relink the same project without losing its runs. Missing sources are clearly marked.

Features

• Persistent project sidebar and last-active-project restoration.
• Keyboard-first terminal workspace suitable for SSH.
• Project creation, rename, source relinking, and recoverable removal.
• Historical run browser with overview, individual reader, and synthesis views.
• Lightweight questions against selected stored results.
• Project-specific JSONL query history with partial typed prefix search.
• .txt, .md, .markdown, .html, and .htm ingestion.
• Independent fresh model context for every reader and every new run.
• Sequential reading that withholds future sections from the reader.
• Bounded concurrency, streaming progress, cancellation, and partial-result preservation.
• Revision awareness using SHA-256 rather than document version control.
• No telemetry, analytics, accounts, cloud service, or document editing.

Requirements and installation

• Go 1.26 or newer to build from source.
• A running Ollama-compatible endpoint. The default is http://127.0.0.1:11434.
• At least one installed model. Audition never downloads one automatically.

ollama serve
ollama pull qwen3:8b
go install archuser.org/audition/cmd/audition@latest

From a checkout:

make build
./bin/audition --version

Persistent terminal workspace

Launch the workspace and restore the last project:

audition

Open or create the project associated with a canonical source:

audition ./story.md

Audition avoids duplicate projects when the same existing file is referenced through relative paths or symlinks.

The workspace has project, run, and query panes. Core keys are visible at the bottom:

Key	Action
Tab / Shift+Tab	Move between project, run, and query panes
Up / Down	Navigate projects/runs or search matching project query history
Enter	Open a run or submit a stored-run question
Ctrl+P	Focus project navigation
Ctrl+R	Run a fresh audience against the active project’s current source
Ctrl+L	Select an installed model for the active project
Esc	Close a modal/result, or safely cancel current generation
Ctrl+C	Cancel active work or exit
N / E / M / D	New, rename, relink source, or remove in the project pane
S	Edit project settings from the run pane

Removing a project never deletes its source. Project-owned data is moved from projects/ into private project-trash/, making manual recovery possible.

Runs versus queries

A fresh audition run is expensive. It reads the current source, computes its hash, snapshots project settings, and starts independent readers with new model histories. No reader sees another reader, an older run, synthesis, or project query history.

A query is different. It asks one lightweight question about the selected stored run, for example:

Where did readers first distrust Marcus?
Who predicted the chapter-eight twist?
Which argument seemed weakest?

The query request contains only labeled stored reader reactions, an optional stored synthesis, and the question. It does not read or send the manuscript, start audience members, include earlier queries, or reuse conversation state. Answers are analyses of simulated reactions, not human evidence.

Up/Down in the query box uses history only from the active project. If the typed prefix is Where, Up cycles backward through that project’s entries beginning with Where; Down moves forward and eventually restores the original draft.

Sequential reading

Sequential mode is the default:

section 1 → reaction and predictions → section 2 → revised reaction → …

Markdown and HTML headings define sections. Plain text is split at paragraph boundaries into bounded parts. A reader retains only its own prior section exchanges, and future sections are not placed in its prompt. A different reader or later run starts from a completely fresh context. Whole-document mode supplies the normalized work in one request per reader.

Non-interactive commands

audition projects
audition models
audition audiences
audition run ./story.md
audition run ./story.md --model qwen3:8b --members 5
audition run ./story.md --audience critical --mode whole --no-synthesis

audition run PATH opens or creates the canonical project and stores the run beneath it. Existing project settings are used by default. Explicit CLI flags and corresponding AUDITION_* environment variables temporarily override settings for that run without rewriting project defaults.

Progress and the saved-run location go to stderr. The synthesis—or individual responses when synthesis is disabled—goes to stdout.

Audience profiles

Built-in profiles are general, critical, and genre-newcomer. Add TOML files below $XDG_CONFIG_HOME/audition/profiles/, or ~/.config/audition/profiles/ when XDG is unset:

name = "skeptical-sci-fi-reader"
description = "Genre-fluent and impatient with passive protagonists."

[traits]
genre_familiarity = 0.9
science_fiction_affinity = 0.9
patience = 0.4
exposition_tolerance = 0.3
ambiguity_tolerance = 0.8
criticality = 0.8
technical_literacy = 0.9

Traits are extensible strings, booleans, or numbers. Describe predispositions, not desired verdicts. A run embeds the complete profile snapshot, so later profile edits cannot rewrite history.

Global configuration

Audition reads $AUDITION_CONFIG, otherwise $XDG_CONFIG_HOME/audition/config.toml, otherwise ~/.config/audition/config.toml. See config.example.toml.

ollama_url = "http://127.0.0.1:11434"
default_model = "qwen3:8b"
default_audience = "general"
default_members = 3
default_mode = "sequential"
concurrency = 2
timeout = "10m"
temperature = 0.8
max_tokens = 2048
synthesize = true

Global audience settings seed newly created projects. Existing projects retain their own settings. ollama_url remains global. Environment overrides are AUDITION_OLLAMA_URL, AUDITION_MODEL, AUDITION_AUDIENCE, AUDITION_MEMBERS, AUDITION_MODE, AUDITION_CONCURRENCY, AUDITION_TIMEOUT, AUDITION_TEMPERATURE, AUDITION_MAX_TOKENS, and AUDITION_SYNTHESIZE.

Storage and migration

The default XDG data layout is:

~/.local/share/audition/
├── state.json
├── projects/
│   └── <project-id>/
│       ├── project.json
│       ├── history.jsonl
│       └── runs/
│           └── <run-id>/
│               ├── metadata.json
│               ├── reader-001.md
│               └── synthesis.md
└── project-trash/

Project and run files are inspectable JSON, JSONL, and Markdown. Directories and files use private permissions where supported. Writes are atomic, and run snapshots are updated as readers complete.

Prototype releases stored runs in the legacy flat $XDG_DATA_HOME/audition/runs/ directory. The project redesign leaves those files untouched: their metadata has no reliable project identity, so Audition does not guess, move, or delete them automatically.

Privacy and endpoint security

By default, writing is sent only to loopback Ollama and saved locally. Audition contains no telemetry. It never sends unrelated files, directory listings, previous runs, or project query history to a fresh audience.

If a remote endpoint is configured, submitted document text and prompts leave the machine for that endpoint. Use a trusted HTTPS endpoint with valid certificates. The HTTP client requires TLS 1.2 or newer; TLS 1.3 is used when negotiated. Plain HTTP is suitable only for a trusted local connection. Endpoint URLs with embedded credentials, queries, or fragments are rejected.

The selected source is opened read-only. HTML scripts, styles, and noscript content are excluded. Model output is displayed and stored as text, never executed.

Supported formats and limits

Supported now: UTF-8 plain text, Markdown, and HTML. DOCX, EPUB, and PDF are not supported in this release. Source files larger than 32 MiB are rejected. Audition reports model context errors per reader and preserves peers that completed.

Development

make build       # create bin/audition
make check       # formatting check, vet, tests, and build
make test-race   # race detector

Tests use fake inference clients and local HTTP servers; they do not require Ollama. Coverage includes projects, canonical source identity, active selection, relinking, reversible removal, revisions, profile snapshots, isolated histories, prefix matching, run association, stored-result queries, fresh reader isolation, read-only sources, atomic persistence, and failure handling.

License

Audition’s original source is licensed under the Mozilla Public License 2.0. Dependency source remains under each dependency’s own license; Audition does not relicense third-party work.