Configuration

Almost everything in Precursor is configured at runtime in the app — under Settings — rather than through environment variables. Every setting has a built-in default, so the app runs fine with no .env file at all. The handful of process-level knobs (host, port, database URL, backup scheduling) live in .env; see the configuration reference.

Connecting a model

Open Settings → Model to pick a provider and enter its credentials. Secrets are stored in the local database and never echoed back by the API — only a *_present boolean is returned.

Provider	What it is	Credential
GitHub Copilot (default)	The Copilot model catalogue (Claude, Gemini, GPT, …), OpenAI-compatible at api.githubcopilot.com	a gho_* token
Azure AI Foundry	Azure OpenAI / AI Foundry deployments	endpoint + key + deployment
OpenAI-compatible	OpenAI, Mistral, Hugging Face, Ollama, or any compatible gateway	base URL + key
Mock	A deterministic streamed reply for offline development	(none — automatic fallback)

Offline by default

When no credentials resolve, Precursor automatically uses the mock provider, so the chat flow stays usable with zero setup. Configure a real provider whenever you're ready.

Which model gets used

Precursor pins no model id of its own. Until you choose one in Settings → Model, the chat model is the first entry in the catalogue the active provider advertises — so a fresh install works without picking anything, whatever that provider happens to offer today.

Your choice is honoured for as long as the provider still lists it. Providers retire models on their own schedule, though, and a retired id would otherwise fail every turn — so if the one you picked disappears, Precursor logs a warning and falls back to a model that exists rather than erroring. If the catalogue can't be reached at all, your stored choice is used unchanged: an unreachable network is no reason to second-guess you.

The catalogue is cached briefly, and re-read immediately when you change provider or credentials.

Agents pick their own

Agent sessions default to auto, which lets the Copilot SDK runtime choose a current model. That's an agents-only value — it is not a chat model id, and it isn't valid in Settings → Model.

GitHub authentication

Precursor resolves a GitHub token in this order:

1. A token saved in Settings → GitHub.
2. Your GitHub CLI session (gh auth token) if you're signed in via gh auth login.

So if you already use gh, you don't need to set anything. A token needs the models:read fine-grained permission (or Copilot access) for real model responses. With no token at all, Precursor falls back to the mock provider so the chat flow stays usable offline.

The token value itself is never returned by the API. When a token resolves to a real GitHub account, the sidebar persona menu also shows your Copilot AI credits and the next reset date.

Several accounts signed in to gh

gh auth token follows whichever account is active, so with more than one login the token Precursor gets depends on whoever last ran gh auth switch in an unrelated shell. That's fine interactively, and hopeless for an instance started at login. Pin the login instead:

PRECURSOR_GITHUB_CLI_USER=your_login

Precursor then asks for that account specifically, every time.

Which repository issues go to

Settings → GitHub also holds the default owner/name repository used when a topic creates an issue. It can be overridden at two narrower levels, checked in this order:

1. the topic's own repository, set in its settings panel;
2. its collection's repository;
3. the global setting above.

Speech-to-text (Live sessions)

The live meeting assistant transcribes audio with Azure AI Speech. Set a Speech key and endpoint under Settings → Speech-to-text. Until then, live sessions can be created but the Record button stays disabled. Audio streams directly from the browser using a short-lived token minted by the backend — the subscription key never reaches the browser, and raw audio is never stored.

Other settings areas

Precursor's Settings panel is organized into tabs, each covered by the feature it configures:

Tab	Covers
Model	Active provider + credentials, default chat model.
Chat	Stats sidebar, notifications, and auto-naming for new chats.
GitHub	Token, default repository, issue-context behaviour.
MCP	Enable tool servers, and choose which of your own sections the built-in server exposes (off by default).
Collections	Create and edit collections.
Agents	Turn Agents mode on/off, set the global approval policy, manage blueprints, and bound timeline retention.
Workflows	The defaults a new pipeline starts from.
Live / Speech-to-text	Enable the section, pick the fast insights model, set transcript retention and Azure Speech credentials.
Backup	Periodic copy of the database + attachment blobs into a plain folder.
System	Theme, storage retention, and the command-runner jail.

Fleet-wide knobs that aren't per-object — the agent concurrency cap, retry backoff — are .env settings.

Process-level configuration (.env)

For deployment concerns — bind host, port, database URL, log level, shutdown grace, and backup scheduling — copy .env.example to .env and uncomment what you want to override:

# PRECURSOR_HOST=127.0.0.1
# PRECURSOR_PORT=8000
# PRECURSOR_DATABASE_URL=sqlite+aiosqlite:///./precursor.db
# PRECURSOR_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/precursor

See the full list in the configuration reference.

Postgres needs an extra

The default database is a local SQLite file. To point at PostgreSQL, install the postgres extra (uv sync --extra postgres) for the asyncpg driver and set PRECURSOR_DATABASE_URL accordingly.