coding-inspector

A local, read-only viewer for the configuration of AI coding tools. It scans the real configuration on disk and answers one question:

What is in my local AI coding environment, where does it live, and what does it contain?

Supported providers today:

• Claude Code: CLAUDE.md instructions, settings, skills, commands, agents, output styles, hooks, plugins, MCP servers and per-project .claude/ configuration
• Codex: AGENTS.md / AGENTS.override.md instructions, config.toml, rules, skills (user, system and project), plugin manifests and plugin MCP files

The filesystem stays the source of truth. coding-inspector never writes to Claude, Codex, or project configuration; it has no edit, save, enable, or delete controls. It runs as one local Node process with a browser UI, has no third-party dependencies and no build step, and makes no outbound network requests.

Requirements and platform support

• Node.js 20 or newer
• Developed and used on macOS. That is the only platform it is regularly run against.
• Windows is not supported: path handling, the project-root separator (:) and the temporary-directory rules assume POSIX paths.
• Linux is not a supported target. The fixture test suite has passed there, but the tool has not been used against a real Linux Claude Code or Codex installation.

Install and run

git clone https://github.com/dan-sheehan/coding-inspector.git
cd coding-inspector
npm install   # no third-party dependencies; nothing is downloaded
npm start

Then open http://127.0.0.1:4747/. Stop the server with Ctrl+C.

The server binds to 127.0.0.1 only. Set CODING_INSPECTOR_PORT to use another port.

Test

npm test

Deterministic and self-contained. It runs the frontend renderer checks (escaped Markdown rendering, heading navigation targets, script syntax), then the health, relationship, redaction, read-only, endpoint and security-header checks against the deliberately broken environment in fixtures/. Before loading the inspector it points HOME at an empty temporary directory, so your real ~/.claude and ~/.codex are never read or probed. It creates and removes temporary probe files inside fixtures/ and under the OS temp directory. Browser interaction and layout checks are manual.

Run the tests from a checkout outside /tmp (and, on macOS, /var/folders). The scanner deliberately ignores project roots in temporary directories, so from a checkout there the fixture projects would be skipped and the suite would fail.

Optional: verify against your own machine

npm run test:local

Runs the same inspector read-only against your real ~/.claude, ~/.claude.json and ~/.codex. It checks endpoint shapes, counts against independent filesystem counts, samples metadata, and confirms that sensitive values from ~/.claude.json never appear in any API response. It also confirms that nothing under the inspected configuration directories changed during the run (sizes and mtimes). Checks for surfaces you don't have (for example, no Codex install) are skipped. It prints paths and component names from your machine, so treat its output as private.

Using the inspector

• Environment is a Finder-like view of Claude, Codex, or both. Browse relevant hidden folders and select a file to see its absolute path and safe contents. Edits under ~/.claude, ~/.codex (config.toml, AGENTS.md, rules, skills, plugins) and project roots refresh the view automatically; Codex runtime databases, temp files and credentials are never watched. Use Refresh if a change is not picked up.
• Press ⌘K / Ctrl+K or / to focus environment search. Search results and relationship evidence link directly to the matching source line.
• Commands and Skills support name, description, and path filtering, including /name. Combine provider, scope, tool policy, files, issues, and override filters; Clear filters resets them. Filters last for the current page session. Selecting an item or changing its tab preserves the list's position.
• Skills lists Claude Code and Codex skills together. Codex user skills (~/.codex/skills/<name>), system skills (~/.codex/skills/.system/<name>, shown with a system badge), and project skills (<project>/.agents/skills/<name>) are parsed, health-checked with provider-neutral rules, searchable, and counted in the Overview. Reference, slash-mention, and relationship analysis is applied to Claude skills only. A Claude skill and a Codex skill may share a name without being reported as a collision.
• Instructions lists Claude CLAUDE.md and Codex AGENTS.md / AGENTS.override.md files together, grouped by provider and layer, each with rendered, source, and structure views. A Codex file's Structure tab states its scope: the global ~/.codex file applies to every session, a root file to the whole repository, and a nested file to the directory tree that contains it (deeper files take precedence); AGENTS.override.md wins over AGENTS.md in the same directory and the shadowed file is marked. Nested AGENTS files are listed up to four directories deep. That is a discovery bound in coding-inspector, not a guarantee that every file Codex honours is shown. Reference extraction, @include handling, and relationship analysis apply to Claude instructions only.
• Instructions and bundled Markdown include Jump to section. Source has Wrap lines, a line-number field (press Enter), and links on each line number. Source wrapping is remembered until the page reloads. A selected bundled file keeps the file chooser collapsed so the content is immediately accessible.
• Trace relationships opens a component's outgoing and incoming references. Expand individual branches, inspect all evidence for a repeated target, or use trace to make another component the starting point. Cycles and the four-hop expansion limit are labeled.

