CodeclewFind code. Follow the thread.

Find your next thread
Architecture · from source to explanation

From repositories
to explainable threads.

Codeclew turns source and build configuration into facts an agent can inspect, connect and cite. The agent supplies the engineering question and writes the explanation; Codeclew preserves where each answer came from.

A curious cat following a bright blue thread of yarn
The evidence pipeline

Each stage adds information
and keeps its limits visible.

Analysis starts with an explicit target: a JVM compilation, a Cargo target, Python source roots or a TypeScript configuration. A repository can contain several targets. Each keeps its own source inputs and evidence limits.

  1. 01 · Capture

    Repository → snapshot

    Pin committed source and repository state. Explicit committed mode permits a checkout with local edits while excluding those edits from the snapshot. Hash the inputs so later answers refer to the same bytes.

    Snapshot implementation ↗
  2. 02 · Describe

    Build → compilation model

    The selected profile identifies source roots and relevant build or parser inputs. Compiler profiles also record dependencies, toolchain and options.

    BuildModelProvider contract ↗
  3. 03 · Analyze

    Model → language facts

    Kotlin and Java use compiler analysis. Rust and Python provide bounded syntax facts. TypeScript and JavaScript use the project-local TypeScript compiler, with explicit limits for unchecked JavaScript.

    Kotlin adapter ↗
  4. 04 · Seal

    Facts → reusable generation

    Store facts by content digest with a completeness receipt. Reuse them only when their input authority still matches.

    Generation lifecycle ↗
  5. 05 · Connect

    Generation → bounded context

    Retrieve declarations, source anchors and supported relations. Framework rules derive Spring roots; thread services connect selected members.

    Context implementation ↗
  6. 06 · Explain

    Context → engineering document

    The agent follows a root, records evidence and names unresolved steps. A reader can distinguish a compiler fact from a proposed interpretation.

    Explore an example →
Optional change path

For an admitted mutation capability: context → immutable edit plan → isolated candidate and validation → reviewed publication. Analysis access alone never enables writes.

Preparation implementation ↗
Where a computational thread begins

Start with the trigger,
then follow the callable.

HTTP handlers, Kafka listeners and scheduled jobs are roots of application work. A useful catalogue preserves the repository, revision, compilation, callable identity, source location and annotation evidence for each root.

HTTP

RequestMapping and method shortcuts describe routes and request conditions. Class and method paths combine; inherited and composed annotations need resolved identities.

Kafka

KafkaListener, containers and KafkaHandler describe subscriptions and dispatch methods. A topic expression is retained separately from its runtime value.

Scheduling

Scheduled and Schedules describe cron, rate and delay triggers. Repeated schedules stay separate; a disabled or dynamic value stays visible.

Rules recognize stable Spring annotation identities rather than a Spring Boot patch number. K2 extraction handles Kotlin annotation resolution; framework interpretation is a separate layer above language facts. The Java Compiler API also extracts Spring attributes and inherited class registrations into the common catalogue contract.

A root is evidence of a declaration. Bean registration, active profiles, property placeholders, SpEL, proxies and programmatic registrations may require configuration or runtime evidence. Matching an HTTP path or Kafka topic between repositories does not prove a call. “All roots” must state which repositories, compilations and extraction capabilities were covered.

After opening an analysis session, list its computation roots. For a bound multi-repository thread, use the second command instead.

clew entrypoints --session <session-id> --limit 100
clew entrypoints --thread <thread-id> --limit 100

Repeat --session to select several sessions. Continue with the returned --cursor until nextCursor is null; the cursor binds every page to the same catalogue. Keep each scope's coverage and unresolved boundaries in the resulting documentation.

Spring catalogue acceptance and scope ↗

Work with a real developer checkout

Select the committed snapshot.
Keep local edits in place.

For read-only analysis, --committed explicitly selects committed HEAD even when the checkout has local changes. Codeclew reports that those changes are excluded and leaves the checkout intact. Carry the same option from discovery into context or navigation admission.

clew doctor repository --repo <repository> --committed
clew context open --repo <repository> --committed \
  --target-ref <returned-ref> --language kotlin \
  --profile <returned-profile> --compilation <returned-compilation> \
  --operation analysis --intent "Document Spring roots" --term <root-name>

Use the exact profile and compilation returned by discovery. For saved Kotlin or Rust edits, use working-tree analysis. Committed mode remains read-only; managed changes have separate profile and freshness requirements.

See how committed analysis was checked on a private Spring service →

When analysis needs attention

Recover at the stage
that reported the problem.

Repository or build

Read the returned next action. For local edits, select committed analysis explicitly. For dependency, authentication, TLS or JDK errors, run the project wrapper locally and fix that build prerequisite before reopening context.

Runtime or profile

Use the named doctor command and clew capabilities --human to inspect the installed runtime. Update with clew upgrade when appropriate. Ordinary baseline analysis can use the core engine; an unavailable exact pack should remain a visible capability limit.

Evidence or navigation

An internal evidence rejection is a Codeclew validation failure to investigate. Retain its private diagnostic and validation stage. After an upgrade, reopen context to use the updated query index; use the exact returned symbol when a short name is ambiguous.

Conditional Kotlin analysis preserves the project compiler version separately from the packaged analyzer. Keep that difference and unresolved boundaries in the document. A successful command alone does not prove that runtime registrations or cross-service calls were observed.

Diagnostic and recovery runbook ↗

Know what the result can establish

Source facts have different strengths.

Compiler analysis

Resolves supported declarations and relationships using language and build inputs. Missing dependencies and unsupported constructs can still leave gaps.

Syntax analysis

Locates what is written in source without claiming runtime or compiler resolution. Rust macros and Python's dynamic behavior remain explicit limits.

Cross-service explanations

Combine source evidence with engineer-declared interactions. A matching route or topic alone does not prove a running integration.

Check language and feature support →. Run clew capabilities --human for your installed runtime's exact contract.

Who does what

A precise tool.
An accountable engineering agent.

Codeclew

Captures inputs, extracts language facts, derives supported framework facts, binds source evidence, limits retrieval, reports gaps and checks freshness. For admitted writes, it isolates and validates a candidate before publication.

The agent and engineer

Choose the scope, inspect returned evidence, decide which computational thread matters, investigate unresolved boundaries and write its explanation. They review behavior and validation before approving a change.

Contributor guide

Have another thread to follow?

Add a build provider, language adapter, framework rule or user workflow. Start with a small capability, define its evidence and verify it through the public interface.

Read the guide to extending Codeclew →