Coding agents write a lot of code, quickly, and logging is the first thing they skimp on: a print here, a logger.info("done") there, and nothing that would help anyone figure out what went wrong a week later. Logika doesn't try to extract meaning from those logs afterwards. Instead, it works on the agent while it codes: it tells it what to log, checks that it did, and gives it the tools to read the result.
What to log: state transitions
Logs are for a later diagnosis: by Logika, by an agent, or by someone querying them and thinking. So every text Logika gives your agent (the section logika init writes in AGENTS.md, the skills, the reviewer) says the same thing: wherever the code creates, updates, deletes, moves, charges, sends, retries or gives up on something, log an event naming the entity, its identity, its values before and after, and the cause.
with tracer.start_as_current_span(
"order.status_changed",
attributes={"order_id": order.id, "status_before": old, "status_after": new, "cause": "payment_captured"},
):
order.status = new
That one span answers questions nobody has asked yet: which orders went from placed to cancelled without a refund, how long they sit in pending, what usually causes a move to failed. It's plain OpenTelemetry; nothing in your code depends on Logika.
What the agent is not asked for while coding is rules about what must hold. Those can only check what was recorded, and they're written well only against what the code really emits, so they wait for reflection.
How it's named: conventions
Each component in logika.json's map carries its conventions: where its state transitions happen (files, or an ast-grep pattern), the span helpers it uses, and how its events, identity and before and after params are named. The agent that instruments the component writes them, and amends them as it learns. logika check holds every change to them, in any component that has them.
"conventions": {"transitions": [{"files": "orders/**/*.py"}], "helpers": ["traced"],
"events": "order.*", "identity": "order_id",
"before": "*_before", "after": "*_after"}
After it codes: the check and the reviewer
Your agent runs logika check when it's done, and the stop hook logika init installs runs it at the end of every session. It works in two layers.
The mechanical layer runs every time and launches nothing. It validates logika.json, runs the mechanical rules over the code (an undeclared span, a dynamic span name, an attribute of the wrong type, add_event on a declared span, a swallowed exception, pii without a key, stale bindings), the only findings that block; holds the change to its components' conventions, as warnings: a changed function at a transition site that logs nothing (unlogged-transition), an event that misses its naming, its identity, or a before without its after (event-convention); and lists the changed files outside every component, to map or exclude.
The reviewer layer runs only from the stop hook or logika check --review, and only when the change touches source in a component marked "instrumented": true, changes at least 3 lines of real code, and is a diff it hasn't reviewed before. Then Logika's reviewer runs once: your own agent command (claude -p unless LOGIKA_AGENT says otherwise), headless and read-only, which reads the diff with the component's conventions and the ledger and says which transitions aren't logged yet, and exactly how to log them. Your main agent never has to load Logika's documentation into its context. The hook hands the findings over, and your agent fixes what applies or says why it doesn't. LOGIKA_REVIEW=off turns the reviewer off.
Once a day at most, check also names an instrumented component whose transition sites changed a lot since logika.json last did (200 lines, or 5 functions with no event), and asks the agent to instrument it again with the logika-instrument skill (LOGIKA_NUDGE=off turns that off).
Instrumenting what's already there
Instrumenting existing code is a different job, done by the logika-instrument skill. The agent maps the repository's components; you pick which to instrument, or all of them. For each one, it chooses a strategy (spans in the body of each operation, a middleware, decorators, consumers and jobs, scripts and batch work, the logging that's already there), lists the component's state transitions, writes the component's conventions (with the strategy in its own words in notes), and marks it "instrumented": true. From then on the reviewer reads every change to it, and the daily nudge watches it drift; a component nobody has started on draws neither. Logika judges nothing about logging in the abstract; it holds the agent to the conventions it chose.
What static analysis can't see, production shows. Every night, instrumentation feedback looks at what actually arrived: optional params that are always null, spans that carry no app version, names your code sends that the ledger doesn't declare, dimensions with too many values, sustained delivery loss, an enhancer too old to trust. Each finding is an item in the console, with a Fix it button that sends your agent at it.
Tools to investigate
An agent investigating a problem needs to see the system run, in a form it can read. Logika's CLI is built for that: dense output, a few fields per line, JSON in and out.
logika query: everything pending, at a glance;logika query item <id>, one issue with its evidence.logika query journey <span-id>: the span tree around a span, with the log records each one emitted.logika query sql "<sql>": DuckDB SQL over everything stored, with a view per declared event ("checkout.captured", its params as columns) besideevents,logsandmetrics.logika query series,breakdown,actives,retention,funnel,milestone: the analytics, for how something changed over time.logika test "<command>": runs your tests (or your app) with a local capture, shows the events through their messages, and judges them againstlogika.jsonas it is on disk, before anything is deployed.logika replay '<json>'judges the same capture, or stored traces, again with events failed, delayed, duplicated or dropped: what would Logika raise if the code misbehaved?logika docs <term>: the documentation, on demand, a short article at a time; it ships with the CLI, so it always describes the commands your agent actually has.
None of this calls a model on our side: the reviewer and the fixer are your agent, on your subscription, and Logika is the deterministic part around them.
Next: the new paradigm, where the rules come in.