The interface uses system fonts and a compact dark palette. Detail columns adapt to their available width; tabs and source remain scrollable in narrower windows.

What it reads

Layer	Location
Managed (enterprise)	/Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json elsewhere (if present)
Claude user	~/.claude/CLAUDE.md, settings.json, settings.local.json, skills/, commands/, agents/, output-styles/, plugins/, hooks/
User state	~/.claude.json (curated: MCP servers, per-project state, usage counters; identity and caches omitted)
Codex user	~/.codex/config.toml, AGENTS.md and AGENTS.override.md (modelled as instruction components), rules/, skills/ (user and .system skills are modelled as components), plugin manifests, plugin skills and plugin MCP files, AGENTS files under .chatgpt-projects/
Codex desktop state	~/.codex/.codex-global-state.json, read only for its recorded workspace root paths; its contents are never displayed
Projects	Roots recorded by Claude Code (~/.claude.json) or Codex (config.toml [projects], the desktop app's workspace roots, CODING_INSPECTOR_CODEX_PROJECT_ROOTS), plus folders found beside them that carry a Claude marker (.claude/, CLAUDE.md, .mcp.json) or a Codex marker (.codex/, .agents/skills/). Claude project configuration and Codex .codex/ entries and .agents/skills/ (modelled as project skills) are listed; AGENTS.md / AGENTS.override.md files on known roots (root-level and nested, up to four directories deep, a discovery bound) mark the root as carrying Codex instructions, are modelled as Codex instruction components with their scope, and are never used to find roots

Beyond those files, discovery lists directory names only:

• Nearby projects. Folder names are listed one or two levels below the parent folders of recorded projects, and below ~/Developer, ~/Projects, ~/projects, ~/code, ~/src, ~/repos, ~/work, ~/dev and ~/workspace if they exist. The home directory is listed one level deep. At most 3,000 directories are examined, and each is only checked for the markers above. There is no home-wide crawl.
• Existence checks. Paths referenced from Claude instructions and skills (links, backtick paths, @includes), script paths named in hook commands, and MCP server commands (including a PATH lookup) are checked for existence so broken references can be reported. They are never read or executed.

Environment variables override the defaults: CODING_INSPECTOR_PORT, CODING_INSPECTOR_CLAUDE_HOME, CODING_INSPECTOR_CLAUDE_JSON, CODING_INSPECTOR_CODEX_HOME (or CODEX_HOME), CODING_INSPECTOR_MANAGED, CODING_INSPECTOR_HOME_DIR, CODING_INSPECTOR_PROJECT_ROOTS, CODING_INSPECTOR_CODEX_PROJECT_ROOTS (colon-separated extra roots), CODING_INSPECTOR_INVENTORY_CAP (per-provider Environment inventory limit; 5,000 is both the default and the maximum, so the override can only lower it, mainly for testing), and CODING_INSPECTOR_QUIET=1 (no request log).

What it refuses to preview

The Environment page lists these by name (when they exist) but never reads or displays them:

• Claude: ~/.claude/projects/ (session transcripts), history.jsonl, session-env/, backups/, cache/, and the raw ~/.claude.json (its curated view is under User state)
• Codex: auth.json, local databases (*.sqlite, -wal, -shm), sessions/, archived_sessions/, attachments/, session_index.jsonl, transcription-history.jsonl, .codex-global-state.json, cache/, .tmp/

Other Claude runtime files, such as ~/.claude/.credentials.json, are outside the listed configuration surfaces and are not listed at all.

In addition, no preview is shown for:

• symlinks (listed, but the target is not followed)
• files that resolve outside the root they were listed under
• files over 1 MiB, binary files, and file types outside a text allowlist (Environment page)
• invalid JSON in the Environment browser and bundled skill files, because its structure can't be redacted reliably (an invalid Claude settings*.json or .mcp.json is still shown in its component view, with the text-pattern redaction only, so you can see the parse error)

Security model

Threat model. coding-inspector is designed for a trusted local user and to reduce accidental exposure or over-broad reads. It is not intended to be a hardened security boundary against a malicious user or process that already controls the machine or account.

What it does:

• Loopback only. The server binds to 127.0.0.1 and rejects requests whose Host header is not 127.0.0.1, localhost or [::1], which blocks DNS-rebinding attacks. There is no authentication: any local process or other account on the same machine that can connect to the port can read what the UI shows. Don't run it on a shared multi-user machine you don't trust.
• Browser isolation. Responses carry a strict Content-Security-Policy (same-origin resources only, no framing), X-Content-Type-Options: nosniff and Referrer-Policy: no-referrer. No CORS headers are sent, so other websites can't read API responses. A web page could still send a blind POST /api/rescan; that only triggers a rescan and returns nothing readable to the page.
• Read-only. The application code never writes to the filesystem and never starts subprocesses. File watching uses fs.watch for change notifications only.
• Redaction. Every displayed file passes through lib/redact.mjs before it is served. Known token shapes (Anthropic, OpenAI, GitHub, Slack, AWS, Google, npm, PyPI, Hugging Face, Shopify, GitLab, JWT, private-key blocks), Bearer tokens, URL passwords, *_TOKEN=-style assignments, email addresses, JSON/TOML/YAML sensitive fields, and values under environment, header, credential, or auth containers are replaced with [REDACTED:kind]. A second pass runs on every outgoing API body and event. Request logs contain only method, path, status and duration.
• Search is built from already-redacted text, so a raw secret value can't be found by searching for it.

Limits you should know about:

• Redaction is best-effort pattern matching. It can't recognise every secret. A credential with an unusual format, stored under an innocuous key name in a plain-text file, can be shown as-is. Don't treat the UI as safe to screen-share or screenshot without looking first.
• Bundled skill files. Any non-binary file inside a skill directory can be previewed with the redaction above, not only Markdown. That includes files such as .env if you keep one there.
• Symlinks. The scanner follows symlinked skill directories and symlinked Markdown instruction files, as Claude Code does, so their targets are read and displayed. The Environment browser and bundled-file previews refuse symlinks and anything that resolves outside its inspected root.
• Metadata is visible. Absolute paths, project directory names and usage counters from ~/.claude.json are shown by design.

Layout

server.mjs          HTTP server, API, file watching (127.0.0.1 only)
lib/scan.mjs        discovery + parsing of every layer; redaction at read time
lib/environment.mjs bounded Claude + Codex filesystem inventory and safe previews
lib/frontmatter.mjs dependency-free YAML-subset parser with error reporting
lib/redact.mjs      secret detection and redaction
lib/analyze.mjs     relationships, health checks, search index, overview
public/             vanilla-JS front end (hash router, no framework, no CDN)
fixtures/           deliberately broken environment used by the tests (all secrets are fake)
test/run.mjs        test suite (npm test; --local for npm run test:local)

API

/api/status, /api/overview, /api/components?type=&scope=&project=&tool=, /api/components/:id, /api/components/:id/file?rel=, /api/search?q=, /api/relationships, /api/health, /api/config, /api/events (SSE), POST /api/rescan. The Environment page uses /api/environment?tool=all|claude|codex and /api/environment/:id.

License

MIT. See LICENSE.