LogicTrail
or type your own

Ask your codebase how it works.

In Claude Code, /logictrail:explain traces the path your code actually takes, through components, routes, services, database calls, events and external APIs, and walks you through it with the file and line behind every step.

Install in Claude Code

What the plugin does
  • /plugin marketplace add werlen-nevio/LogicTrail
  • /plugin install logictrail@logictrail
Then ask
/logictrail:explain how does checkout work?

Prefer a terminal? npx logictrail "how does checkout work?"

The trail, in the sample app

    The real viewer, live

    This is the file LogicTrail writes: one offline HTML page per question. These three come from the sample shop in the repository, traced by static analysis with no API key. Click a step for its source, callers and callees, or an edge for the line that proves it.

    Full screen

    Every step cites the code

    An edge is drawn because a line of code makes the call. When a link is likely but no line proves it, LogicTrail still shows it, dashed, with how sure it is and why.

    Proven by a call site

    authController.login()callsfindUserByEmail()

    17const user = await findUserByEmail(email);

    server/src/controllers/authController.ts:17

    Inferred, not proven

    Stripe: paymentIntents.createwebhookPOST /api/webhooks/stripe

    60%

    “Stripe delivers webhook events to POST /api/webhooks/stripe, whose handler processes Stripe webhooks.” No call site can prove it: Stripe calls the webhook from outside the codebase.

    Claude chooses, the code decides
    Claude picks and describes steps only inside the part of the code graph that static analysis found. A step it returns that the analysis did not find is dropped.
    No API key needed
    Without ANTHROPIC_API_KEY, static analysis selects the flow and writes the explanation from code facts and doc comments.
    What is sent to Claude
    The question, the candidate steps (names, paths, signatures, doc comments), the edges between them and excerpts of the most relevant functions: about 60k characters at most. --model static keeps everything on your machine.

    Built for Claude Code

    Claude runs LogicTrail in your project, reads a compact outline of the flow and checks the source at the steps that matter, so the answer stays on the path the code takes.

    /logictrail:explain

    Ask how something works, or start from a route, a function or a file. Claude answers in a few sentences, then walks the path step by step, calls out the branches and marks inferred links.

    When Stripe reports a failed payment, the webhook marks the order failed, puts the reserved stock back and emails the customer.

    1. POST /api/webhooks/stripe runs handleStripeWebhook() server/src/payments/stripe.ts:17
    2. switch (event.type) sends payment_intent.payment_failed to markOrderFailed() server/src/payments/stripe.ts:29
    3. It writes order.update, calls releaseInventory() and emits order.paymentFailed server/src/services/orderService.ts:30
    4. notifyPaymentFailed() sends the email through Resend server/src/email/send.ts:21

    An example on the sample shop, shortened. Claude's wording varies; the steps and lines come from the trace.

    /logictrail:update

    After the code changes, Claude re-runs your saved flows with the question they were made with and tells you what changed in the path: new and removed steps, connections gained or lost, steps that moved.

    ✓ what-happens-when-a-payment-fails: steps 1 added, 3 moved; edges 1 added

    + paymentAttempt.create (database) server/src/services/orderService.ts:35

    ~ markOrderFailed() server/src/services/orderService.ts:30 → :32

    What logictrail update reports after a database write is added to markOrderFailed(). Claude reads it and explains the change.

    The plugin page Install

    Or run it yourself

    The same engine as a command line tool for any JavaScript or TypeScript project. It needs Node.js 22 or newer, and npx runs it without installing anything.

    • npx logictrail "how does checkout work?"
    Output Flag What you get
    HTML --output html One offline file: pan, zoom, search, node details, source, evidence, light and dark themes, deep links.
    SVG --output svg A standalone image with light and dark styles.
    Mermaid --output mermaid A flowchart for GitHub, GitLab, Notion and docs.
    JSON --output json The full graph, with evidence and source snippets.

    Start from anywhere

    • --route "POST /api/orders"The flow behind an HTTP route, including its callers
    • --function createSessionFrom a function, method or component
    • --file src/auth/login.tsFrom the entry points of a file
    • logictrail updateRe-run every saved flow against the current code

    Static analysis does the selection by default. Set ANTHROPIC_API_KEY to let Claude choose the steps and write the explanation. Full documentation

    Changelog

    The CLI and the Claude Code plugin share one version number. Releases on GitHub

    Unreleased

    Added

    • --show-prompt prints the prompt LogicTrail would send to Claude (the system prompt, the candidate steps, the edges and the source excerpts) without sending it or writing any files. It needs no API key. buildFlowPrompt does the same in the library API.
    • A JSON Schema for the graph output, schema/graph-v1.schema.json. JSON files point to it with $schema, and the package exports it as logictrail/graph.schema.json.
    • Routes for Fastify (fastify.get, fastify.route, route hooks and register prefixes), Hono (app.route sub-apps and basePath), Koa (@koa/router and koa-router prefixes and nested router.routes()) and NestJS (@Controller methods decorated with @Get, @Post and so on, plus app.setGlobalPrefix). Each route records its framework and is matched by --route and by client requests like an Express route.

    0.2.0

    Added

    • logictrail update [flow...] re-runs the flows saved in .logictrail/ with the question or starting point and the limits they were made with, rewrites them in the formats they were saved in (an SVG keeps its theme) and lists the steps that were added, removed or moved, and the connections gained or lost between them.
    • Saved flows record how they were requested (request in the graph JSON), so they can be re-run.
    • updateFlow, findSavedFlows, loadSavedFlow, diffFlows and hasChanges in the library API.
    • A Claude Code plugin. /logictrail:explain runs LogicTrail on a question and walks you through the flow, citing the file and line behind every step; /logictrail:update re-runs saved flows and explains what changed. Install it with /plugin marketplace add werlen-nevio/LogicTrail and /plugin install logictrail@logictrail.

    Changed

    • New logo. The HTML viewer's header and favicon and the README use the Two Steps mark in Waymark Yellow and Ink; the brand kit is in docs/brand.

    0.1.0

    Initial release.

    Added

    • logictrail "<question>" turns a plain-English question about a JavaScript or TypeScript codebase into the execution flow behind it (components, API routes, services, database calls, events, external APIs and the branches between them), with the file and line behind every step.
    • --route, --file and --function start a flow from an HTTP route, a file or a function instead of a question.
    • Output as an interactive HTML viewer, SVG (light, dark or auto theme), Mermaid and JSON. --open opens the result in the browser and --stdout prints a single format.
    • Works without an API key through static analysis. With ANTHROPIC_API_KEY set, Claude selects the flow and writes the descriptions and explanations (--model picks the model).
    • Framework adapters for Express, Next.js, React, React Router, HTTP clients, ORMs and database drivers, event emitters and queues, and external APIs such as Stripe and Resend.
    • logictrail.config.ts configuration, a per-file analysis cache and a library API (analyze, writeOutputs).

    Two commands away

    In Claude Code

    Plugin details
    • /plugin marketplace add werlen-nevio/LogicTrail
    • /plugin install logictrail@logictrail