tentra

Create a new, versioned architecture diagram from a set of services, connections, and (optionally) external actors, and return a shareable web URL. Use instead of describing an architecture in chat: whenever the user asks to design, plan, sketch, or document any system/feature/integration, call thi…

Mutate an existing architecture — bump its version, snapshot the prior state as a version record, and replace whichever top-level fields you pass. Use instead of create_architecture whenever you already have an architecture id in context from a previous call, list_architectures, or the URL. Unlike …

Fetch ONE architecture by ID with the full services + connections + flows graph inline. Use instead of list_architectures when you already know the ID and need the contents (e.g. before calling update_architecture, or to re-explain an existing diagram). list_architectures returns IDs + names only f…

List every saved architecture in this workspace as a lightweight summary (id + name + version + createdAt + URL), newest first. Use for BROWSING / DISCOVERY — "what have I designed already?", "find an architecture named X". Unlike get_architecture, this does NOT return services or connections; once…

Scan a local monorepo / project directory, auto-detect its services (from package.json, docker-compose, pom.xml, go.mod, Python configs), infer their connections (from deps, imports, env vars, docker depends_on), and materialize the result as a new Tentra architecture diagram in one shot. Use when …

Run 8 architecture-quality rules against a saved diagram and return a severity-tagged list of issues (errors / warnings / info). Rules covered: orphan_node, duplicate_connection, dangling_connection (references non-existent service), naming_convention (snake_case IDs), god_service (>6 connections),…

Diff a saved Tentra architecture against the current state of a local codebase and return a drift report: services added / removed / changed, connections added / removed, plus a 0–100 accuracy score. Use when the user asks "is my diagram still accurate?", "what's drifted?", or after significant ref…

