Stop coding agents from searching an empty directory

A fresh project directory has no code to discover, but a coding agent does not necessarily know that. Its first response can start with ls, globbing, or broader repository searches before it finally asks what should be created.

I built EmptyDir Context to remove that dead-end search without adding another permanent instruction to every session.

The invariant

Before each submitted prompt, the hook lists only the working directory's immediate entries.

If there are no entries, it adds this instruction to model context:

The current working directory is empty. Do not search this directory unless the user explicitly asks you to search it or the directory state changes.

If there is even one entry, it exits successfully with zero stdout bytes. No “directory is nonempty” message, no empty JSON object, and no incidental status text reaches model context.

That distinction matters because a context-saving hook should not become context overhead everywhere else.

Hidden entries count

An apparently blank directory may still contain .git, .env, editor state, or another dotfile. EmptyDir Context uses Node's readdir() on the directory itself, so hidden names, subdirectories, and symlinks all make it nonempty. It does not recurse and does not read file contents.

The core path is deliberately small:

const entries = await readdir(input.cwd);

if (entries.length !== 0) {
  return; // exact zero-byte stdout
}

process.stdout.write(JSON.stringify({
  hookSpecificOutput: {
    hookEventName: input.hook_event_name,
    additionalContext:
      "The current working directory is empty. Do not search this directory unless the user explicitly asks you to search it or the directory state changes."
  }
}));

Claude Code and Codex

Claude Code loads the repository's UserPromptSubmit hook as a normal plugin:

claude plugin marketplace add https://git.meowc.at/miki/emptydir-context.git
claude plugin install emptydir-context@emptydir-context-tools

Codex 0.145 exposes user-level hooks as stable but reports plugin-local hooks as removed, so the repository includes a small installer that merges the same command into ~/.codex/hooks.json and backs up an existing file first:

git clone https://git.meowc.at/miki/emptydir-context.git
node emptydir-context/scripts/install-codex-hook.mjs

The test suite covers a truly empty directory plus regular-file, hidden-file, .git, subdirectory, and symlink cases. Every nonempty case asserts exact zero-byte stdout.

EmptyDir Context is dependency-free, MIT-licensed, local-only, and contains no telemetry or network calls.

Source and installation details: https://git.meowc.at/miki/emptydir-context

Disclosure: I created and maintain EmptyDir Context.