dotdotgod

Change a file, know what else must be checked.

Dotdotgod gives AI coding agents a maintained project-memory map, bounded context loading, durable task plans, and changed-file impact review. It helps agents find the right evidence without loading the whole repository or reconstructing intent from stale chat history.

Use it to carry project knowledge across sessions while keeping plans, verification, and historical context explicit.

Repository: https://github.com/dotdotgod/dotdotgod-kit

The Working Loop

Every adapter follows the same loop:

1. init — create the docs-first project-memory scaffold.
2. load — start from a bounded documentation map and focused local query; Pi performs one mode-neutral automatic assessment when baseline context is missing.
3. plan — record durable task intent under docs/plan/ before source edits when the work warrants a saved plan.
4. impact — identify related specs, tests, docs, commands, and source before broad verification or handoff.

Pick the Package You Need

Package	Use it when	Start here
@dotdotgod/pi	You use Pi and want initialization, project loading, Plan Mode, impact checks, and archive handoff.	pi install npm:@dotdotgod/pi
@dotdotgod/cli	You want validation, graph indexing, local query, reference expansion, or impact reports.	npx @dotdotgod/cli init .
@dotdotgod/context	You want local command/file processing, FTS5 retrieval, and the shared stdio MCP runtime.	Installed automatically by the agent adapters.
@dotdotgod/claude-code	You use Claude Code and want /dd:* workflows plus local context MCP tools.	/plugin marketplace add dotdotgod/dotdotgod-kit, then /plugin install dotdotgod@dotdotgod
@dotdotgod/codex	You use Codex and want dotdotgod skills, local context MCP tools, and reviewed hooks.	Register the plugin manifest through a trusted Codex plugin flow.

Quick Start

Pi

Install the adapter:

pi install npm:@dotdotgod/pi

Open Pi in the target repository and ask:

Initialize this project with dotdotgod.

The initializer creates or normalizes shared agent instructions, documentation indexes, behavior, architecture, and test areas, plus local plan and archive memory. Validate the result with:

npx @dotdotgod/cli validate .

CLI only

npx @dotdotgod/cli init .
npx @dotdotgod/cli validate .
npx @dotdotgod/cli graph impact . --changed <path> --compact

For Claude Code and Codex setup, follow the package-specific Start Here links in the package table.

Why dotdotgod

Dotdotgod keeps a small, high-signal project-memory surface so an agent can answer three questions:

1. What should I load? Start from canonical instructions, README indexes, maintained docs, active plans, and the archive map.
2. What is related to this change? Use graph impact to rank likely specs, tests, docs, commands, and neighboring files.
3. What should I verify? Select documentation checks, traceability, focused tests, dry-runs, or workspace verification from the changed surface.

The structure provides:

• Low-noise loading: agents follow the documentation map and read targeted bodies instead of broad file lists.
• Durable intent: active plans and archived outcomes survive compaction, handoff, and new sessions.
• Traceable behavior: ordered traceability-key definitions connect behavior specs to configured path or command targets with explicit graph relations and weights.
• Bounded history: docs/archive/README.md remains the history map; archive bodies are read only when targeted.
• Local processing: graph and query caches stay under .dotdotgod/; agent-facing commands return bounded summaries.

Local Context Runtime

The adapter packages share a local execution and retrieval runtime. Small results can be returned directly; larger command output is indexed in the project-local SQLite FTS5 store and retrieved as bounded excerpts. Command stdout and stderr share a 10 MiB capture ceiling, and direct responses are capped at 1 MiB per stream. Dotdotgod execution tools inherit a compatibility-oriented environment after filtering runtime injection variables; ordinary inherited credentials are not isolated. Markdown and JSON retain structural chunk metadata, while bounded Porter, label/path, and typo-tolerant trigram candidates are combined with reciprocal-rank fusion and title/path/proximity reranking.

