dotdog

Local-first spec and code graphs for coding agents. Keep human intent, observed implementation, and imported analysis evidence distinct and queryable.

Install

These commands install the stable package. This guide covers Dotdog 1.0.

npm install -g dotdog
# or
bun add -g dotdog

Node.js 22.12+ or Bun 1.3+. npm and Bun install the same package. The global executable has a Node shebang; on a Bun-only machine, use bunx --bun dotdog to force the Bun runtime. The existing Homebrew distribution remains available through the Specdog tap; its formula/version is maintained separately from this source change.

brew tap specdog/tap
brew install dotdog

Existing repository: one refresh, targeted questions

cd your-repository
dotdog refresh --json
dotdog query "authentication"
dotdog context "file:src/auth.ts" --json
dotdog impact "file:src/auth.ts" --json
dotdog path "file:src/auth.ts" "file:src/session.ts" --json

Use an actual graph label from query, not the illustrative paths above. refresh maps repository files, extracts JS/TS declarations and static relative imports, preserves semantic/overlay layers, compiles specs when present, and reports added/changed/removed identities. --if-stale checks content hashes and skips extraction when inputs and output match. Unchanged JS/TS extraction is cached.

Generated repository graphs live under .doghouse/. Do not commit generated repository metadata by default. Human-owned semantic and overlay inputs remain separate from generated facts.

Codex and Claude skills

dotdog skills install --agent both
# or: --agent codex / --agent claude

This installs the bundled dotdog skill into .agents/skills/dotdog/ for Codex and .claude/skills/dotdog/ for Claude Code. It is repository-scoped, idempotent, and refuses to replace user-edited skills. Invoke $dotdog in Codex or /dotdog in Claude; hosts can also select the skill when relevant. Installation does not modify global client settings or install hooks.

Optional automation

dotdog hooks install --agent claude
dotdog hooks install --agent git
dotdog hooks status
dotdog hooks remove --agent claude
dotdog hooks remove --agent git

Hooks are explicit opt-in, visible and removable. Existing Git hooks and core.hooksPath configurations are not overwritten. Git hooks never auto-stage files. Claude hooks preserve unrelated settings; edits made through shell commands or external tools may not trigger them. Use refresh --if-stale at the next task boundary and CI as independent checks.

For CI, install a pinned release or build this branch, then run:

dotdog check --json

check rebuilds graphs and checks structural integrity. It does not run application tests or prove runtime behavior. check --staged checks index contents rather than unstaged changes.

New spec project

dotdog init my-project
# Fill in the generated human-owned specs.
dotdog validate
dotdog compile
dotdog design --json
dotdog serve

init refuses an existing project. --minimal creates two files and is supported by validation. Validation reports required-file presence and parser diagnostics, not a percentage of product correctness. Use analyze for heuristic suggestions; use real tests for behavior.

The compact compiler preserves property definitions, states and lifecycle metadata. Incompatible same-named declarations in different source files receive Name@source-file labels; relationships must resolve in their source scope. --v2 retains legacy positional output. Byte-based token figures are estimates, not tokenizer measurements or quality guarantees.

MCP

Configure a local stdio server with the installed dotdog executable and arguments ["serve"], from the intended repository root. It opens no TCP listener.

Tools: listProjects, workspace.list, search, getEntity, schema, summary, traverse, path, context, impact, and infraVerify.

Query an explicit project when more than one is loaded. Observed repository graphs use <repository>:observed names in MCP, keeping them separate from same-named spec projects. Every tool returns structured JSON plus text fallback. Search supports limit and cursor; traversal/impact/context are bounded and disclose truncation. Graph queries retain supplied coverage/limitations; MCP traversal also retains node identities and provenance. no_path means no path in the supplied graph within maxHops, not proof of runtime independence; truncated reports an unexplored search boundary. Invalid graphs are reported separately by listProjects; deleted graphs are evicted.