Render a saved architecture as runnable code scaffolding, Mermaid, docker-compose, or an ADR markdown document and either stream it back as text or write it to disk. Use when the user asks to "scaffold / generate / export / materialize" a diagram. Text formats (mermaid, markdown-adr, docker-compose…

Append an ordered step-by-step walkthrough (a "flow") to an existing architecture — e.g. a checkout request path, a data pipeline, or a failure-recovery procedure. The flow is rendered as an animated sequence on the canvas that highlights services and edges as the user steps through it. Use wheneve…

Walk a local repo, extract symbols + call/import/reference edges via Tree-sitter (TypeScript, JavaScript, Python, Go, Java, Rust), and upload them to Tentra as a new immutable snapshot. This is what turns a raw checkout into a queryable code graph. WRITE PATH, LONG-RUNNING (seconds on small repos, …

Drive the tier-2 indexing loop forward: check a job's progress and either mark it done (when every file has been processed) or return the remaining file count so the agent knows it should send another batch of record_semantic_node calls. Use ONLY after index_code with tier="tier2" or tier="both" re…

Persist ONE agent-inferred semantic annotation (a one-sentence purpose + domain tags + confidence + optional semantic role) for a single file OR single symbol in an indexing job, and advance that job's progress cursor by 1. This is the write side of tier-2 indexing: after index_code (tier2/both) re…

Read-only status lookup for an indexing job: tier, status, snapshotId, totalFiles, processedFiles, lastBatchCursor, createdAt, completedAt. Use when you need to INSPECT a job without advancing it — e.g. to report progress to the user or to decide whether a previously-started job is still in flight.…

Search the indexed code graph for symbols (functions, classes, methods, interfaces, types, variables) by name or qualified name. The structural-search entry point: returns resolved symbol IDs (with fanIn/fanOut ranking) that every other read-path tool accepts — grep returns text matches, query_symbo…

Return every resolved caller / importer / inheritor of a single symbol from the code graph — the refactor-safety tool. Use before renaming or deleting a symbol to see exactly who depends on it. Unlike query_symbols (which takes a NAME and returns candidate symbols), find_references takes a KNOWN sy…

Return a structured PATCH PLAN for renaming a symbol — definition site + every call site with exact file paths and line ranges — so the calling agent can apply the rewrite with its own Edit/MultiEdit tools. The canonical "rename without breaking hidden callers" tool. Unlike find_references (which o…

Produce an agent-ready narrative walkthrough of a whole repo — "what is this codebase?" answered in a single tool call from the indexed code graph. The onboarding tour: Start here / Structure / Architectural hotspots / Domains / Decisions / Contracts / Snapshot info, all assembled from data we alrea…

Breadth-first traverse the code graph starting from one symbol to return its local neighborhood: what it calls, what calls it, what it imports, inheritance / implementation relationships. Answers "how does this work?" structurally — grep finds the symbol; get_symbol_neighbors tells you what it actua…

Return the full code subgraph that belongs to ONE Tentra canvas service: every file mapped to that service, all the symbols in those files, and the edges leaving those symbols (including cross-service edges). Use when the user has an architecture diagram and asks "what code is in the payment_servic…

Compute the SHORTEST call/import/reference chain between two given symbols in a snapshot, and annotate each intermediate hop with its record_semantic_node purpose (when available). Answers "how does X reach Y?" / "is A actually connected to B?". Unlike get_symbol_neighbors (which explores around ON…

Run a cosine-similarity search over agent-generated embeddings stored via record_embedding. Pass a pre-computed query_vector (you must embed your text first with your own embedding capability — this tool does NOT embed for you) and optionally restrict by entity_type or snapshot_id. Returns the most …

Persist ONE pre-computed embedding vector for a file or symbol so it becomes searchable via find_similar_code. You must produce the vector yourself (the agent embeds the source_text with whatever model it has access to) — Tentra stores vector + source_text + model identifier but does not call any em…

Return the top-N most coupled symbols in a snapshot — those with the highest fanIn + fanOut — as a ranked list. Surfaces architectural smells: utility modules that "know too much", classes every other class depends on, etc. Unlike get_quality_hotspots (which ranks FILES by churn × complexity × (1 −…

Rank FILES by a composite refactor-priority score: cyclomaticComplexity × (1 + churn30d/100) × (1 − testCoverage/100). High score = complex, frequently changed, poorly tested — the files most likely to break. The canonical "what should I refactor next?" list. Unlike list_god_nodes (which ranks SYMB…

List every code-graph snapshot stored for a given repo, newest first — each row has id, commitSha (when index_code ran inside a git working tree), createdAt, parentSnapshotId, and a stats blob. Use to TIME-TRAVEL through the repo's history: pick a snapshot_id from this list and feed it to any read-…

Compute a structural diff between two snapshots of the same repo: files added / removed / modified (by contentHash), symbols (qualifiedNames) added / removed, and god-node changes (appeared / resolved). Effectively a commit-range architectural diff that answers "what actually changed between these t…

Declare which Tentra canvas service owns which files in a specific snapshot — in one batched call. Each mapping is (relative file path → service id); every matching CodeFile row has its serviceId column updated. This is the bridge between the code graph (files, symbols, edges) and the architecture …

Tag one file, symbol, or service as belonging to a business domain (e.g. "payments", "identity", "fraud"). Supports both AI-inferred (source="ai", lower confidence) and human-confirmed (source="human", confidence 1.0) assignments. Upserts: if the same (domain_id, entity_type, entity_id) tuple alread…

Persist a service contract — an OpenAPI spec, proto file, GraphQL schema, event schema, Kafka/RabbitMQ topic schema, etc. — as a first-class entity in the code graph, so you can then attach code symbols to it via bind_contract and query it via get_contracts. Use once per contract per version. The c…

Link a code symbol to a contract with a typed relation: "provides" (symbol implements the contract, e.g. a handler that serves the OpenAPI endpoint), "consumes" (symbol calls the contract, e.g. a client that hits the endpoint), or "documents" (symbol describes the contract, e.g. a type definition ge…

List every Contract stored in a workspace, newest first, with each row including a count of its bindings. Optionally filter by kind (http / grpc / event / graphql / rabbit / kafka). Use for BROWSING the workspace's contract inventory — "what API contracts do we have?", "show every Kafka topic schem…

Persist an Architecture Decision Record (ADR) — slug + title + status + context + decision + consequences — as a first-class row in the code graph, with support for supersession (auto-marking an older decision "superseded") and immediate entity links (services, files, symbols, contracts, domains). …

Attach an EXISTING decision (from record_decision) to one more entity — a service, file, symbol, contract, or domain — with a typed relationship: "motivates" (decision caused this entity to exist), "constrains" (decision limits how it can evolve), "documents" (decision explains it), "implements" (en…

Look up every ADR that is linked to a specific entity — useful for answering "why is this service / file / symbol the way it is?" while reviewing code. Returns every linked decision with its full context + decision + consequences + link kind. Use proactively in code review: before changing a servic…

Mid-implementation alignment check: given files you just changed and a saved architecture, return what the spec says about that work — which services those files belong to (via set_service_mapping), the spec's declared edges in/out of each, ADRs that motivate or constrain them, and drift signals (fi…

Resolve the owning team(s) for a given file path according to the workspace's CODEOWNERS-style rules (longest-match-wins with explicit priority). Returns a list of team or user handles. Use to answer "who owns this file?" / "who should review this change?" / "who should I ping about this bug?". Own…