trelix

Delete a persisted agent session and all its turn history.

List recent agent sessions for a repo, most recently active first.

Ask a question using the multi-turn ReAct agentic loop, with persistent memory. ⚠️ IMPORTANT: - repo_path must be an ABSOLUTE path to an already-indexed repository. - Session history is scoped to (repo_path, session_id) — a session_id created against one repo is invisible when querying a different repo_path. - Requires LLM configuration (e.g. OPENAI_API_KEY) — this tool always uses the agentic loop, unlike search_code which is retrieval-only. 🎯 When to Use: - Multi-step questions needing iterative retrieve/grep/get_symbol drilling. - Follow-up questions in the same conversation — pass back the session_id returned from the previous call to preserve context across calls. Session lifecycle: - Omit session_id on the first call — a new one is generated and returned. - Pass that session_id on subsequent related calls to resume with full turn history loaded from persistent storage. - Sessions are automatically evicted after TRELIX_RETRIEVAL_AGENT_SESSION_MAX_AGE_SECONDS of inactivity (default 7 days). Use agent_clear_session to delete one explicitly. Clarifying questions (SEP-2322, v3.3.0+): - When the agent's question is genuinely ambiguous, this tool returns an `InputRequiredToolResult` instead of the usual dict — an MCP client that supports SEP-2322 elicitation surfaces it as a form and resends this SAME call (same query/repo_path/session_id) with the answer attached as `inputResponses`; do not pass the answer as a new `query`. - A client that declines/cancels gets a normal dict answer back explaining the question could not be resolved — this tool never re-asks the same clarify question on a decline.

Find all symbols that depend on (call or import) a given symbol. Useful for impact analysis: "if I change X, what else might break?"

Build a knowledge graph for an indexed codebase. ⚠️ IMPORTANT: Run index_codebase first. repo_path must be absolute. 🎯 What this builds: - Unified code property graph (calls + imports + type hierarchy) - Community detection: clusters modules into architectural groups - Optional LLM concept extraction. extract_concepts=True is PAID: up to 10 LLM calls over the 200 most central symbols (batches of 20), and it requires an LLM API key. It does NOT cover the repository — on trelix's own 12,184-symbol index those 200 symbols are 1.6% of it — so concept_count describes that sample. Selection is by PageRank centrality descending, symbol id ascending. ✨ Returns: - node_count: number of symbols in the graph - edge_count: number of structural relationships - community_count: detected architectural clusters - community_summary: the largest clusters, size-ordered (see the caps below) - concept_count: concepts found in that sample, 0 unless extract_concepts=True - concept_symbols_considered / concept_symbols_total: the coverage those concepts came from — 200 of 12,184 on this repo. Both are 0 when extract_concepts=False, which is what distinguishes "extraction never ran" from "it ran over 200 symbols and found nothing"; concept_count=0 alone cannot tell those apart. community_summary used to ship every detected community, unsorted. Measured on trelix's own index that was **1,160,415 bytes — roughly 290,000 tokens** from a single tool call, larger than most context windows. 6,437 of the 6,497 entries (99.1%) were singleton communities carrying no architectural signal, while the five real clusters (514, 477, 393, 279, 277 nodes) accounted for almost none of the bytes. min_community_size=2 and max_communities=50 cut that to under 32 KB while keeping every significant cluster. Pass min_community_size=1 and max_communities=0 to restore the old uncapped array. singleton_count and communities_omitted are always reported: 6,437 singletons is a community-detection tuning problem, and capping the payload without saying so would hide it. NOTE this does not reduce the endpoint's real COST. Both this tool and GET /graph/communities call GraphBuilder(config).build() on every request — a full Louvain pass, a PageRank rebuild and two metadata saves — and that is untouched here.

Register a repo for federated search across MCP tool calls. ⚠️ IMPORTANT: - path must be an ABSOLUTE path. - Run index_codebase on it separately before federation_search_all can return results from it — registering a repo does not index it. - The registry is capped at TRELIX_FEDERATION_MAX_REPOS entries (default 50) to prevent unbounded growth from a scripted client.

List all repos registered for federated (multi-repo) search.

Unregister a repo from federated search by alias.

Search across ALL registered repos simultaneously (federated search). ⚠️ IMPORTANT: - Requires repos to already be registered via federation_add_repo AND already indexed (run index_codebase on each repo path beforehand). - Results are merged via Reciprocal Rank Fusion weighted by each repo's registered weight, then deduplicated. - Only the first TRELIX_FEDERATION_MAX_REPOS registered repos (default 50) are actually queried; repos_skipped reports how many were omitted. 🎯 When to Use: - Cross-service / cross-repo questions ("where is auth handled across our microservices?") - You don't know which of several registered repos contains the answer. 📄 Pagination: same cursor/k contract as search_code — pages are sliced from one fixed-width fetch, independent of cursor, so page contents are stable across calls (results don't shift/duplicate/vanish between pages the way a cursor-scaled fetch width would cause).

Look up a symbol by its fully-qualified name.

Graph-traversal search: find structurally related symbols by starting from semantically similar seeds and following code relationships. ⚠️ IMPORTANT: Run index_codebase and optionally build_knowledge_graph first. 🎯 When to use: - "What other code is connected to X?" — follow call/import/type edges - "Find the blast radius of a class" — who calls or imports it? - "What lives in the same architectural cluster as X?"

Index a repository for code search. Run once before calling search_code. ⚠️ IMPORTANT: - Stores the index in <repo_path>/.trelix/index.db (zero external infra). - Re-run to refresh after large code changes; incremental update is fast. ✨ Providers: - local — no API key, CPU-only, fast for small repos - openai — requires OPENAI_API_KEY, best quality - azure — requires AZURE_API_KEY + AZURE_ENDPOINT - voyage — requires VOYAGE_API_KEY, best code-specific quality Defaults to TRELIX_EMBEDDER_PROVIDER (or "local" if that's unset too). Progress notifications are sent if the MCP client supports them.

Search the indexed codebase using natural language queries. ⚠️ IMPORTANT: - repo_path must be an ABSOLUTE path to an already-indexed repository. - Run index_codebase first if you receive an error about a missing index. 🎯 When to Use: - Find specific functions, classes, or implementations - Understand architecture before making changes - Locate all callers of a function before refactoring - Find similar patterns to follow when adding code 📄 Pagination: - Use cursor=0 for first page (default). - If next_cursor is not null, pass it as cursor for the next page. - k controls page size. 🧭 Intent hint (optional): - If the calling agent already knows the query's intent, pass it as intent_hint (one of: symbol_lookup, file_overview, feature_flow, project_overview, comparison, config_lookup, dependency_map, blast_radius) to skip trelix's own internal LLM classification and route directly. An unrecognized value is never rejected — it falls through to normal classification. - hyde_snippet_hint (a short hypothetical code snippet) is only used when intent_hint is also valid.

Register a subscription for a trelix:// resource URI. MCP clients call this after receiving resources.subscribe=True in capabilities. When the resource changes (e.g. trelix watch detects a file edit), the server pushes notifications/resources/updated carrying only the URI — no content. The client then calls resources/read to fetch the updated content.

Deregister a resource subscription by its subscription ID.