Open source · Apache 2.0 · Java 17+

Code is the log.
Stop writing logging statements.

NarrativeTrace turns your running code into readable narratives — execution traces for humans who debug, and safe, token-efficient runtime context for AI agents that write code.

Get started in 5 minutes View on GitHub

implementation("ai.narrativetrace:narrativetrace-core:0.1.0")

build/narrativetrace/customer_places_order.md

# Customer places order- OrderService.placeOrder("C-42", qty: 5) — 4.2ms  - Customers.verifyGoodStanding("C-42") → true  - PricingService.calculate(5) → 49.95  - PaymentService.charge(card: [REDACTED])    → PaymentConfirmation(txId="T-9")  - OrderRepository.save(Order{…})    → Order{id=ORD-1001, total=49.95} // Zero log statements were written for this.

0log lines in your business logic

~10 nsper-call overhead when tracing is off

15–30%fewer tokens when AI agents read your code

0runtime dependencies in the core

Before & after

Delete the logging. Keep the story.

Logging statements are a third of a typical service class — and they still miss the one thing you needed. NarrativeTrace captures method names, parameters, return values, and call structure automatically. The code you already wrote is the narrative.

Before — logging everywhere

public Order placeOrder(String customerId, int qty) {
    log.info("Placing order for {} qty {}", customerId, qty);
    customers.verifyGoodStanding(customerId);
    log.debug("Customer in good standing");
    var price = pricing.calculate(qty);
    log.info("Calculated price: {}", price);
    var order = repository.save(new Order(customerId, price));
    log.info("Order saved: {}", order.getId());
    return order;
}

After — code is the log

public Order placeOrder(String customerId, int qty) {
    customers.verifyGoodStanding(customerId);
    var price = pricing.calculate(qty);
    return repository.save(new Order(customerId, price));
}

// Zero log lines.
// NarrativeTrace captures the narrative
// automatically.

Generated trace — Markdown, JSON, prose, or sequence diagram

narrative trace

- OrderService.placeOrder("C-42", 5)
  - Customers.verifyGoodStanding("C-42") → true
  - PricingService.calculate(5) → 49.95
  - OrderRepository.save(Order{…}) → Order{id=ORD-1001, total=49.95}

For AI-assisted development

Your AI agent can read the code.
Now it can watch it run.

Vibe coding works until something breaks and nobody — human or agent — knows what actually happened at runtime. NarrativeTrace gives coding agents ground truth: the real call tree, not a guess reconstructed from static reading.

Runtime truth, not guesswork

Agents debugging from source alone infer behavior — and infer wrong. A narrative trace shows what ran, in what order, with what parameters and results. Paste it into any agent's context, or attach the per-test trace files your CI already produces.

More logic per context window

Log statements are noise tokens. Removing them makes a service class 15–30% cheaper for an agent to read — and every line of a trace carries signal, because it was generated from names, not prose.

Injection-safe by design

Narrative/value separation keeps untrusted runtime values structurally apart from the story. Redaction is built in, and the structure-only output level ships zero user data to a model — safety by construction, not by filter.

How separation works

MCP server Pro Coming soon

Claude Code, Cursor, and Copilot will query traces, runtime dependency graphs, and clarity data directly over the Model Context Protocol — read-only, with tiered output levels that default to structure only.

Preview the MCP design

This site is agent-friendly too: point your assistant at llms.txt or llms-full.txt and it can adopt NarrativeTrace for you.

For legacy modernization

Migrate the system nobody understands — with receipts.

AI agents make rewrites cheap; verifying them is the expensive part. Wrap a legacy system in traces and you get its real runtime behavior — before you change it, and proof of equivalence after.

X-ray the architecture you actually have

Run the existing tests — or just the app — under NarrativeTrace and read what really happens, call by call. No documentation archaeology, no tribal knowledge required. JUnit 4 support included, because legacy means JUnit 4.

Prove behavior didn't change Pro

Migration diffs compare trace sets from before and after a refactor, port, or AI-assisted rewrite — detecting divergences and classifying each by risk. Behavioral equivalence stops being a feeling and becomes a report.

Migration diffs

Expose hidden coupling Pro

Runtime dependency graphs aggregated from real executions: solid edges for always-called dependencies, dashed for conditional ones with frequencies. Circular dependencies and god services have nowhere to hide.

Dependency graphs

Find the code that reads worst

If the trace doesn't read well, the code is lying about itself. Clarity scoring grades naming quality from the runtime narrative and points your refactoring — or your agent's — at the worst corners first. Free tier.

Clarity diagnostics

How it works

Three steps to your first narrative

Add two dependencies

dependencies {
  implementation(
    "ai.narrativetrace:narrativetrace-core:0.1.0")
  implementation(
    "ai.narrativetrace:narrativetrace-proxy:0.1.0")
}

Wrap a service — or auto-wrap

var context = new ThreadLocalNarrativeContext();
var service = NarrativeTraceProxy.trace(
    orderService, OrderService.class, context);

// or for Spring:
@EnableNarrativeTrace(
    basePackages = "com.example.app")

Read the story

service.placeOrder("C-42", 5);

System.out.println(
  new IndentedTextRenderer()
      .render(context.captureTrace()));

// JUnit 5/4: every test writes
// its own trace file.

Editions

Free for humans. Paid for AI scale and compliance.

The boundary is simple: reading traces as a developer is free, forever, Apache 2.0. Cross-run analytics, AI integration at scale, and compliance-grade auditing are paid.

Open Source Available now

Everything one developer needs, with zero runtime dependencies in the core.

Automatic tracing: proxy, Java agent, Spring, servlet
All five capture levels, runtime-switchable
@Narrated, @OnError, @NotTraced annotations + redaction
JUnit 5 & JUnit 4 per-test trace files
Markdown, JSON, prose & sequence-diagram output
Clarity scoring & SLF4J bridge

Get started

Pro Early access

Cross-trace analytics, AI integration, and compliance for teams.

Flow summaries & path frequency analysis
Migration diffs with risk classification
Runtime dependency graphs
Audit & SecOps events with policy engine
MCP server for coding agents — coming soon
Tiered AI output levels — coming soon

Request early access

Platform Coming soon

Hosted backend for narratives from every service, environment, and run.

Managed OTLP ingest for traces
Multi-tenant storage & search
Team dashboards & retention policies
Org-wide clarity & audit reporting

Join the waitlist

Full comparison in the Pro overview. Open-source artifacts are on Maven Central under ai.narrativetrace.

Integrations

Meets your stack where it is

Spring Boot 0.1.0

JUnit 5 0.1.0

JUnit 4 0.1.0

Java Agent 0.1.0

SLF4J 0.1.0

Micrometer 0.1.0

Servlet 0.1.0

Diagrams 0.1.0

Micronaut Next release

OpenTelemetry Next release

Gradle Plugin Next release

Clarity CLI 0.1.0

Beyond Java

One architecture, every runtime

Narrative capture, dual-consumer output, and clarity diagnostics — the same design, ported.

JavaAvailable now

.NETIn development

TypeScriptIn development

PythonPlanned

Give your code a voice.

Five minutes to your first narrative. No log statements were written in the making of this library.

Get started Star on GitHub

Code is the log.Stop writing logging statements.