Convo

Convo is an open-source, local-first terminal app for chatting with a selected file. Qwen3 embeddings and PostgreSQL full-text search retrieve passages together; a local cross-encoder reranks them; your connected ChatGPT account returns a structured answer with supporting quotations.

It is released under the MIT License. Contributions are welcome—see CONTRIBUTING.md.

Install and start

The supported release install uses uv:

uv tool install convo-cli
convo

On first launch, convo creates a private settings file at ~/.config/convo/.env, pulls pgvector/pgvector:pg16, starts a loopback-only convo-postgres container, and runs migrations before opening the terminal app. It generates a random database password and preserves existing data. Later launches restart Convo's local container if needed and apply pending migrations.

Local storage needs Docker Desktop or Podman installed. Start Docker Desktop first if you use Docker. On macOS, Convo starts or initializes a Podman machine when Podman is installed. First use downloads Python dependencies, a database image, and—when indexing your first file—the embedding/reranker models.

If you already use PostgreSQL, set DATABASE_URL to a postgresql+psycopg://... URL, run convo --setup once to migrate that database, then run convo. Explicit database connections are used as configured; startup only manages storage created by Convo.

For a one-command install on macOS/Linux, inspect and then run the repository installer:

curl -LsSf https://raw.githubusercontent.com/madvillax/convo/main/scripts/install.sh | sh

It installs uv if needed, installs convo-cli, and adds uv's tool directory to your shell path. Then type convo to start. Open a new terminal if convo is not immediately found.

To use an unreleased checkout while developing:

uv sync --python 3.12
uv run convo

--directory ~/Documents changes the file browser root. Environment variables always override the user settings file; .env.example is only for checkout-based development.

Optional model download/warmup outside the TUI:

uv run convo --download-model

This prepares both Qwen3 and cross-encoder/ms-marco-MiniLM-L6-v2. Models otherwise load/download on demand in an isolated process. File preparation shows stages and elapsed time; Esc cancels it. Download/native logs stay in ~/.cache/convo/rag-worker.log (respecting XDG_CACHE_HOME). After storage preparation, startup restores account preferences locally; models and the account catalog load when needed.

For a UI preview without services or backend dependencies:

uv run convo --shell

Use

Type / for command suggestions. Filter by typing, use ↑/↓ to move, Tab to complete, Enter to run, and Esc to dismiss.

Questions appear in shaded blocks with a gold left edge. Answers use spaced Markdown with highlighted code, and source quotations appear in a separate subdued block. The composer groups your input with the gold model name and thinking level underneath. The ASCII title collapses once chatting starts and in smaller terminals, leaving more room to read. Long replies open at the question and the beginning of the answer; use PageUp/PageDown or the mouse wheel to keep reading.

Change the cycling shortcut with convo --thinking-key ctrl+g or set CONVO_THINKING_KEY=ctrl+g in .env (export it for --shell). The command-line flag takes precedence. Shift+Tab and F2 remain available. Choose a Ctrl/Alt letter or F3–F24; essential keys are reserved. /help shows the configured shortcut. Only thinking levels supported by the selected account model can be saved.

Sessions, completed message pairs, displayed source quotes, and structured answers persist in PostgreSQL. Use /sessions after restarting. Resuming uses the saved indexed snapshot, so the original file can have moved or disappeared. Use /file again to index changed content. A failed request never saves a partial turn. Account tokens remain in the OS keyring; model/thinking preferences remain in the local account profile.

Greetings such as hello and acknowledgements such as thank you receive a short local reply without retrieval or model calls. Mixed greetings and file questions still use retrieval. Specific questions use hybrid search, reciprocal rank fusion, cross-encoder reranking, and weak-match filtering. Broad file overviews sample sections across the snapshot and rerank their order without applying a QA relevance cutoff.

ChatGPT returns JSON sections containing text and citation objects. Python validates the schema, requires citations on answered sections, checks source IDs and exact supporting quotes, then renders readable Markdown with numbered citations. Only cited quotes appear under sources. An empty evidence set returns an insufficient-evidence response without an LLM call. These checks verify structure and quotations; they do not prove every generated claim is entailed by its quote.

Supported files: .txt, .md, .pdf, .docx, .csv, .json, .py, .rst, .log. Limits: 10 MB input, 500,000 extracted characters, and 2,000 chunks. LlamaIndex is used only for readers and chunking. The TUI supports terminals down to 50 columns × 18 rows.

Architecture

convo/
├── core/       settings, shared values and UI/backend contracts
├── ui/         Textual app, commands, file/model/session pickers
├── llm/        ChatGPT connection, credentials, catalog and Responses transport
├── pipeline/   chat flow, routing, ingestion, embeddings, reranking and worker
├── prompts/    answer instructions, context builder and structured schema
└── db/         SQLAlchemy models, connections, document/search/session queries

ARCHITECTURE.md explains the files, schema, data flow, tuning, and verification. changes.md records implementation approaches and validation.

Checks

uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest -q

PostgreSQL integration checks use a disposable database, enabled explicitly with CONVO_TEST_DATABASE_URL. CONVO_TEST_MODELS=1 also exercises real Qwen/reranking models. See ARCHITECTURE.md for these opt-in checks and their prerequisites.

Releasing to PyPI

Maintainers should test a release on TestPyPI first, then create a GitHub release. The included Publish to PyPI workflow uses PyPI Trusted Publishing, so it does not require a long-lived token in the repository. Configure the repository and .github/workflows/publish.yml as a Trusted Publisher in PyPI before publishing.

uv build --no-sources
uv publish --token "$PYPI_TOKEN" # one-time/manual alternative