Skip to content
Latch

Since the last run

Overall −3 points

langchain-ai/langchainjs (opens in a new tab)

Comprehensive agent toolkit with scaling friction: strong testing and docs, but monorepo sprawl and loose module boundaries demand navigation discipline.

TypeScript★ 17,826360 open issuesMIT License
Overall score: 70 out of 100
Holding

last scored 2026-06-21 · both lenses

Readiness lenses

The same repo, two ways: how ready it is for an AI coding agent, and for a human newcomer. Switch lenses to see each one's score and checks.

How ready the repo is for an AI coding agent to read, build, and operate it.

70 / 100

28 of 41 checks passed across 6 categories.

  • Machine Orientation

    76

    AGENTS.md is comprehensive and well-structured; README and package.json are clear; but core repo geometry and non-obvious entry points need better signposting for agents navigating the monorepo.

    The repo explicitly provides AGENTS.md with build commands (`pnpm --filter langchain build`), test commands (`pnpm --filter langchain test`), and a detailed monorepo map (Key Packages table). README.md correctly describes the project and links to external docs. package.json clearly pins pnpm@10.14.0 and defines test/lint/build scripts. However, an agent cannot easily discover *which* package to start with or understand the dependency graph without reading AGENTS.md sections on Prerequisites and Initial Setup, which state `pnpm --filter @langchain/core build` must run first—a critical ordering constraint that is stated but not machine-actionable in a config file.

  • Reproducible Setup

    72

    Pinned Node version, exact pnpm version, lockfile, devcontainer, and Docker Compose for testing present; agent can reproducibly install and run tests, but root-level Dockerfile missing and setup instructions sparse for first-time users.

    The repo has strong lockfile discipline (.nvmrc pinned to v24.6.0, packageManager pinned to pnpm@10.14.0, pnpm-lock.yaml committed), a populated devcontainer.json, and Docker Compose configs for environment and dependency-range testing. CI uses --frozen-lockfile and node-version-file, making builds deterministic. However, the root-level Dockerfile advertised in signals does not exist; devcontainer.json lacks a postCreateCommand to auto-install dependencies, and the README provides no explicit multi-step setup instructions (e.g., "pnpm install && pnpm build") that an agent would need without tribal knowledge.

  • Code Navigability

    62

    Large monorepo with strong naming and typed TypeScript, but root-level tsconfig is missing, module boundaries are loose and undocumented, and 2631 files exceed typical context windows for agent navigation.

    The repository is a TypeScript monorepo (pnpm workspaces with explicit workspace declaration) with conventional layout signals: clear pnpm lockfile, exact Node version pinning (.nvmrc v24.6.0), and turbo-driven build/test scripts. Package.json uses descriptive workspace paths (libs/*, libs/providers/*, internal/*) and strict TypeScript tooling (v6.0.3, oxlint, oxfmt). However, no root tsconfig.json exists to establish baseline type checking rules across the monorepo, and the detected 2631 files with unclear distribution across packages means an agent cannot easily determine which workspace owns which responsibility or identify module boundaries without reading workspace-level package.json files. The .devcontainer, docker-compose, and CI workflow presence (22 workflows) show environment clarity, but lack of an architecture document or llms.txt leaves module purpose and interdependencies implicit. This forces the agent to infer structure from file discovery rather than explicit declaration.

  • Verification Surface

    72

    Solid test and lint coverage with CI/CD integration, but missing root-level tsconfig and type-checking transparency, limiting agent feedback loop completeness.

    The repository has executable, machine-readable tests (vitest with unit/integration/bench modes), linting (oxlint with strict TypeScript rules), formatting (oxfmt), and 22 CI workflows that run on PRs and main—all critical verification surfaces. Tests are isolated by environment and type (*.int.test.ts, *.bench.test.ts, *.unit.test.ts) with explicit exclusions in test configs. Linting is mandatory in CI (codeql, oxlint --fix available). A major gap: no root tsconfig.json exists (detected as absent), only per-workspace tsconfigs via @langchain/tsconfig. This breaks monorepo-wide type-checking visibility and prevents an agent from understanding global type constraints without inspecting each workspace separately. Vitest has typecheck enabled but only in individual package configs, not coordinated at root.

  • Agent Safety

    72

    Solid secret hygiene and destructive-operation flagging; missing formal security policy and CODEOWNERS guard rails.

    The repo has strong foundational safety practices: `.gitignore` correctly excludes `.env` and `.env.local`, `.env.example` exists in the examples folder with clearly marked placeholders ("ADD_YOURS_HERE"), no committed `.env` files are detected, and `AGENTS.md` provides explicit agent guidelines including a no-`process.env` lint rule (except in tests). The `pnpm` overrides in `package.json` actively patch known vulnerable dependencies (tar, node-forge, minimatch, protobufjs, etc.). However, the repo lacks a committed `SECURITY.md` file (README references a shared one in `.github/`) and has no `CODEOWNERS` file to enforce reviewer approval on sensitive paths — critical guardrails for a 17k-star framework that agents will parse and modify.

  • Context Economy

    62

    Monorepo with 2631 files and explicit build outputs (.gitignore: dist/, lib/, dist-cjs/) excluded, but bulk test fixtures, environment test scaffolds, and generated lockfile remain untagged noise in the signal path.

    The repository explicitly excludes compiled outputs (dist/, lib/, dist-cjs/) via .gitignore and pins Node v24.6.0 and pnpm@10.14.0 exactly. The monorepo structure is conventional (libs/langchain, libs/core, libs/providers) and navigable with turbo-driven task organization visible in turbo.json. However, 2631 files include ~150+ environment test subprojects (test-exports-cf, test-exports-vercel, test-exports-bun, etc.), dependency_range_tests/, and examples/ — most are boilerplate or scaffolding without linguist markers (.gitattributes lacks export-ignore rules) to signal vendored/generated status to agents. The pnpm-lock.yaml itself is complete and correct, but the file tree density remains high relative to core signal.

  • Machine Orientation

    6 checks passed4 problems found

    • lowllms.txt present

      An llms.txt is the emerging machine-orientation standard — a curated map for LLMs.

      Fix: Add an llms.txt pointing at the key docs and entry points.

    • lowTopics set

      GitHub topics situate the repo's domain and stack for an agent at a glance.

      Fix: Add a few GitHub topics describing the domain and stack.

    • lowArchitecture doc

      An ARCHITECTURE doc hands an agent the module map instead of making it infer one.

      Fix: Add an ARCHITECTURE.md describing the major components and how they fit.

    • lowREADME shows usage

      A usage/example section tells an agent how the project is actually invoked.

      Fix: Add a Usage or Examples section to the README with a runnable snippet.

    • README present — An agent reconstructs what the repo is and how to work in it from the README first.
    • Agent instructions file — AGENTS.md / CLAUDE.md is the direct, machine-read channel for entry points and conventions.
    • Agent instructions stay lean — A bloated instructions file burns context and measurably hurts more than it helps.
    • Repository description set — The one-line description is the fastest orientation signal an agent reads.
    • Examples directory — An examples/ directory gives an agent runnable, copyable references for the API.
    • Contribution conventions are written down — A contributor guide is where an agent learns the branch, commit, and review conventions it must follow.

  • Reproducible Setup

    7 checks passed0 problems found

    • Lockfile committed — Without a lockfile two clones can resolve different dependency trees — the build isn't reproducible.
    • Runtime / toolchain pinned — An unpinned runtime makes an agent guess the version a clean environment needs.
    • Version pins are exact — A floating pin (a bare major, or a range) still drifts between installs.
    • Env template present — A .env.example tells an agent which configuration keys it must supply to run.
    • Container or dev-container — A Dockerfile / compose / devcontainer removes 'works on my machine' from setup.
    • Dev container — A .devcontainer gives an agent a one-command, fully-declared environment.
    • README documents setup — Explicit install/setup steps are what let an agent go from clone to running.

  • Code Navigability

    2 checks passed3 problems found

    • lowTypeScript strict mode on

      Strict typing gives an agent typed signatures to anchor an edit on, not guesses.

      Fix: Turn on `strict` in tsconfig.json.

    • lowFormatter configured

      A formatter config (Prettier/Biome/rustfmt/…) keeps style uniform across the tree.

      Fix: Add a formatter (Prettier, Biome, rustfmt, …) and commit its config.

    • lowTyped public API

      A declared `types` entry gives an agent typed signatures to anchor an edit on.

      Fix: Ship type declarations and point package.json `types`/`typings` at them.

    • Conventional source layout — A recognised src/ · lib/ · app/ layout lets an agent localise code without spelunking.
    • .editorconfig present — An .editorconfig keeps whitespace and encoding consistent, so diffs stay legible.

  • Verification Surface

    5 checks passed2 problems found

    • lowTask runner present

      A Makefile / Taskfile / justfile gives an agent a single index of the project's commands.

      Fix: Add a Makefile / Taskfile / justfile collecting the common commands.

    • lowTypecheck command

      A typecheck script lets an agent catch type errors before they ship.

      Fix: Add a `typecheck` script (e.g. `tsc --noEmit`).

    • Tests present — Runnable tests are the ground truth an agent checks its own edits against.
    • Test command defined — A `test` script is the documented, discoverable way to run the suite.
    • Lint command defined — A linter an agent can run catches a class of mistakes before they ship.
    • CI configured — Readable CI is the feedback loop an agent reads to know what 'green' means here.
    • Build command — A documented build command is the discoverable way for an agent to produce artifacts.

  • Agent Safety

    6 checks passed2 problems found

    • mediumSecurity policy

      A SECURITY.md is where an autonomous security agent reads this repo's rules before acting on it.

      Fix: Add a SECURITY.md stating the disclosure channel and the repo's security rules.

    • lowCODEOWNERS present

      CODEOWNERS marks the 'don't touch without review' zones an agent should respect.

      Fix: Add a CODEOWNERS file marking the sensitive paths.

    • No committed .env — A tracked real .env hands secrets to anything — including an agent — that reads the repo.
    • No exposed secrets — Secret-shaped literals in tracked files are a live credential leak.
    • .gitignore covers env files — An ignore rule for .env is what keeps the next careless commit from leaking secrets.
    • Automated dependency updates — Dependabot / Renovate keeps dependencies patched without a human in the loop.
    • .gitignore present — A .gitignore is the first guard against an agent committing secrets or build junk.
    • License makes the code reusable — Without a license an agent cannot safely copy, redistribute, or vendor any of this code.

  • Context Economy

    2 checks passed2 problems found

    • lowGenerated / vendored files marked

      A .gitattributes linguist marker tells tools (and agents) what to skip.

      Fix: Mark generated/vendored paths in .gitattributes (linguist-generated / linguist-vendored).

    • lowNo oversized source file

      A single file in the hundreds of KB blows past an agent's effective context window.

      Fix: Split the largest files along their natural seams.

    • Dependencies not vendored in — A committed node_modules / vendor tree drowns the real signal an agent needs.
    • Build output not committed — Generated dist/ · build/ output is noise an agent has to read past.

Where the grip slips

  1. highReproducible Setup+3 pts if fixed

    No root-level Dockerfile; devcontainer setup not automated

    Signals claim a root-level Dockerfile, but it does not exist in the repo. The devcontainer.json references a Microsoft image but has postCreateCommand commented out; an agent must infer that 'pnpm install' is required. This blocks deterministic local setup without guessing.

    Fix: Uncomment and populate postCreateCommand in devcontainer.json with 'pnpm install && pnpm build', or create a root-level Dockerfile that copies pnpm-lock.yaml and runs pnpm install --frozen-lockfile.

  2. highVerification Surface+2 pts if fixed

    No root-level tsconfig.json for monorepo type-checking visibility

    The repository is a pnpm workspace monorepo with 2631 files but lacks a root tsconfig.json. Type-checking is delegated to individual workspace packages (@langchain/tsconfig), making it impossible for an agent to verify global type coherence or run a unified type pass without parsing each workspace config. This fragments the feedback loop.

    Fix: Create a root tsconfig.json extending @langchain/tsconfig/base.json with references to all workspace packages (libs/langchain, libs/langchain-core, etc.) and include it in CI as `pnpm tsc --noEmit` or equivalent to establish a monorepo-wide type baseline.

  3. mediumReproducible Setup+2 pts if fixed

    Missing explicit setup instructions in README

    README jumps to 'npm install -S langchain' (publishing the package) without documented steps for contributors to clone, install, and build from source. Agents cannot infer monorepo topology or build order from prose alone.

    Fix: Add a 'Development Setup' section to README with explicit steps: clone → 'pnpm install' → 'pnpm build' → 'pnpm test:unit', linked to CONTRIBUTING.md and devcontainer setup.

  4. highCode Navigability+2 pts if fixed

    Undocumented module boundaries and responsibilities

    The pnpm-workspace.yaml declares 4 workspace patterns (libs/*, libs/providers/*, examples, internal/*), but no central document explains what each workspace owns (e.g., is @langchain/core in libs/ or libs/providers/? What is internal/ for?). The file tree shows 2631 files with no visible structure legend.

    Fix: Add a top-level ARCHITECTURE.md or docs/REPO_STRUCTURE.md that lists each workspace, its exports, primary responsibilities, and key modules. Use concrete examples (e.g., 'libs/core: RunnableSequence, prompt templates' vs. 'libs/providers/openai: OpenAI model integrations'). Include a dependency graph or workspace relationship diagram.

  5. mediumVerification Surface+1 pts if fixed

    Type-checking not explicitly surfaced in PR/main CI workflows

    While vitest.config.ts enables typecheck, the CI workflows (ci.yml, unit-tests-langchain.yml) do not explicitly call type-checking as a distinct, failing step. An agent cannot easily see whether type errors block merge or are warnings-only.

    Fix: Add explicit `pnpm tsc --noEmit` or `turbo tsc` step in ci.yml and unit-tests-langchain.yml that fails the build if type errors exist, and document this in the README under 'Verification'.

  6. mediumVerification Surface+1 pts if fixed

    Vitest typecheck mode unclear in CI and not documented for agents

    vitest.config.ts sets typecheck: { enabled: true } but this runs only during local test invocation, not explicitly in any CI job. It's unclear if CI's `turbo test` or `vitest run` triggers typecheck or if it runs in parallel with tests. No documentation clarifies this.

    Fix: Document in README under Verification that `pnpm test:unit` includes type-checking, or decouple it into a separate CI step with explicit output so an agent can observe type-check results independently.

  7. lowReproducible Setup+1 pts if fixed

    pnpm overrides define security patches but lack inline justification

    package.json includes extensive pnpm.overrides (e.g., 'tar>=7.5.11', 'esbuild>=0.25.0') without comments explaining *why* these versions are pinned. An agent cannot verify the intent or detect stale pins.

    Fix: Add inline comments to each override block in package.json explaining the vulnerability or compatibility reason, e.g., '// CVE-2024-XXXXX: tar RCE' or '// esbuild regex DOS in <0.25.0'.

  8. mediumCode Navigability+1 pts if fixed

    Missing root tsconfig.json

    No root-level TypeScript configuration exists to document baseline compilation settings, strict mode defaults, or path aliases across the monorepo. Agents must infer or guess per-workspace overrides.

    Fix: Create a root tsconfig.json with strict: true, explicit path aliases for major workspace boundaries (e.g., @langchain/core, langchain), and clear references to workspace tsconfigFiles. Document as a required reference for all workspace members.

  9. mediumCode Navigability+1 pts if fixed

    No root TypeScript path aliases defined

    Without a root tsconfig with paths and path mapping, agents cannot quickly resolve import statements like `import { RunnableSequence } from '@langchain/core'` back to the source file location without manual directory traversal.

    Fix: In root tsconfig.json, define and document all workspace export paths (e.g., '@langchain/core': ['libs/core/src/index.ts'], '@langchain/anthropic': ['libs/providers/anthropic/src/index.ts']). Ensure this is inherited or explicitly set in all workspace tsconfigFiles.

  10. mediumCode Navigability+1 pts if fixed

    File count (2631) and distribution opacity exceed typical agent context window

    With 2631 files across an unknown distribution of workspaces, an agent cannot quickly map a feature request (e.g., 'add a new chat model') to the relevant package without discovering or reading many workspace package.json files and entry points.

    Fix: Publish a file inventory or codebase map (e.g., codebase-map.json or docs/FILE_STRUCTURE.md) that groups files by workspace and function (core abstractions, model integrations, utilities). For each workspace, list primary source directories and file count.

  11. mediumContext Economy+1 pts if fixed

    Missing .gitattributes export-ignore for vendored/generated patterns

    .gitattributes file exists but does not use linguist or export-ignore directives; it only contains 'end_of_line' and 'insert_final_newline'. No indication that test fixtures, lockfiles, or build scaffolding are machine-generated or non-core.

    Fix: Populate .gitattributes with: '*.lock export-ignore', 'pnpm-lock.yaml export-ignore', '.turbo/ export-ignore', 'environment_tests/** export-ignore', 'dependency_range_tests/** export-ignore', and 'examples/** linguist-documentation'.

  12. mediumContext Economy+1 pts if fixed

    Test environment projects committed without export-ignore markers

    environment_tests/ contains 20+ test subdirectories (test-exports-cf, test-exports-vercel, test-exports-node-classic, test-zod-compat, etc.) with nested package.json, tsconfig.json, and src/ trees. .gitattributes exists but lacks linguist-documentation or export-ignore rules to signal these as scaffolding rather than source. An agent must parse and filter these manually.

    Fix: Add to .gitattributes: 'environment_tests/** export-ignore' and 'environment_tests/** linguist-documentation' to exclude from source context and IDE indexing. Optionally move to a separate ci-fixtures/ branch or separate test-matrix artifact.

  13. mediumMachine Orientation+1 pts if fixed

    Monorepo entry-point and build order not codified in automation

    AGENTS.md documents that @langchain/core must build before other packages, but this is only stated in prose. Turbo config does enforce dependencies via `dependsOn: ["^build:compile"]`, which is correct, but an agent must read AGENTS.md to know @langchain/core is the root; no llms.txt or architecture doc exists.

    Fix: Add brief llms.txt or architecture document (100–200 words) naming @langchain/core as the foundational package and linking to libs/ structure. Alternatively, add a top-level diagram to AGENTS.md with a visual dependency tree.

  14. highAgent Safety+1 pts if fixed

    No CODEOWNERS file

    A 2631-file monorepo with dozens of integration providers and internal packages has no CODEOWNERS configuration to enforce mandatory review on sensitive paths (e.g., core runnables, secret/credential handling, CI workflows).

    Fix: Create .github/CODEOWNERS with entries for: libs/langchain-core/, libs/langchain/, libs/providers/*, internal/, .github/workflows/, and any auth/credential modules, each assigned to maintainers.

  15. mediumAgent Safety+1 pts if fixed

    No repository-level SECURITY.md

    README delegates to a shared SECURITY.md at langchain-ai/.github but this repo has no local policy file. Agents reading the repo cannot determine the security reporting path without leaving the repository boundary.

    Fix: Commit a SECURITY.md at the repository root (or symlink/copy from parent) with clear instructions for reporting security issues privately, signed disclosure process, and supported versions.

  16. lowVerification Surface

    No explicit test-execution guarantee visible in main CI for all packages

    test:unit:ci runs `turbo test` but CI has path-ignore filters (docs, dependency_range_tests, environment_tests) that may skip tests for unchanged packages. An agent cannot easily verify which tests ran or which were skipped without parsing turbo logs.

    Fix: Add a summary step in CI (e.g., `turbo test --output-logs new-only --only-changed=false`) or document the test execution model explicitly so an agent knows which packages' tests were verified.

  17. lowContext Economy

    dependency_range_tests/ is structural noise without clear scope marking

    The dependency_range_tests/ directory parallels environment_tests/ with 15+ shell scripts, docker-compose.yml, and nested package.json templates for testing dependency resolution. These are CI-only and not part of the buildable codebase, but lack explicit markers.

    Fix: Add 'dependency_range_tests/** export-ignore' to .gitattributes and document in CONTRIBUTING.md or a CI/test infrastructure guide that these are dependency matrix artifacts, not source.

  18. lowContext Economy

    examples/ directory is large and unfiltered in monorepo context

    examples/src/ includes 50+ detailed example files (createAgent, cache patterns, langchain-classic chains, extraction) that are valuable for users but add context weight for an agent tasked with understanding core repo structure. No .gitattributes rule marks this as documentation-only.

    Fix: Mark examples/ with 'examples/** linguist-documentation' in .gitattributes to reduce context weight in IDE/agent indexing. Alternatively, link to examples in docs/ or a separate org repo.

  19. mediumMachine Orientation

    Incomplete guidance on test execution and environment setup

    AGENTS.md lists test commands (`pnpm --filter langchain test`) but does not state which tests are unit vs. integration, or which require API keys. The examples/.env.example file exists but is not referenced in AGENTS.md; agents will not know to copy it or set environment variables without trial and error.

    Fix: Add a section to AGENTS.md titled 'Running Tests' that states: (1) unit tests run without external APIs; (2) integration tests require API keys from examples/.env.example; (3) copy examples/.env.example to examples/.env and fill in keys for integration tests.

  20. lowMachine Orientation

    No documented entry points for code exploration or common workflows

    An agent reading AGENTS.md learns the package structure but not what to do first—e.g., where to read to understand Runnables, where to start a simple agent project, or how to add a new integration. The sections reference abstractions (Runnables, Messages, Tools) but do not link to source files or examples.

    Fix: Add a 'Getting Started for Agents' subsection in AGENTS.md with: (1) link to libs/langchain-core/src/runnables/base.ts for Runnable interface; (2) link to examples/src/createAgent/ for agent examples; (3) list the 3 most critical source files for a minimal understanding.

  21. lowMachine Orientation

    AGENTS.md does not mention required environment variables for core development

    The file lists test commands that may require API keys (e.g., test:integration) but provides no guidance on which keys are needed for which tests or how to set them. This forces agents to infer or read CI workflows to understand dependencies.

    Fix: Add a subsection 'Environment Variables' to AGENTS.md listing: API_KEY variables used by tests and which tests require them (e.g., OPENAI_API_KEY for test:integration in @langchain/openai).

  22. lowAgent Safety

    Agent guidelines exist but not machine-verifiable

    AGENTS.md documents best practices (no process.env, no explicit any) but these are prose guidelines, not enforced at parse time. An agent could read the codebase and encounter violations without detectible boundaries.

    Fix: Supplement AGENTS.md with a .agent-safety file (or tool config) listing blacklisted patterns (e.g., 'process.env' outside tests, destructive npm scripts), or ensure lint rules are runnable before agent execution.

Show your score

Latch badge
[![Latch score](https://latch.fyi/api/badge/2fba28bf-f8ae-4627-8955-5170e73fd032)](https://latch.fyi/langchain-ai/langchainjs)

Share this analysis

https://latch.fyi/langchain-ai/langchainjs

Fixed some issues? Re-analyze to measure your progress →

Copy the whole report

Grab the entire verdict in one go — a Markdown block for a README or an issue, plain text, or a prompt you can paste straight into an LLM.

Was this verdict fair?

One tap helps — or tell us more.

← Analyze another repo