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. Agents begin with the smallest useful set of project evidence and expand context through maintained documentation routes.

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:

• Focused loading: agents begin with a bounded documentation map and expand context through relevant indexes and evidence.
• Durable intent: active plans and archived outcomes survive compaction, handoff, and new sessions.
• Traceable behavior: behavior specs connect to implementation, verification, and design evidence through configured graph relations.
• Routed history: docs/archive/README.md guides agents to historical records relevant to the current task.
• Local processing: graph, query, and execution results stay locally available while agent-facing commands return bounded summaries.

Local Context Runtime

The adapters share a local runtime that keeps large command output, files, and fetched text useful without filling the model context. Small results return directly; larger results become locally searchable, bounded excerpts with provenance and trust metadata. Durable ingestion jobs and opaque session resume let longer processing survive individual turns.

Pi calls this core through native dotdotgod_* tools. Claude Code and Codex use the local stdio MCP server. These policies apply to dotdotgod execution and retrieval tools, while each host's built-in shell keeps its native behavior. The default compatibility environment preserves ordinary inherited credentials; an opt-in allowlist mode provides a stricter child environment.

The runtime applies bounded capture, storage, traversal, and HTTP(S) fetch policies. These controls provide defense in depth rather than a network sandbox or prompt-injection guarantee. See the @dotdotgod/context npm landing page, behavior contract, architecture, and verification strategy.

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 the smallest useful set of related evidence. 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