The server supports legacy initialization revisions 2024-11-05, 2025-06-18 and 2025-11-25, plus 2026-07-28 discovery and per-request metadata. infraVerify is an explicit live network/provider operation; other graph queries stay local.

Selected type contracts

Dotdog 1.0 supports opt-in types inspect for selected TypeScript 7.0.2 contracts, compiler diagnostics and bounded type-reference graphs. See type contracts for commands, requirements and limits. No compiler is auto-installed, and no MCP query executes one.

REA / Ghidra evidence

Dotdog can import a saved REA NativeCallGraph body:

dotdog graph import native-calls.json --format rea-callgraph --project native --artifact-sha256 <binary-sha256> --rea-direction forward
dotdog context "0x1000" --dag .doghouse/imported/native.dag --json
dotdog graph export --dag .doghouse/imported/native.dag --format json

Replace the digest and address with actual evidence values. Supply --rea-direction forward or backward to match the original REA request; the bare export does not encode it. Backward exports are imported as caller → callee edges, not reversed calls. The importer retains traversal coverage, limitations, evidence references, addresses and the export digest. Without a binary digest, identifiers are scoped to the export bytes and binary identity remains unknown. Imported projects are also served by MCP. Imports create separate named graphs; automatic source-to-binary reconciliation and cross-project links are not provided.

This is a saved-export adapter, not a direct Ghidra analysis provider. REA/SolidState retains ownership of Ghidra, target selection, analysis sessions and authority. Dotdog never launches targets, installs REA/Ghidra, or registers another provider. NativeCallGraph bodies are supported; arbitrary REA Evidence envelopes and other Ghidra export formats are not implicitly accepted.

Existing integrations

GitHub Spec Kit remains supported:

dotdog speckit import .
dotdog compile .doghouse/speckit
dotdog serve .doghouse/speckit

Workspaces retain workspace init, add, list, validate, graph, observe, ask, and drift. refresh operates on the current repository; it does not infer cross-repository calls. Use the workspace commands for explicit multi-repo manifests.

Freshness, references and recorded evidence

dotdog status --json
dotdog scenario-check checkout --project shop --json
dotdog reference-check --project shop --json
dotdog graph audit --dag .doghouse/imported/system.dag --profile evidence --json

status is read-only and exits nonzero when graphs are stale or absent. scenario-check checks one named Scenario/Flow for lexical compiled-entity references. reference-check checks explicit Verify file/property mappings without writing human plans. None proves application correctness. staleness, simulate and verify are deprecated compatibility names; verify --init is retired.

graph audit checks recorded artifact hashes, timestamps and results. This establishes artifact identity and reported traceability, not requirement satisfaction or runtime correctness.

Limits and migration

• AST extraction covers JS/TS top-level declarations and static relative imports/re-exports. It does not resolve arbitrary aliases, dynamic calls, runtime execution, or every language's semantics. Other files are inventoried.
• Git ignore rules are honored in Git repositories; non-Git directories use built-in exclusions. There is no silent 500-file cutoff.
• impact follows recorded relationships; it is not a complete runtime blast-radius proof.
• 1.0 uses content-derived, case-sensitive identities. Rebuild generated graphs with refresh; old graph formats remain readable. Do not persist old generated IDs as external contracts without migration.
• Missing paths and high-severity drift return nonzero exits, including JSON output.
• No fixed token-savings percentage or hallucination guarantee is claimed.

See retrieval measurements and superposition assessment for the controlled benchmark, exact tokenizer baseline and remaining evaluation limits.

See security review, migration, and integrations.

Development

bun install --frozen-lockfile
bun run lint
bun test
bun run build
node packages/dotdog/dist/cli.js --help
bun run pack:check
bun run release:check

Run the built CLI with node packages/dotdog/dist/cli.js from this checkout. When working in another repository, use the absolute path to that built executable; an existing global dotdog installation may still be the stable release.

See path-search measurements for the tested optimization scope.

The release check packs the actual npm artifact and tests it outside the repository with Node and Bun. MIT licensed.