dagayn

DAG is All You Need — a knowledge-graph-centered approach to code review and impact analysis.

dagayn is a fork of code-review-graph focused on practical AI-assisted review for polyglot repositories, especially infrastructure-heavy codebases.

This fork keeps the graph-centered review model from the upstream project, but it is documented and maintained as its own product. The most visible differences are first-class Terraform support, commit-pinned grammar fetching for fork-specific parsing, broader platform-install flows, and a stronger focus on monorepos that mix application code, docs, and infra.

What dagayn does

dagayn parses your repository into a local SQLite knowledge graph. It records files, symbols, references, call edges, imports, test links, communities, and execution flows. AI agents can query that graph instead of re-reading the whole repository on every task.

In practice, that means:

• smaller review context windows
• faster impact analysis
• safer refactors
• better navigation across large repositories
• a single workflow for code, docs, notebooks, and Terraform

Fork status

dagayn is explicitly a fork of code-review-graph.

It does not treat upstream documentation as canonical. All project guidance, examples, and command descriptions in this repository are written for dagayn itself.

See NOTICE for upstream attribution and original author information.

Highlights

• first-class Terraform parsing for .tf and .tfvars
• Markdown structure and dependency extraction, including directive comments and dagayn: documentation links
• notebook parsing for .ipynb and marimo .py / .md notebooks
• native Japanese FTS (Lindera IPADIC morphemes plus CJK bigrams), so inflected queries still AND-match
• incremental graph updates, watch mode, worktree sync, and session prepare
• MCP server for AI coding tools
• graph queries for impact radius, review context, communities, flows, and refactors
• native Rust graph store, parsers, FTS, flows, and post-processing (dagayn._core)
• multi-repo registry and daemon workflows
• GraphML, Mermaid C4, SVG, Cypher, and Obsidian graph exports

Supported languages and file types

dagayn covers mainstream application languages plus repo-adjacent formats.

Highlights include:

• Python, JavaScript, TypeScript, TSX, Go, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Solidity, Dart, Lua, Luau, Objective-C, Bash, Elixir, Zig, PowerShell, Julia, Perl, R, GDScript, Vue, Svelte, Astro
• Markdown
• Jupyter notebooks, Databricks notebook sources/exports, and marimo .py / .md notebooks as graph inputs
• Terraform

See docs/FEATURES.md and docs/LLM-OPTIMIZED-REFERENCE.md for the current coverage summary.

Terraform support

dagayn treats Terraform as a first-class language alongside application code. Both .tf and .tfvars files are parsed by a dedicated Tree-sitter grammar.

Parsed block types

Edge types produced

• REFERENCES — any var.x, local.x, module.x, output.x, provider.x, data.type.name, or resource_type.name expression inside a block body. The parser extracts these with a dedicated regular expression and skips Terraform built-in prefixes (count, each, path, self, terraform).
• CALLS — built-in function calls such as merge(…) or length(…).
• IMPORTS_FROM — the source attribute in module and terraform required_providers blocks, and the target of import blocks.
• CONTAINS — file to every block defined in it.
• DEPENDS_ON — required_providers version constraints in terraform blocks.

Cross-module analysis

When a module block references a local path in source, dagayn records an IMPORTS_FROM edge from the calling module to the target directory. This lets impact-radius queries cross module boundaries.

.tfvars files

Variable value files (.tfvars) are parsed as Terraform. Their top-level attribute assignments become var.name nodes linked to the corresponding variable block in .tf files via REFERENCES edges, giving the graph a complete picture of variable data flow.

Markdown support

dagayn extracts graph nodes and edges from Markdown documentation alongside source code, so prose architecture decisions and code they describe appear in the same graph.

Parsed node types

Heading slugs follow the GitHub Markdown convention: lowercase, spaces and hyphens collapsed to -, non-alphanumeric characters removed. Duplicate headings within a file get a numeric suffix (slug-1, slug-2, …).

Edge types produced

