microsoft/ShadowFrog

microsoft/ShadowFrog

Description: A suite of AI coding agent skills that build and maintain a shadow knowledge base for any codebase.

Language: Python

License: MIT

Stars: 25

Forks: 9

Open issues: 9

Created: 2026-05-19T15:28:47Z

Pushed: 2026-09-17T02:57:10Z

Default branch: main

Fork: no

Archived: no

README:

ShadowFrog

ShadowFrog gives coding agents a shadow knowledge base for any codebase: a file-backed memory of tacit codebase knowledge learned from code reading, experiments, and conversations with you.

Most agent memory preserves what happened in past chats. ShadowFrog is built for tacit knowledge that is hard to recover from chat history or source alone: which refactor breaks downstream callers, which invariant the tests never exercise, which "obvious" cleanup removes a production workaround, or which cross-file edge case is easy to miss. The code tells you *what runs*. The shadow tells future agents *what has been learned about how it behaves*.

Read the launch blog post: Shadow-Frog: Coding Agents that Dream and Discover.

---

Quick Start

# From your ShadowFrog checkout, install into your target repo.
cd /path/to/ShadowFrog
# Choose one:
./install.sh --project /path/to/your-repo # Copilot CLI (default)
# ./install.sh --agent claude --project /path/to/your-repo # Claude Code

On Windows, use the PowerShell installer instead (no Bash shell needed):

cd C:\path\to\ShadowFrog
.\install.ps1 -Project C:\path\to\your-repo # Copilot CLI (default)
# .\install.ps1 -Agent claude -Project C:\path\to\your-repo # Claude Code

Commit the installed files in the target repo:

cd /path/to/your-repo
# Stage the files for the agent you installed:
git add .github/skills/ .github/hooks/ .github/copilot-instructions.md
# git add .claude/skills/ .claude/hooks/ .claude/settings.json CLAUDE.md
git commit -m "Add ShadowFrog skills, hooks, and context"
git push

Then open the target repo in your AI agent session:

| Command | Use | |---------|-----| | /shadow-frog-init | Create the shadow | | /shadow-frog-update | Refresh after code changes | | /shadow-frog-dream | Explore and experiment while you're away | | /shadow-frog-meditate | Deduplicate and resolve conflicts | | /shadow-frog-viewer | Browse what's in the shadow |

If you plan to use /shadow-frog-dream, commit and push .shadow/ after init. Dream also needs permission to push dream/... branches to the repo's remote.

> See [Installation](#installation) for full details.

---

What is a Shadow?

A shadow is a .shadow/ directory that mirrors your source tree with markdown files. It is not generated API documentation and it is not a transcript store. It stores discoveries: behavioral facts, edge cases, implicit contracts, warnings, and cross-file interactions that are useful to future agents.

Shadow lookup is index-free: it follows the source tree instead of a separate vector index. If an agent is editing src/auth.py, the corresponding knowledge lives at .shadow/src/auth.py.md; if it is reasoning about src/auth.py::login, the same shadow file contains the symbol-level section. Cross-file discoveries use file::symbol back-pointers in .shadow/_cross/. No embedding database or separate retrieval service is required for this lookup path.

source code + conversations + dream experiments
|
v
shadow-frog skills and hooks
|
v
.shadow/ (per-file discoveries, cross-cutting notes, prefs, dreams)
|
v
future agent sessions (hooks, viewer, file reads, search)

The .shadow/ layout mirrors the repo:

your-repo/
src/
auth.py
db/models.py
.shadow/
.shadowignore gitignore-style excludes
_index.md file list with discovery counts
_prefs.md project-wide user preferences
_cross/ cross-cutting discoveries (span multiple files)
token-expiry-config-split.md
_meta/
state.json tracking state
_dreams/ experiment archive (reports + branch metadata)
_index.md table of all experiments (branch, parent, tip)
20250115-143012Z-retry-logic/ one folder per experiment (mirrored from branch)
report.md structured report with YAML frontmatter
patch.diff code-only diff (excludes .shadow/)
manifest.json machine-readable discovery manifest
src/
auth.py.md discoveries about auth.py
db/
models.py.md discoveries about models.py

Discoveries come from three sources:

Agent exploration: the agent reads code and runs experiments:

- authenticate_user() silently returns None on expired tokens
instead of raising. 3 of 7 callers don't check the return value.
_(verified, source: exploration, labels: [bug])_

User knowledge: things you tell the agent during conversation:

- The retry logic here took 3 iterations to get right -- it handles
a subtle race condition during rolling deployments. Do not simplify.
_(verified, source: user)_

Collaborative work: insights from debugging, refactoring, etc.:

- While debugging issue #42, discovered that process_batch() silently
drops items exceeding 1MB -- logged at DEBUG level only.
_(verified, source: interaction)_

Good discoveries are claims a future agent can act on, not summaries of what a function is named. Prefer "silently returns None on expired tokens" over "handles token expiration."

---

Skills

| Skill | What it does | When to use | |-------|-------------|-------------| | shadow-frog | Reference docs for the shadow format and conventions | Use when working in a repo with .shadow/ | | shadow-frog-init | Creates .shadow/ with structural templates for every file | Once per repo | | shadow-frog-update | Refreshes shadows after code changes; captures knowledge from conversations | After commits, or when you share context | | shadow-frog-dream | Autonomous exploration and experimentation while you're away | When you want the agent to explore on its own | | shadow-frog-meditate | Deduplicates, merges, and resolves conflicting discoveries | Periodically, to keep the shadow clean | | shadow-frog-viewer | Browse, search, inspect preferences and labels, render dream lineage, and check invariants | When you want to see what's in the shadow, or audit its integrity |

Design note: skills are readable instructions backed by small helper scripts for deterministic work: initializing shadows, managing dream worktrees, validating artifacts, reconciling branches, repairing...