Getting started

From nothing to the first answer: install CodeLoupe, ask a question in a repository, and know where its state lives. It works on any git repository with Kotlin or Java sources, with no configuration.

Requirements

git ≥ 2.31 and either the bundle (it carries its own Java runtime) or, to build from source, JDK 25 (Gradle finds or downloads it as a toolchain).

Install

You want	Do
The desktop app, tray, daemon and CLI in one download	An installer from the Releases page (no release is published yet; every CI run keeps its installers for 7 days as artifacts); see Installers and updates
Only the daemon and the CLI, no Java needed	The codeloupe-<version>-<os>-<arch>.zip bundle of a release (or of a CI run); unpack it and put its bin/ on PATH (Packaging and releasing)
To build from source	./gradlew installDist, then build/install/codeloupe/bin/codeloupe (needs JDK 25)

First queries

./gradlew installDist
build/install/codeloupe/bin/codeloupe outline OrderService          # from inside a repository
build/install/codeloupe/bin/codeloupe symbol "OrderService.handle(_)"
build/install/codeloupe/bin/codeloupe find "*Repository" --kind interface
build/install/codeloupe/bin/codeloupe usages OrderService.handle
build/install/codeloupe/bin/codeloupe calls OrderService.handle --depth 2      # --callees for what it calls
build/install/codeloupe/bin/codeloupe hierarchy Repository
build/install/codeloupe/bin/codeloupe changes                    # what this branch changed, by declaration
build/install/codeloupe/bin/codeloupe issue ABC-5 --section scope   # with a tracker configured
build/install/codeloupe/bin/codeloupe tasks "epic: ABC-1" --mode ready
build/install/codeloupe/bin/codeloupe task_code ABC-5            # its landed or predicted code
build/install/codeloupe/bin/codeloupe code_tasks OrderService.handle   # the tasks that touched it
build/install/codeloupe/bin/codeloupe task_context ABC-5         # a planner's whole starting pack; asked again: what changed
build/install/codeloupe/bin/codeloupe doc plan.md --section goal # a text file by digest, section or line window
build/install/codeloupe/bin/codeloupe run -- git log -30         # a short command: its summary, the rest by handle (doc path=job:<id>)
build/install/codeloupe/bin/codeloupe env list                   # secret names, scopes and last use; never a value
build/install/codeloupe/bin/codeloupe env run --repo repo -- docker compose up   # a command with the secrets in its environment
build/install/codeloupe/bin/codeloupe status

Every command takes --root (default: the current directory), and codeloupe <command> --help lists its options. What each tool returns is in the Tools reference.

The first query in a repository builds its index (seconds); later queries take milliseconds. The daemon starts on the first CLI call; codeloupe start / stop manage it explicitly. codeloupe status prints the daemon's state as JSON (exit code 3 when it is not running); codeloupe repos add <folder>... makes it know a repository before the first question (Configuration).

A CLI call against a running daemon takes ~0.15 s. The start script maps a JVM AOT cache from <home>/aot/ (about 22 MB for the CLI, 51 MB for the daemon and 45 MB for its parse worker, per install and build). The daemon makes them in the background, a few seconds after it started and in a JVM of its own, so no call waits for it; until they exist (about 20-30 s) a call takes ~0.3 s, and a cache the JVM cannot use (another JDK, another build, a damaged file) is ignored without a message. The desktop app runs the bundled jar without the script and passes -Dcodeloupe.aot=auto, which names the same caches. Caches of an install that no daemon started from for 30 days are removed by the next training. codeloupe stop ends a training that is running. JAVA_OPTS / CODELOUPE_OPTS add JVM flags.

Where things live

State, indexes, logs and secrets live in the daemon's home (CODELOUPE_HOME; default %LOCALAPPDATA%\codeloupe, ~/Library/Caches/codeloupe or $XDG_CACHE_HOME/codeloupe). The daemon listens on 127.0.0.1:47391 only. Nothing is written into the repositories it indexes. Both are covered in Configuration.

Next

• Connect it to Claude Code: Claude Code integration.
• Learn how it answers and what it keeps in memory: Daemon and index.
• Something does not work: FAQ and troubleshooting.