Getting Started

Install CtxE, sign in, build a searchable codebase index, and explore it in the local dashboard.

Prerequisites

  • macOS, Linux, or Windows with PowerShell
  • A codebase you want to index
  • A Google or GitHub account for CTXE Server authentication

1. Install CtxE

Upgrading from a version earlier than 0.3.6? Run the official uninstaller before installing the current release and choose Everything. Earlier config and index data are not compatible with the 0.3.6 client. The uninstaller preserves workspace-local .ctxe directories, so remove those from previously indexed workspaces before reinstalling.

Run the installer for your platform:

macOS / Linux

curl -fsSL https://storage.tlelabs.com/ctxe/latest/install.sh | sh

Windows (PowerShell)

irm https://storage.tlelabs.com/ctxe/latest/install.ps1 | iex

Verify the installation:

ctxe --version
ctxe --help
ctxe daemon status

The current release reports ctxe 0.3.6. On a fresh installation, daemon status should show the service definition present while autostart is disabled and the process is stopped.

2. Sign in

Indexing and Ask use the CTXE Server. Authenticate once through the browser-based OAuth flow:

ctxe login

Choose Google or GitHub in the browser. Use ctxe whoami to verify the active identity.

3. Index your workspace

From the project root, inspect the local plan and then create the index:

cd ~/projects/my-app
ctxe index . --dry-run
ctxe index .

The dry run parses the workspace and reports planned changes without writing an index or calling the server. The real index stores code-aware chunks locally, then obtains embeddings and optional enrichment outside the database write transaction.

Indexing is incremental. Later runs process changed files and pending work instead of rebuilding everything.

4. Check index health

Status is read-only and reports index state, counts, and capability health:

ctxe status .
ctxe status . --format json

5. Open the dashboard

Launch the local web dashboard to monitor workspace health and indexing progress, ask questions, browse query history and indexed content, and manage global settings:

ctxe dashboard

CtxE opens the dashboard in your browser and serves it on localhost. Press Ctrl+C to stop it. See CLI Reference for port and browser options.

6. Ask your first question

Ask a concrete question or investigation objective:

ctxe ask "How does user authentication work?"
ctxe ask "What calls UserService.create()?" --effort high

Ask combines semantic retrieval, indexed text search, graph expansion, and evidence synthesis. The default effort comes from [ask_v4].effort; the built-in default is min.

7. Enable background indexing (optional)

Fresh installs leave the supervised daemon disabled and stopped. Request durable watch intent for each workspace, then enable the worker:

ctxe daemon watch .
ctxe daemon enable --now
ctxe daemon status
ctxe daemon list

The index created in step 3 already establishes accepted catalog membership. watch independently requests continuous indexing and is safe to repeat. Use ctxe daemon unwatch . to stop watching while preserving source files, catalog membership, and index data.

Use ctxe daemon stop for a temporary stop, or ctxe daemon disable --now to stop and disable autostart.

Use with MCP

The installer offers to configure CtxE for Claude Code and Codex when those clients are detected. Restart the selected client after installation.

For Cursor, VS Code, Windsurf, or manual setup, see MCP Integration.

Next steps