# Instructree

> Instructree is a dependency-free CLI, GitHub Action, and Codex skill that maps and lints repository-scoped coding-agent instructions without uploading repository content.

Use Instructree to run a share-safe Codex pre-session doctor; audit a focused companion-skill starter stack; debug parent AGENTS.md files hidden by nested project-root markers; inspect the configured AGENTS.md and AGENTS.override.md project chain; audit Codex user and repository-local skill candidate scopes plus supported user config; and map CLAUDE.md, GitHub Copilot instructions and recursive imports, Agent Skills, custom agents, agentic workflows, Cursor rules, Windsurf rules, and GEMINI.md. The current release is v0.22.0 and requires Node.js 20 or later.

## Start here

- [Project site](https://kotobuki09.github.io/instructree/): Product overview, example output, and verification evidence.
- [Debug Codex AGENTS.md](https://kotobuki09.github.io/instructree/codex-agents-md-debugger.html): Source-grounded troubleshooting for nested project roots, override precedence, byte limits, user instructions, and disabled skills.
- [Fix Codex skill overload](https://kotobuki09.github.io/instructree/codex-skill-overload.html): Find the largest enabled skill-list contributors, review duplicates, and check a focused starter stack against the bounded model-visible catalog.
- [Troubleshoot missing Codex Desktop local skills](https://kotobuki09.github.io/instructree/codex-desktop-local-skills.html): Audit valid repository-local `.agents/skills` candidates before comparing them with a fresh native Desktop session; the guide keeps static disk evidence separate from runtime visibility.
- [Repository](https://github.com/kotobuki09/instructree): Source code, README, issue tracker, and contribution guide.
- [Codex setup](https://github.com/kotobuki09/instructree/blob/main/docs/codex-setup.md): Install the native Codex skill and use the focused companion stack.
- [Release v0.22.0](https://github.com/kotobuki09/instructree/releases/tag/v0.22.0): Current release notes and verified package assets.

## Technical references

- [README](https://github.com/kotobuki09/instructree/blob/main/README.md): Commands, supported formats, CI integration, and design boundaries.
- [Compatibility report](https://github.com/kotobuki09/instructree/blob/main/docs/compatibility.md): Pinned audit of 682 public instruction and skill files.
- [Agent skill](https://github.com/kotobuki09/instructree/blob/main/skills/instructree/SKILL.md): Instructions used when Instructree is installed as a Codex skill.
- [Security policy](https://github.com/kotobuki09/instructree/blob/main/SECURITY.md): Supported version and vulnerability reporting guidance.

## Try it

- [Codex doctor](https://github.com/kotobuki09/instructree#commands): Run `instructree doctor .` for one redacted report covering supported user project settings, user instructions, the current project chain, and skill state; add `--json` for deterministic structured output.
- [Codex starter audit](https://github.com/kotobuki09/instructree/blob/main/docs/codex-setup.md): Run `instructree starter .` to compare a focused engineering stack with local skill state and print commands only for missing companions. The command is read-only; review every linked `SKILL.md` before installation.
- [Codex root-boundary research](https://github.com/kotobuki09/instructree/blob/main/docs/research/codex-root-boundary.md): Explain why a nested `.git` or configured marker can hide parent instructions and how the doctor reports that boundary without exposing local paths.
- [Codex user-root research](https://github.com/kotobuki09/instructree/blob/main/docs/research/codex-user-skill-roots.md): Explain why both `~/.agents/skills` and the deprecated default `~/.codex/skills` root are audited, with pinned Codex source and GitHub CLI evidence.
- [CLI install and examples](https://github.com/kotobuki09/instructree#try-it): Run the pinned release without an API key or repository upload.
- [Codex local-scope audit](https://github.com/kotobuki09/instructree#commands): Inspect shared and deprecated-default user roots plus repository-local `.agents/skills` candidates, supported user `skills.config` state, duplicates, metadata, the largest enabled contributors, and prompt-list pressure concisely with `instructree skills . --client codex`; add `--all` or `--json` for the full inventory.
- [GitHub Action](https://github.com/kotobuki09/instructree#ci): Add deterministic instruction linting to pull requests.