The index tool accepts project-contained files or bounded directories with explicit extension and path exclusions, deterministic traversal, symlinks skipped by default, and depth, entry, file-count, per-file, and aggregate-byte limits. It does not apply .gitignore semantics automatically. Fetched HTTP(S) content passes application-level DNS, address, peer, and redirect validation with separate wire and decoded limits; bounded HTML is normalized without browser rendering, JavaScript, subresource loading, or link following by default. An optional injected browser renderer is available only through explicit opt-in and is not bundled or described as a sandbox. Indexed sources carry operation-owned provenance and trust metadata, and retrieved text is rendered as non-authoritative data with instructionAuthority: "none"; these controls are defense in depth, not network isolation or a prompt-injection guarantee.

The local SQLite store uses WAL, a bounded busy timeout, and transactional source replacement, expiry, and purge. Recognized databases use versioned transactional migrations, while unknown or corrupt schemas fail closed; explicit healing backs up before a conservative rebuild. Opaque session resume, durable bounded ingestion jobs, and opt-in environment allowlisting are exposed consistently through MCP and Pi. Claude Code and Codex expose this behavior through dotdotgod's local MCP tools, while Pi calls the same core through native dotdotgod_* tools. It applies only when those execution, indexing, search, or fetch tools are used—ordinary host shell tools are not intercepted automatically. See the @dotdotgod/context package and the maintained context execution contract for details.

Beyond Software Projects

Although dotdotgod was designed for software projects, its memory and traceability model is not limited to code. I also use it personally to organize a real-world property dispute: separating confirmed facts from hypotheses, maintaining a timeline and evidence index, and tracing external documents back to their factual and legal grounds.

This makes dotdotgod useful as structured memory for preparing complaints, formal notices, and potential legal proceedings—not as legal advice, but as a way to keep complex evidence and reasoning organized.

Changed-File Impact Example

$ dotdotgod graph impact . --changed packages/cli/src/core.mjs --compact

docs:
- docs/spec/CONFIG_COMMAND.md (56.8; incoming:links_to, incoming:implemented_by)
- docs/spec/cli/TRACEABILITY_LINKS.md (26.3; vector_similarity)

tests:
- packages/cli/test/core.test.mjs (6.5; verified_by)

files:
- packages/cli/src/core.mjs (100; changed-file)
- packages/cli/src/memory/config.mjs (6.5; implemented_by)

Non-seed scores use a fixed weighted Personalized PageRank connection component capped at 80 plus memory policy capped at 20. Direct, curated, test, type, and semantic evidence add no separate score or ordering bonus; relation weights participate through PPR and reasons remain explanation evidence. When the local query cache is available, impact analysis can add a bounded request-local multilingual vector_similarity overlay without changing the indexed graph or persisting changed-file vectors. Vector failures degrade to structural-only results.

Each result includes ranking reasons so agents can inspect relevant evidence instead of scanning broadly. Exact scores vary with the project graph and memory policy. Keep results useful through focused README indexes, current traceability blocks, meaningful package metadata, and single-responsibility documents.

Core Concepts

• Project memory: durable files and metadata reused across sessions.
• Memory areas: configured scopes for stable project knowledge, local active plans, and historical archives.
• Documentation load: a depth-bounded project map with optional focused local query.
• Traceability: an ordered registry of string-array keys with labels, path or command targets, graph relations, and PPR weights.
• Impact graph: fixed weighted-PPR plus memory-policy ranking, optionally enriched by a request-local multilingual vector overlay.

For the detailed model, read Context curation, Context mechanics, and Measurement design.

Develop This Repository

Use source-checkout commands in this repository:

pnpm install
node packages/cli/bin/dotdotgod.mjs validate . --include-local-memory --check-index
pnpm run verify

Run package dry-runs before release-style handoff:

pnpm run pack:dry-run

Test the Pi adapter from a checkout:

pi install /path/to/dotdotgod/packages/pi

Documentation

Start with docs/README.md, then use the area indexes:

• Concepts
• Specs
• Tests
• Architecture
• Reports

Common routes:

• Project initializer
• Plan Mode
• Project Load
• Cross-agent support
• Documentation structure

Publishing

The root workspace package is private. Publish public workspace packages individually or with:

pnpm run publish:all