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 tu…

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. When the server runs with --root or TRELIX_ALLOWED_REPO_ROOTS, a registered repo outside those roots is not listed or counted, and every response carries repos_outside_roots (how many were left out).

Unregister a repo from federated search by alias. When the server runs with --root or TRELIX_ALLOWED_REPO_ROOTS, a registered repo outside those roots cannot be removed: its alias is answered exactly like an unregistered one, and the registry file is not written.

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). A registered repo with no index is skipped, not searched, and not counted in repos_searched; repos_unindexed names its alias, and if none of the queried repos is indexed, error says so. - 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 the server runs with --root or TRELIX_ALLOWED_REPO_ROOTS, a registered repo outside those roots is not searched, and every response carries repos_outside_roots (how many were left out). 🎯 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). k is clamped to 1..TRELIX_MCP_MAX_K, a negative cursor is an error, and the text is capped at TRELIX_MCP_MAX_RESULT_CHARS (see search_code). 🪶 Detail: detail="concise" drops each body and returns a one-line signature.

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?" 📏 Size: - k is the most results, from 1 up to TRELIX_MCP_MAX_K (default 50). - detail="detailed" (default) returns each body (first 600 chars); detail="concise" returns a one-line signature instead. - The list is capped at TRELIX_MCP_MAX_RESULT_CHARS characters (default 15000). When results are left out, the result carries a second text block saying so and `_meta.trelix` has total_available and omitted.

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). A negative cursor is an error. - If next_cursor is not null, pass it as cursor for the next page. - k controls page size, from 1 up to TRELIX_MCP_MAX_K (default 50); page_size in the response is the k the server used. - The response text is capped at TRELIX_MCP_MAX_RESULT_CHARS (default 15000). When results are dropped to fit, truncated is true, omitted counts them and next_cursor points at the first dropped result. 🪶 Detail: - detail="detailed" (default) returns each result's body (first 800 chars). - detail="concise" drops body and returns a one-line signature instead. 🧭 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. Registers the URI in this server process's in-memory subscription registry. The server does not advertise resources.subscribe and does not serve resources/subscribe, so this tool is the only way to register. A notifications/resources/updated (URI only, no content) is sent for a registered URI only if a file watcher runs inside this server process; nothing starts one today, so none is delivered yet.

Deregister a resource subscription by its subscription ID.