• CONTAINS — heading hierarchy. A level-2 heading that appears under a level-1 heading is recorded as a child of that section.
• REFERENCES — inline or reference-style links between sections: [text](./other.md#heading) or [text](#local-heading). Source is the containing section; target is resolved to file::slug form.
• IMPORTS_FROM — cross-file links. When a link or directive points to a different Markdown file, an IMPORTS_FROM edge is added from the current file to the target.
• DEPENDS_ON — directive comments (see below).

Directive comments

Directive comments are HTML comments with a structured form that express inter-document dependencies machine-readably:

<!-- constrained-by ./decisions/adr-001.md#context -->
<!-- blocked-by ./specs/open-issue.md -->
<!-- supersedes ./old-api.md#endpoint-design -->
<!-- derived-from ./research/background.md#findings -->

Supported directive kinds:

Each directive becomes a DEPENDS_ON edge. The markdown_directive_kind edge attribute records the specific directive type for downstream filtering.

Documentation directives (dagayn:)

HTML comments of the form <!-- dagayn: implemented-by path::symbol --> create CROSS_ARTIFACT edges from a Markdown section to a code (or other artifact) target. Supported kinds include implemented-by, discusses-artifact, and raises-issue-for. Code can point the other way with line comments such as # dagayn: implements docs/spec.md#Section.

See docs/MARKDOWN-AUTHORING.md for the full contract.

Link resolution

The parser handles:

• [text](./relative/path.md#section) — resolved relative to the source file
• [text](#local-section) — resolves to the same file
• [ref]: path reference-definition style
• External URLs (http://, https://, mailto:) are ignored

Installation

pip install dagayn

For a persistent isolated CLI environment, uv tool install works too:

uv tool install dagayn

For an isolated one-shot CLI, uvx works well:

uvx --from dagayn dagayn --help

Published wheels include the compiled extension for supported targets, so the normal PyPI install paths do not require building from the Git repository.

If you prefer persistent isolated tool installs, pipx also works.

Quick start

dagayn install
dagayn build
dagayn status

install auto-detects supported AI coding platforms and writes MCP configuration where appropriate. Run without arguments on a TTY to be prompted for an embedding mode (see below); under -y or a non-TTY stdin the mode must be passed explicitly.

build creates the initial graph.

Use dagayn build --force-full-build (or --force) when you want to delete the existing graph database before rebuilding from scratch.

status confirms the graph exists and reports basic counts.

Choosing an install mode

dagayn install supports these embedding strategies as first-class options:

# 1. FTS only — no embeddings, fastest, no model download.
dagayn install --mode fts-only

# 2. Local — managed BGE-M3 llama.cpp GGUF sidecar.
dagayn install --mode local-embedding

# 3. Managed Qwen3 llama.cpp GGUF sidecar.
dagayn install --mode local-embedding-llama --preset low    # Qwen3-Embedding-0.6B (~1 GB)

# 4. Remote — OpenAI-compatible / Google / MiniMax cloud embeddings.
dagayn install --mode remote-embedding --provider openai
dagayn install --mode remote-embedding --provider google
dagayn install --mode remote-embedding --provider minimax

For --mode remote-embedding, set the provider's environment variables in the shell that launches your AI coding tool (e.g. CRG_OPENAI_API_KEY, CRG_OPENAI_BASE_URL, CRG_OPENAI_MODEL for openai); the MCP server inherits those at launch time and the generated dagayn serve --remote-embedding <provider> entry makes MCP search use that provider automatically. The exact env-var list is printed at install time. Legacy install shortcuts such as --mode fts, --mode local, --mode local --preset low, --mode llama-qwen3, --mode remote, and --local-embedding low still work as aliases for the new explicit mode names.

Native graph store

The graph store, parsers, FTS, flows, and post-processing run in the native Rust extension (dagayn._core). There is no Python graph engine to fall back to: DAGAYN_BACKEND=python is rejected. Hybrid search ranking and manifest-bridge extraction stay in Python.

Parsers cover Markdown, Terraform, Rust, Python/notebooks, Bash, Go, Java, Ruby, C#, PHP, Kotlin, Swift, Scala, Solidity, Dart, Lua, Luau, C / C headers / Perl XS, C++, Objective-C, Elixir, GDScript, R, Julia, Perl, Vue, Svelte, Zig, PowerShell, extensionless shebang scripts for supported scripting languages, and core JavaScript / JSX / TypeScript / TSX / Astro files:

dagayn build
dagayn update

Source checkouts without the native extension fail clearly.

Common CLI flows

dagayn build
dagayn update
dagayn watch
dagayn worktree sync
dagayn detect-changes --base HEAD~1
dagayn visualize --format graphml
dagayn serve

MCP tool surface

dagayn serve exposes a compact default workflow surface: the main tools plus dispatcher tools such as review_tool, flow_tool, and architecture_analysis_tool, so routine sessions no longer need named server profiles.

dagayn serve
dagayn serve --tools query_graph_tool,semantic_search_nodes_tool

--tools is an exact comma-separated allow-list for deployments that need to hide some public tools. Persistent server configs can use CRG_TOOLS for the same control.

Tool responses use a calibrated guidance contract. Compatibility fields such as status, summary, _hints, and next_tool_suggestions remain, while review, architecture, flow, refactor, search, and query responses can also include guidance, answerability, and missingness. Guidance items carry claim, evidence, confidence, missingness, action, reason_codes, and counts so agents can treat graph output as evidence-ranked leads rather than verdicts. Use detail_level="minimal" for the top recommendations and detail_level="standard" for the full supporting sections. query_graph_tool zero-result and not-found responses include zero_result_reason, next_action, result_count, results, answerability, and missingness; treat absence as graph-limited until source or tests confirm it. Documentation bridge results label evidence as authored, extracted, or heuristic_reachable so Markdown traceability is not confused with a verified contract.

Reporting and export outputs

dagayn visualize exports static graph artifacts.

• --format is required and supports graphml, mermaid-c4, svg, cypher, and obsidian
• mermaid-c4 emits Mermaid C4Component code with files collapsed into components and cross-file relations
• svg export uses matplotlib, so install the eval extra when you need it: pip install "dagayn[eval]"
• Jupyter / Databricks / marimo notebooks are parsed as graph inputs, not emitted as report formats

AI platform integration

dagayn install can configure MCP for these targets:

• Codex
• Claude / Claude Code
• Cursor
• Windsurf
• Zed
• Continue
• OpenCode
• Antigravity
• Qwen Code
• Kiro
• Qoder
• Pi
• Hermes Agent

You can limit installation to a single platform with --platform <name>. For Codex, install also creates global ~/.codex/hooks.json and enables hooks in ~/.codex/config.toml so the graph refreshes during Codex sessions. Claude hooks are written to global ~/.claude/settings.json. Installed git hooks run dagayn update --skip-flows before commit-time checks and a full dagayn update after each commit. When a local embedding install mode is selected, generated AI-tool update hooks also pass the same local embedding sidecar arguments so edit-time refreshes keep vectors current.

Platform-specific instruction files are also installed where needed:

• Claude uses ~/.claude/CLAUDE.md
• Codex uses ~/.codex/AGENTS.md
• OpenCode uses ~/.config/opencode/AGENTS.md
• Qoder uses QODER.md
• --platform qcoder is accepted as an alias for qoder

How the graph is used

A typical review loop looks like this:

1. build or update the graph
2. ask for minimal context or a change review
3. inspect only the affected files and symbols
4. follow communities, flows, or cross-file references as needed
5. refresh incrementally after edits

The graph is stored locally under .dagayn/ by default. No external database is required.

Semantic search and embeddings

semantic_search_nodes combines exact/name search with embedding-backed fuzzy search when embeddings are available, and falls back to FTS-only search when they are not. It reports which search path contributed through search_mode and per-result source fields. Native FTS segments Japanese with Lindera IPADIC morphemes (plus dictionary base forms) and overlapping CJK bigrams, so an inflected query such as 検索する AND-matches 検索を行う.

For implementation details such as FTS indexing, RRF merge, reranking, text modes, and provider setup, see docs/ARCHITECTURE.md#hybrid-search and docs/LOCAL-EMBEDDINGS.md.

Embedding modes and providers

The openai provider speaks the standard /v1/embeddings schema, so it works with real OpenAI, Azure OpenAI, LiteLLM, vLLM, LocalAI, Ollama (in OpenAI mode), and similar gateways. When CRG_OPENAI_BASE_URL points to localhost the cloud egress warning is suppressed automatically.

Vector search uses the Rust native cosine-similarity backend by default. It computes dot products with architecture-specific SIMD intrinsics directly in Rust (NEON on aarch64, AVX with SSE fallback on x86_64, and a scalar fallback elsewhere), so no external BLAS or Accelerate library is required. Set DAGAYN_EMBEDDING_SEARCH_BACKEND=auto to fall back to the Python path when native search is unavailable, or DAGAYN_EMBEDDING_SEARCH_BACKEND=python for A/B testing. The Python path uses an optional numpy BLAS matmul when numpy is installed (pip install "dagayn[numpy]") and otherwise a pure-Python cosine loop — numpy is never a required hard dependency. dagayn serve --local-embedding runs BGE-M3 through a managed llama.cpp GGUF sidecar so acceleration stays out of the Python process. The older sentence-transformers/PyTorch provider="local" mode has been removed; local embedding now means the managed llama-server sidecar or another localhost OpenAI-compatible endpoint.

Running embedding

Call embed_graph_tool via MCP (or let your AI agent call it after build_or_update_graph_tool). For fully local embeddings, prefer dagayn build --local-embedding, dagayn update --local-embedding, or dagayn serve --local-embedding; these manage llama-server and then use the OpenAI-compatible localhost endpoint internally. Pass provider and optionally model only when using an already configured provider.

dagayn build --local-embedding
embed_graph_tool(provider="openai")   # reads CRG_OPENAI_* from env
embed_graph_tool(provider="google")   # reads GOOGLE_API_KEY from env
embed_graph_tool(provider="minimax")  # reads MINIMAX_API_KEY from env

Embeddings are stored in the embeddings table inside .dagayn/graph.db. Switching provider, model, or DAGAYN_EMBEDDING_TEXT_MODE partitions the cache and triggers a re-embed for that provider/text-mode pair on the next call.

Search quality

The current search benchmark has 20 queries: 12 standard queries for exact/name and purpose-style lookup, plus 8 structural queries for purpose and process-pattern prose over function behavior.

On the 8 structural queries, narrative improves over material from 0.2881 to 0.5875 MRR and from 3/8 to 7/8 Hit@5. See docs/LOCAL-EMBEDDINGS.md#search-quality for the detailed benchmark tables, search-mode notes, and local model comparison.

Privacy and cloud egress

Before sending any data to a cloud provider, dagayn prints a warning to stderr listing what will be transmitted (function names, docstrings, file paths). To acknowledge once and suppress the warning in subsequent runs:

export CRG_ACCEPT_CLOUD_EMBEDDINGS=1

To stay fully offline, use --local-embedding so dagayn manages a localhost llama-server endpoint. No Python ML stack or PyTorch dependency is required.

Documentation map

• docs/USAGE.md — installation and day-to-day workflows
• docs/RECIPES.md — copy-paste recipes for watch, registry/daemon, and embeddings
• docs/COMMANDS.md — CLI, MCP tools, prompts, and exported artifacts
• docs/FEATURES.md — what the fork emphasizes and where it differs
• docs/ARCHITECTURE.md — parser, storage, and post-processing pipeline
• docs/SCHEMA.md — node, edge, and metadata model
• docs/MARKDOWN-AUTHORING.md — graph-aware Markdown directives and dagayn: links
• docs/SESSION-GRAPH-FRESHNESS.md — session prepare, worktrees, and MCP first-tool readiness
• docs/EVALUATION-SEMANTICS.md — metric roles, profile summaries, gates, costs, and semantic report outputs
• docs/LOCAL-EMBEDDINGS.md — managed sidecar and local embedding setup
• docs/DAEMON-CONFIG.md — registry and watch daemon file formats
• docs/TROUBLESHOOTING.md — practical fixes
• docs/LLM-OPTIMIZED-REFERENCE.md — machine-oriented reference sections

Current development direction

The fork currently emphasizes:

• infra-aware review, especially Terraform
• mixed-language monorepos
• stable relative-path graph registration from the repo root
• MCP-first workflows for terminal and editor agents
• reproducible local analysis without hosted services

Security and privacy

dagayn is designed around local graph storage. Some optional embedding providers can call remote APIs, but those flows are opt-in and documented separately.

See SECURITY.md and docs/LEGAL.md for details.

Contributing

See CONTRIBUTING.md for development setup, verification commands, and contribution rules.

License

MIT. See LICENSE.