eulerian

Real-time code navigation for AI agents and editors. eulerian keeps a live symbol index — files, classes, functions, methods, constants, with line ranges — so an agent can jump straight to a definition instead of grepping or reading whole files.

Two ways to point it at code:

• Local mode — watch a real working directory. A filesystem watcher re-parses files the moment they're saved; the index never goes stale and there's no explicit re-index step. Every query also runs a synchronous, cheap mtime-diff catch-up first (LocalWatcher.sync()), so a query issued immediately after a save — with no delay — never races ahead of the watcher's debounce window and returns pre-edit state.
• Repo mode — register a git remote, check out a (user, repo, ref) worktree, and browse it without touching your actual working tree. Freshness is checked against the remote on each call instead of pushed live, since nothing is editing the worktree directly.

Both modes share one in-memory symbol index and the same tree-sitter parsing core. Python, Java and Go today; additional grammars are straightforward to add — see parser.py.

Install

uv tool install eulerian
# or
pip install eulerian

No other runtime dependencies beyond tree-sitter, tree-sitter-python, tree-sitter-java, tree-sitter-go, rapidfuzz, watchfiles, fastmcp, and typer — all pulled in automatically.

CLI

# Local mode: one-shot queries against a directory, no persistent watcher
eulerian status [PATH]
eulerian outline QUERY [PATH] [-k N]
eulerian find SYMBOL [PATH]

# Local mode: live watch + MCP server (stdio by default, for an MCP client)
eulerian watch [PATH] [--http --host HOST --port PORT]

# Repo mode: register, checkout, browse
eulerian repo add URL
eulerian repo list
eulerian repo fetch REPO
eulerian repo checkout REPO REF [--user NAME]
eulerian repo outline REPO REF QUERY [--user NAME] [-k N]

MCP server

eulerian watch [PATH] starts a FastMCP server (stdio or --http) exposing:

Local mode — watch(path), unwatch(path), outline(query, paths, root, k, format), find(symbol, root), references(symbol, root, regex, max_results), callers(symbol, root, depth), callees(symbol, root, depth), call_path(source, target, root, max_depth), imports(file, root), read(path, start, end, root, segments), status(root).

Repo mode — repo_add(url), repo_fetch(repo), repo_list(), repo_pubkey(), checkout(repo, ref, user), checkout_close(repo, ref, user), git_log(repo, ref, user, n), repo_outline(repo, ref, query, paths, user, k, format, reset_head), repo_read(repo, ref, path, user, start, end, segments, reset_head), repo_references(repo, ref, symbol, user, regex, max_results, reset_head), repo_callers(repo, ref, symbol, user, depth, reset_head), repo_callees(repo, ref, symbol, user, depth, reset_head), repo_call_path(repo, ref, source, target, user, max_depth, reset_head), repo_imports(repo, ref, file, user, reset_head).

Point any MCP-capable client (Claude Code, etc.) at eulerian watch <path> to get instant, line-precise code navigation without burning tool calls on grep/read round-trips.

references/repo_references complement outline/find, which only match definitions in the symbol index: they grep the watched directory's or worktree's file contents directly for call sites, imports, type hints, decorators, and any other textual mention of a symbol, defaulting to whole-word matching (pass regex=True for a raw pattern instead).

callers/callees/call_path/imports (and their repo_* counterparts) walk a structural call/import graph instead, built from the CallEdge/ ImportEdge records the parser resolves during parsing — same-file calls and calls through a tracked import alias. They're precise where they resolve at all, but resolve less than references() finds textually: instance-method calls on untracked objects, decorators, and other dynamic call forms aren't in the graph. depth/max_depth walk multiple hops (depth=1 is direct callers/callees only); call_path finds the shortest path between two symbols, one per matching start node.

Indexing scope and .gitignore

Every file walk — the initial full scan, the local watcher's live filter, and repo_references's grep — honors .gitignore recursively (nested .gitignore files and global excludes included) whenever the root is a git working tree, via git ls-files/git check-ignore. Registered-repo worktrees always qualify; a locally watched directory only gets this treatment if it's itself a git repo. On top of that, a fixed set of noise directories (.venv, node_modules, __pycache__, build, dist, etc. — see parser.SKIP_DIRS) is always excluded, gitignored or not.

Repo-mode configuration

Bare clones and worktrees live under ~/.eulerian/ by default:

repo_add clones with --filter=blob:none (blobless partial clone) — the full commit/tree graph is fetched up front so any ref still resolves and checks out, but file content is fetched lazily per worktree instead of for the entire history. This cuts clone time and disk use substantially on repos with a lot of history/blob volume. Falls back to a full clone automatically if the remote doesn't support partial clone.

Architecture

parser.py        tree-sitter Python + Java + Go parser -> Symbol / CallEdge / ImportEdge
index.py         in-memory Index, keyed by an opaque handle, rapidfuzz search
sources/local.py watchfiles watcher  -> handle = resolved root Path
sources/repo.py  bare clone + worktree lifecycle -> handle = (user, repo, ref)
mcp/             FastMCP server exposing both modes as tools
cli.py           typer CLI

Index doesn't care what a handle is — local mode and repo mode just pick different shapes for it. Both feed the same outline/find query surface.