agt-env 0.0.3__tar.gz

agt_env-0.0.3/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v10.3.3
+
+      - name: Check formatting
+        run: uvx ruff format --check
+
+      - name: Lint
+        run: uvx ruff check
+
+      - name: Lint workflows
+        run: uvx --from actionlint-py actionlint .github/workflows/*.yml
+
+  # Shared runners vary too much to fail on a time limit: the same code measured 209 ms and
+  # under 200 ms on two runs. This only reports the timings.
+  speed:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v10.3.3
+
+      - name: Report speed
+        run: uv run pytest -s tests/test_speed.py
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.14"]
+    runs-on: ${{ matrix.os }}
+    env:
+      UV_PYTHON: ${{ matrix.python }}
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v10.3.3
+
+      - name: Run tests
+        run: uv run pytest --ignore=tests/test_speed.py
+
+      - name: Build
+        run: uv build
+
+      - name: Check the built package from a clean environment
+        run: uv run --no-project scripts/check_wheel.py dist/*.whl

agt_env-0.0.3/.github/workflows/pypi.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+# Uploads to PyPI when a release tagged v<version> is published by a person, or when
+# release.yml starts this workflow on that tag.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v10.3.3
+
+      - name: Check the release tag matches the project version
+        env:
+          TAG: ${{ github.event.release.tag_name || github.ref_name }}
+        run: |
+          version="$(uv version --short)"
+          if [ "$TAG" != "v$version" ]; then
+            echo "Release tag $TAG doesn't match project version $version" >&2
+            exit 1
+          fi
+
+      # A slow runner shouldn't stop a release, so the speed test is left out.
+      - name: Run tests
+        run: uv run --python 3.11 pytest --ignore=tests/test_speed.py
+
+      - name: Build
+        run: uv build
+
+      - name: Check the built package from a clean environment
+        run: uv run --no-project scripts/check_wheel.py dist/*.whl
+
+      - uses: actions/upload-artifact@v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agt-env/
+    permissions:
+      id-token: write # PyPI trusted publishing, so no API token is stored
+    steps:
+      - uses: actions/download-artifact@v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@v1.14.3

agt_env-0.0.3/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Create release
+
+# Pushing a tag v<project version> on a commit in main creates its release, then starts
+# the PyPI workflow. A release made with GITHUB_TOKEN doesn't trigger other workflows,
+# so pypi.yml has to be started explicitly.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write # start pypi.yml
+      contents: write # create the release
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          fetch-depth: 0 # needed to check the commit is in main
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v10.3.3
+
+      - name: Check the tag matches the project version
+        run: |
+          version="$(uv version --short)"
+          if [ "$GITHUB_REF_NAME" != "v$version" ]; then
+            echo "Tag $GITHUB_REF_NAME doesn't match project version $version" >&2
+            exit 1
+          fi
+
+      - name: Check the tagged commit is in main
+        run: |
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "Tag $GITHUB_REF_NAME points at a commit that isn't in main" >&2
+            exit 1
+          fi
+
+      - name: Create release and start publishing
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # A release published in the browser also pushes its tag, and starts pypi.yml itself.
+          if gh release view "$GITHUB_REF_NAME" > /dev/null 2>&1; then
+            echo "Release $GITHUB_REF_NAME already exists" >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+          gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --generate-notes
+          gh workflow run pypi.yml --ref "$GITHUB_REF_NAME"
+          echo "Created $GITHUB_REF_NAME and started pypi.yml" >> "$GITHUB_STEP_SUMMARY"

agt_env-0.0.3/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/

agt_env-0.0.3/AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md
+
+This file provides guidance to coding agents when working with code in this repository. `CLAUDE.md` is a symlink to it.
+
+`agt-env` is a read-only CLI that lists the skills, MCP servers, plugins, hooks, subagents, and commands each coding agent can use from the current directory. Requirements are in `docs/PRD.md`.
+
+## Commands
+
+```sh
+uv run agt-env                  # run from source
+uv run pytest                    # all tests; real-agent comparisons are skipped
+uv run pytest tests/test_cli.py::test_filters    # one test
+uv run --isolated --python 3.11 --group dev pytest    # oldest supported Python
+uvx ruff format                  # format; configured in pyproject.toml
+uvx ruff check                   # lint
+uvx --from actionlint-py actionlint .github/workflows/*.yml
+uv build && uv run --no-project scripts/check_wheel.py dist/*.whl    # the built wheel, as a new user runs it
+```
+
+Real-agent comparison tests run only when given a binary, and always use a temporary `HOME`. Pass the real binary, because a version-manager shim may not work in a temporary `HOME` (with mise, use `mise which codex`):
+
+```sh
+AGT_ENV_CLAUDE=... AGT_ENV_CODEX=... AGT_ENV_OPENCODE=... AGT_ENV_PI=... AGT_ENV_AGY=... uv run pytest
+```
+
+## Architecture
+
+`cli.py` runs every adapter in `adapters.ADAPTERS` (registry order is display order), marks skills shared between agents by real path, and passes what `filters.py` selects to an output: `render_pretty.py` (Rich) on a color terminal, otherwise `render_plain.py` (plain text, whose exact form scripts can rely on). It hides agents that aren't both installed and configured, unless `--all` or `-a` is used.
+
+Each adapter returns an `AgentReport`: install and config state, plus `Item`s (`model.py`). All agent-specific rules live in that adapter. Shared helpers are in `adapters/base.py` (reading config, building items), `skills.py` (scanning, with per-agent options for depth and hidden directories), `mcp.py` (safe server summaries), `hooks.py` (hook entries and safe summaries), `frontmatter.py`, and `jsonc.py`.
+
+Adapters are independent of each other. The same directory can be scanned by several adapters, because agents read each other's skill directories.
+
+## Rules that span the code
+
+- **Default commands only read files.** They never run agent binaries, start MCP servers, or load plugins. `shutil.which` is the only install check.
+- **Secret values must never reach an `Item`.** MCP `details` come from `mcp.py`, which keeps env and header names only, drops arguments, and strips URL credentials and queries. Plugin and package names go through `without_credentials`, and a hook's text goes through `masked`, the one place free text reaches an `Item`. Masking recognizes common forms, not every secret, so add a form there and to the tests when one is missed. Credential stores are never opened, and `skills.py` won't follow a skill file's symlink to a non-Markdown file. `tests/test_safety.py` checks this, and that nothing is written, by auditing what a real run opens; add new credential locations there and to `docs/agents/README.md`.
+- **Inspected text is untrusted.** Everything printed goes through `render_plain.clean()`, and reaches Rich only as a `Text`, because Rich parses plain strings as markup. Files are read with a size limit, and non-regular files aren't opened.
+- **Status needs evidence.** Use `unknown` rather than guessing `enabled`, and `pending` when an item waits on user approval or trust. A `broken` item always has a finding that says why, which every scan in the tests checks. `shadowed` needs a precedence rule with evidence, recorded in the agent's doc page, and adapters call `mark_shadowed` with items in that order. A config file that can't be read gives a warning and `unknown`, and must not affect other agents.
+- **The current directory, or `--project`, is the project root.** Parent directories aren't searched, even for agents that search them.
+
+## Changing agent rules
+
+Agent docs are often incomplete or wrong, so check behavior against the real agent, in a temporary `HOME`. When rules change, update both the adapter and its `docs/agents/<agent>.md`, which is the single record of each rule and whether it's documented or tested. Adapter header comments only point to that file.
+
+To add an agent, write the adapter, a line in `adapters/__init__.py`, a doc page, and tests. The priority order is in the PRD.
+
+Tests must stay isolated: the `machine` fixture in `tests/conftest.py` provides a temporary `HOME`, an empty `PATH`, and a redirected `system_root`.
+
+OpenCode's comparison tests start a background service, so they give it its own port and stop it afterwards. Don't stop a service running under a real `HOME`.
+
+## Docs
+
+- Keep `docs/PRD.md` independent of any one machine: no personal paths or installed tools, and no scope or priority decided by them. Use placeholder examples.
+- Don't change the document version in the PRD unless asked.
+
+## Releasing
+
+Before tagging, run the real-agent comparison tests above, because CI doesn't have the agents.
+
+The version is in both `pyproject.toml` and `src/agt_env/__init__.py`, and `uv.lock` must be refreshed with `uv lock`. The workflows only check the tag against `pyproject.toml`.
+
+Pushing a tag `v<version>` on a commit in `main` runs `release.yml`, which creates the GitHub release and starts `pypi.yml`. A release created by a workflow can't trigger other workflows, so `release.yml` starts `pypi.yml` explicitly. `pypi.yml` uploads through PyPI trusted publishing, with environment `pypi`.

agt_env-0.0.3/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

agt_env-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xgzeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agt_env-0.0.3/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.5
+Name: agt-env
+Version: 0.0.3
+Summary: List the skills, MCP servers, and extensions available to each coding agent
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: rich>=14.3
+Description-Content-Type: text/markdown
+
+# agt-env
+
+A read-only CLI that shows what each coding agent on your machine can use from the current directory.
+
+**Status:** early development. It currently lists **skills**, **MCP servers**, **plugins**, **hooks**, **subagents**, and **commands** for **Claude Code**, **Codex**, **OpenCode**, **Pi**, and **Antigravity CLI**. More agents are planned; see the [product requirements](docs/PRD.md). [Agent discovery rules](docs/agents/README.md) describes how each agent finds these.
+
+## Usage
+
+Run it from your project root to include project-level configuration. No install is needed with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx agt-env                            # list everything for active agents
+uvx agt-env --all                      # also show agents not both installed and configured
+uvx agt-env -a codex -k mcp            # filter by agent and kind
+uvx agt-env -n my-skill --detail       # filter by name, and add paths and other details
+uvx agt-env "browser test" lint        # search all fields: (browser and test) or lint
+```
+
+`agt-env` only reads files. It never changes your configuration or runs your agents.
+
+Output is plain text when piped, or with `--no-color` or `NO_COLOR`.
+
+Problems are shown with the items they affect: why an item is `broken`, and when a same-named item is used instead (`shadowed`). Search for them like anything else, as in `uvx agt-env shadowed`.
+
+## Development
+
+```sh
+uv run agt-env   # run from source
+uv run pytest     # run the tests
+
+# Also compare results with real agents, in a temporary HOME
+AGT_ENV_CLAUDE=/path/to/claude AGT_ENV_CODEX=/path/to/codex \
+AGT_ENV_OPENCODE=/path/to/opencode AGT_ENV_PI=/path/to/pi AGT_ENV_AGY=/path/to/agy \
+uv run pytest
+```

agt_env-0.0.3/README.md

@@ -0,0 +1,35 @@
+# agt-env
+
+A read-only CLI that shows what each coding agent on your machine can use from the current directory.
+
+**Status:** early development. It currently lists **skills**, **MCP servers**, **plugins**, **hooks**, **subagents**, and **commands** for **Claude Code**, **Codex**, **OpenCode**, **Pi**, and **Antigravity CLI**. More agents are planned; see the [product requirements](docs/PRD.md). [Agent discovery rules](docs/agents/README.md) describes how each agent finds these.
+
+## Usage
+
+Run it from your project root to include project-level configuration. No install is needed with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx agt-env                            # list everything for active agents
+uvx agt-env --all                      # also show agents not both installed and configured
+uvx agt-env -a codex -k mcp            # filter by agent and kind
+uvx agt-env -n my-skill --detail       # filter by name, and add paths and other details
+uvx agt-env "browser test" lint        # search all fields: (browser and test) or lint
+```
+
+`agt-env` only reads files. It never changes your configuration or runs your agents.
+
+Output is plain text when piped, or with `--no-color` or `NO_COLOR`.
+
+Problems are shown with the items they affect: why an item is `broken`, and when a same-named item is used instead (`shadowed`). Search for them like anything else, as in `uvx agt-env shadowed`.
+
+## Development
+
+```sh
+uv run agt-env   # run from source
+uv run pytest     # run the tests
+
+# Also compare results with real agents, in a temporary HOME
+AGT_ENV_CLAUDE=/path/to/claude AGT_ENV_CODEX=/path/to/codex \
+AGT_ENV_OPENCODE=/path/to/opencode AGT_ENV_PI=/path/to/pi AGT_ENV_AGY=/path/to/agy \
+uv run pytest
+```

agt_env-0.0.3/docs/PRD.md

@@ -0,0 +1,294 @@
+# agt-env: Product Requirements
+
+| | |
+|---|---|
+| **Status** | Draft v0.1 |
+| **Date** | 2026-10-30 |
+| **Name** | `agt-env` (command and package) |
+
+## 1. Summary
+
+`agt-env` is a read-only CLI that answers one question: **what can each coding agent on my machine use from this directory?** It finds the skills, MCP servers, and plugins configured for each agent, puts them in one model, and shows them in the terminal.
+
+## 2. Problem
+
+Anyone running several coding agents has capabilities scattered across incompatible locations and formats, and no single place to see them. Common situations make this harder than listing a few directories:
+
+| Situation | Why it matters |
+|---|---|
+| Each agent has its own locations, file formats, scopes, and terminology | Checking each one by hand doesn't scale past one or two agents |
+| The same skill can be linked or copied into several agents' directories | A plain listing overstates what exists and hides what is shared |
+| Copies of a skill can change independently | Agents can end up with different versions and no warning |
+| Agents may cache plugins they haven't enabled | Treating a directory's contents as available would mislead |
+| An agent can be installed but unconfigured, or leave config behind after being uninstalled | "Installed" and "configured" are separate states |
+| Some capabilities are built into the agent or attached to a cloud account | Files on disk don't describe everything available at runtime |
+| Agent CLIs can be slow to start, need authentication or network access, or have side effects | Calling each CLI is too slow and unreliable to be the default |
+
+## 3. Goals and non-goals
+
+### Goals
+
+1. List capabilities across all agents in one command, with no setup, including no prior install.
+2. Be accurate about what is known: report status and source, and say "unknown" rather than guess.
+3. Resolve context from the current directory, covering both user and project scope.
+4. Expose shared, duplicated, and shadowed items instead of hiding them.
+5. Make adding a new agent a small, isolated change.
+
+### Non-goals (v1)
+
+- **Changing anything:** no install, remove, enable, disable, or sync. These may come later, but v1 is strictly read-only.
+- **Machine-readable output:** v1 is for people reading a terminal. JSON or similar output may come later.
+- **Marketplace browsing:** v1 covers what is on the local machine, not what could be installed.
+- **Exact session state:** v1 doesn't report what a particular running session has loaded.
+- **Account-level discovery:** remote connectors that exist only in an agent's cloud account aren't enumerated.
+- **Windows support:** Linux and macOS come first.
+
+## 4. Users
+
+- **Primary: multi-agent developer.** Switches between agents and wants to know why one of them can't see a skill or MCP server.
+- **Secondary: security-conscious user.** Audits what is configured, especially in an unfamiliar repository.
+
+### Core scenarios
+
+1. "What do I have across all my agents?" → `agt-env`
+2. "Which MCP servers can Codex use here?" → `agt-env -a codex -k mcp`
+3. "Where does this skill come from, and who else has it?" → `agt-env -n my-skill --detail`
+4. "What does this repo add to my agents?" → `agt-env --scope project`
+
+## 5. Functional requirements
+
+Priorities: **P0** is required for v1, **P1** follows soon after, and **P2** is later.
+
+### 5.1 Commands
+
+| Command | Purpose | Priority |
+|---|---|---|
+| `agt-env [keyword...]` | Agents and their items, filterable | P0 |
+| `agt-env probe` | Opt-in live checks through agent CLIs (see 5.5) | P2 |
+
+Agents appear in rank order (see section 6), each with a header showing its state and config location, followed by its items sorted by scope (project, user, system), then kind, then name.
+
+**Flags:** `--all`, `--detail`, `-a`/`--agent <agent>` (repeatable), `-n`/`--name <text>` (repeatable), `-k`/`--kind <kind>` (repeatable), `-s`/`--scope project|user|system`, `-p`/`--project <path>`, `--no-color`.
+
+**Filters:** different filters narrow each other.
+
+- `-a` shows only the named agents, even ones hidden by default. It takes an agent's ID, or `claude` for `claude-code` and `agy` for `antigravity`.
+- `-n` matches a case-insensitive part of the item name. Repeating it widens the results.
+- Keywords match a case-insensitive part of everything shown for an item, including its details and path. Words in one argument narrow and separate arguments widen, so `agt-env "browser test" lint` finds (browser and test) or lint.
+- With `-n` or keywords, agents with no matches are left out. If none are left, the output says so.
+
+**Illustrative output:**
+
+```text
+$ agt-env
+agent-a  ~/.agent-a
+  SCOPE/KIND  NAME        STATUS
+  P/skill     repo-skill  enabled
+  U/skill     my-skill    enabled
+  U/mcp       my-server   enabled
+  U/plugin    my-plugin   disabled
+
+agent-b  /opt/agent-b (set by AGENT_B_HOME)
+  SCOPE/KIND  NAME      STATUS
+  U/skill     my-skill  enabled
+  U/plugin    other     unknown
+
+Hidden: agent-c, agent-d. Use --all for details.
+```
+
+`P`, `U`, and `S` stand for the project, user, and system scopes. `--detail` adds lines under each item, starting at the `NAME` column, for everything the columns don't show, and a line of dashes after the table head and between items:
+
+```text
+$ agt-env -a agent-b -n my-skill --detail
+agent-b  /opt/agent-b (set by AGENT_B_HOME)
+SCOPE/KIND  NAME
+--------------------
+U/skill     my-skill
+            Status:       enabled
+            Description:  Does a thing
+            Path:         /opt/agent-b/skills/my-skill (symlink)
+            Real path:    /opt/shared/my-skill
+            Shared with:  agent-a
+```
+
+What a plugin brings is listed directly below its row, when that row is shown. If a filter hides the plugin, those items take their normal place.
+
+Problems are shown with the items they affect, in the same output, with no separate command. Each finding is a row directly below its item, starting where the `DESCRIPTION` column starts, or at `NAME` if a narrow terminal leaves too little room. An agent without any looks as above. With `--detail`, each finding is a `Finding:` line among the item's details.
+
+```text
+$ agt-env -a agent-a
+agent-a  ~/.agent-a
+  SCOPE/KIND  NAME      STATUS
+  P/skill     my-skill  shadowed
+                                  ! shadowed by ~/.agent-a/skills/my-skill
+  U/skill     my-skill  enabled
+  U/skill     old       broken
+                                  ! symlink target is missing
+```
+
+Findings can be searched like everything else shown for an item, and they don't change the exit code. A config file that can't be read stays a warning on stderr (FR-17).
+
+With `--all`, hidden agents are added with their state:
+
+```text
+agent-c  not installed, configured at ~/.agent-c
+agent-d  installed, not configured
+```
+
+### 5.2 Capability kinds
+
+| Kind | Meaning | Priority |
+|---|---|---|
+| `skill` | Skill directory or file, usually `SKILL.md` | P0 |
+| `mcp` | Configured MCP server | P0 |
+| `plugin` | Plugin or extension, with the agent's own term kept in `native_kind` | P0 |
+| `hook` | Lifecycle hook | P1 |
+| `subagent` | Custom agent definition | P1 |
+| `command` | Custom slash command | P1 |
+| `instructions` | Agent instruction and rules files | P2 |
+
+### 5.3 Discovery
+
+- **FR-1 (P0):** Detect each agent independently through its binary on `PATH` and its config locations, and report the two separately. An agent is configured if it has config at user or project scope. A version-manager shim on `PATH` counts as a binary, but detection must not execute it.
+- **FR-2 (P0):** Discover items at user and project scope. The current directory, or `--project` if given, is assumed to be the project root. Parent directories are not searched, so running from a subdirectory doesn't find the project's items. System-level locations are read where the agent defines them.
+- **FR-3 (P0):** Get all results by reading files on disk. Only `probe` (FR-14) may run other programs, so all other commands must not launch agent CLIs or start MCP servers.
+- **FR-4 (P0):** Determine status from the agent's own configuration. An item in a plugin cache that is not enabled must not be reported as `enabled`.
+- **FR-5 (P0):** Follow symlinks and record both the path found and the resolved path. Report a dangling symlink as `broken`.
+- **FR-6 (P0):** Treat items that resolve to the same real path as shared, naming the other agents under `--detail`, while still listing them under each agent.
+- **FR-8 (P1):** When an agent's precedence rules mean a same-named item is used instead, report the item as `shadowed` and show a finding naming the winner. Only rules with evidence count, so an agent whose rule isn't known is never flagged.
+- **FR-23 (P1):** Show why each `broken` item is broken. The reason is fixed text, never file contents.
+- **FR-24 (P1):** List hooks, custom agents, and custom commands wherever the agent has them, by the same rules as other items: a status from evidence, and the plugin named under `--detail`. A hook is named by its event and matcher unless the agent gives it a name. Its description is what it runs, with anything that looks like a secret masked (FR-12).
+- **FR-9 (P1):** List skills that plugins and packages bring, under the name the agent gives them, such as `my-plugin:my-skill`, and with `--detail` name the plugin. A skill follows its plugin's status, and one whose plugin is off or missing isn't listed.
+- **FR-10 (P0):** Only treat a directory as a skill if it meets the agent's definition. A directory that only groups other skills must be descended into or skipped, not counted.
+- **FR-20 (P0):** Resolve locations from the environment, not fixed paths: honor `HOME`, XDG variables, and each agent's documented config-directory overrides. When an override moves an agent's location away from its default, the output shows the location in use and the variable that set it in the agent's header.
+- **FR-21 (P0):** Work from any starting state. With no agents detected, or an agent's directories missing or unreadable, the tool still succeeds and says what it found. A missing location isn't a warning; an unreadable one is.
+- **FR-22 (P0):** By default, only agents that are both installed and configured are shown, and the output names the agents it hid. `--all` shows every detected agent, and `-a` always shows the agent it names, in each case with its state.
+
+### 5.4 Data model
+
+Every item has these fields, and adapters must fill them consistently:
+
+| Field | Meaning | Example |
+|---|---|---|
+| `id` | Unique identity of the item | `agent-a:skill:user:my-skill` |
+| `name` | Display name | `my-skill` |
+| `kind` | Normalized kind (see 5.2) | `plugin` |
+| `native_kind` | The agent's own term | `plugin` |
+| `agent` | Agent ID (see section 6) | `agent-a` |
+| `scope` | `user`, `project`, or `system` | `user` |
+| `status` | `enabled`, `disabled`, `pending` (waiting for the user to approve or trust it), `broken`, `shadowed` (a same-named item is used instead), or `unknown` | `enabled` |
+| `description` | Short description, if the source has one | What the skill does and when to use it. |
+| `source_path` | Where the item was found | `/home/me/.agent-a/skills/my-skill` |
+| `resolved_path` | Real path after following symlinks | `/home/me/shared-skills/my-skill` |
+| `shared_with` | Other agents using the same real path | `agent-b` |
+| `details` | Kind-specific information | See below |
+| `findings` | Problems to show with the item, such as why it's broken | `symlink target is missing` |
+
+**MCP `details`** contains transport, command or URL, and the *names* of env vars and headers, never their values.
+
+### 5.5 Safety
+
+- **FR-11 (P0):** Never modify files in agent config directories or anywhere else.
+- **FR-12 (P0):** Never display secret values in any output. Env values, header values, tokens, and URL credentials are omitted or masked. A hook's command or prompt is free text, so it's shown after masking the forms a secret usually takes, which can't catch a secret that looks like any other word. Agent credential stores are never opened. A skill file that is a symlink to anything but a Markdown file isn't opened, and the skill is reported as `broken`, because a skill's text can become its description and a cloned repository could otherwise display any file.
+- **FR-13 (P0):** Never run code from inspected configuration. Listing an MCP server must not start it, because a repository's project config can name any command.
+- **FR-14 (P2):** `probe` is the only command that may run other programs. It must be explicitly invoked, apply a timeout per agent, and show what it will execute.
+- **FR-15 (P0):** Treat inspected file contents as untrusted. Strip terminal escape sequences from names and descriptions before display.
+
+### 5.6 Output and errors
+
+- **FR-16 (P0):** On a color terminal, show each agent in a colored panel, with a symbol and a color for each status. The status column has no words, and its heading is `S`. Scopes are written `Prj`, `Usr`, and `Sys` under the heading `SCOPE`, and the description starts with the item's kind, as in `SKILL: Does a thing`. Each kind other than `skill` has its own color on its name. With `--detail` there is no status column, in either output, and the status is one of the details. Use plain aligned text when piped, with `--no-color`, when `NO_COLOR` is set, when `TERM` is `dumb`, or when the output encoding isn't UTF-8. The illustrative output above is the plain form. Without `--detail`, the terminal table also shows the start of each description, cut to the space left in the terminal, and leaves the column out when too little space is left. Other long values wrap on a terminal and are never cut.
+- **FR-17 (P0):** A broken config for one agent must not stop the others. It produces a warning on stderr naming the agent and file, and items from that agent's other sources still appear.
+- **FR-18 (P0):** Exit codes: `0` for success, including partial results with warnings and empty results; `1` for a fatal runtime error; `2` for a usage error.
+- **FR-19 (P0):** Unknown fields in agent configs are ignored without error, so a new agent release doesn't break parsing.
+
+## 6. Agent support
+
+Each agent is one adapter behind a common interface: detect the agent, then return items and warnings. An adapter must not depend on any other adapter.
+
+Adapters are built in rank order. P0 agents are required for v1, and P2 agents are added after v1, when there is demand.
+
+| Rank | Agent | ID | Priority |
+|---|---|---|---|
+| 1 | Claude Code | `claude-code` | P0 |
+| 2 | Codex | `codex` | P0 |
+| 3 | OpenCode | `opencode` | P0 |
+| 4 | Pi | `pi` | P0 |
+| 5 | Antigravity CLI | `antigravity` | P0 |
+| 6 | Gemini CLI | `gemini` | P2 |
+| 7 | Cursor | `cursor` | P2 |
+| 8 | GitHub Copilot CLI | `copilot` | P2 |
+| 9 | Amp | `amp` | P2 |
+| 10 | Qwen Code | `qwen` | P2 |
+| 11 | Crush | `crush` | P2 |
+| 12 | Kiro | `kiro` | P2 |
+| 13 | Goose | `goose` | P2 |
+| 14 | Cline | `cline` | P2 |
+| 15 | Windsurf | `windsurf` | P2 |
+
+The ranking can change without affecting the architecture.
+
+### Adapter rules
+
+- Each adapter declares its locations, formats, scopes, and precedence rules, taken from the agent's documentation and a clean install. They live with the adapter rather than in this PRD, because they change with agent releases.
+- Every format claim in an adapter is backed by a fixture and the agent version it was checked against.
+- Tests run against fixtures in an isolated `HOME`, never against a developer's real configuration.
+- Where an agent has a read-only listing command, it is used as a test oracle during development, not at runtime.
+- An adapter attributes a cross-agent shared location to an agent only if that agent is confirmed to read it.
+- Agents without an adapter are ignored: they aren't detected, listed, or mentioned in any output.
+
+## 7. Non-functional requirements
+
+| Area | Requirement |
+|---|---|
+| **Performance** | The default listing finishes in under 200 ms, in plain and terminal output, on a reference fixture of 5 agents and 500 items, on a typical developer laptop; no subprocesses are spawned. The target excludes the time `uvx` needs to set up its environment |
+| **Distribution** | Published to PyPI and runnable with `uvx agt-env`, with no prior install; `uv tool install` also works. Requires Python 3.11 or later, with as few third-party dependencies as practical; Rich is used for terminal output, and plain output doesn't load it |
+| **Portability** | Linux and macOS, on any home directory layout, shell, or version manager |
+| **Extensibility** | A new adapter touches only its own module, fixtures, and one registry line |
+
+**Implementation language:** Python.
+
+## 8. Success metrics
+
+These are acceptance checks, run against fixtures in CI, except where noted:
+
+1. **Accuracy:** for each P0 agent, MCP results match that agent's own listing command on the same fixture, wherever such a command exists. This needs the real agents, and some need a signed-in account, so it runs by hand before each release rather than in CI.
+2. **No false claims:** no item is reported as `enabled` without evidence in that agent's config.
+3. **Secret safety:** a test config with planted secrets produces no secret text in any command's output, planted credential stores are never opened, and no file changes.
+4. **Inertness:** a test project config naming a marker-writing command leaves no marker after any P0 command.
+5. **Resilience:** corrupting any single agent's config still produces full results for the others, with exit code 0 and a warning.
+6. **Clean start:** with an empty `HOME` and no agents on `PATH`, `agt-env` exits 0 with a clear message.
+7. **Speed:** the 200 ms target holds on the reference fixture on a developer machine. CI only reports the timings, because shared runners vary too much for a time limit.
+8. **Zero-install run:** in a clean environment, `uvx` runs the built package and `agt-env` produces correct output.
+
+## 9. Risks
+
+| Risk | Mitigation |
+|---|---|
+| Agent formats change often and without notice | Tolerant parsing, per-adapter fixtures, and visible warnings instead of crashes |
+| Users read the output as exactly what a session has loaded | Label output as configured state; document the gaps; add `probe` later |
+| Enablement rules are undocumented or complex | Use `unknown` status rather than guessing |
+| Secrets leak through unexpected fields, such as credentials in MCP args | Allowlist the fields to display; mask URL credentials and values following secret-like flags |
+| Terminal injection through a malicious skill description | Sanitize all displayed strings (FR-15) |
+
+## 10. Milestones
+
+1. **M1, foundation:** data model, adapter interface, skill discovery, Claude Code and Codex adapters, listing, packaging for `uvx`.
+2. **M2, P0 complete:** remaining P0 adapters, MCP and plugins, details and filters, safety tests.
+3. **M3, diagnostics:** findings in the normal output (why items are broken, and shadowing), plugin-bundled skills, hooks, subagents, commands.
+4. **M4, breadth:** `probe`, and P2 adapters in rank order as demand appears.
+
+## 11. Decisions and open questions
+
+### Decisions made for this draft
+
+| Decision | Reasoning |
+|---|---|
+| Read-only in v1 | Keeps the tool safe to run anywhere and the scope small |
+| Static inspection by default | Fast and inert, with no dependence on an agent's startup, authentication, or network |
+| Unified `plugin` kind | "Plugin" and "extension" vary by agent; `native_kind` keeps the original term |
+| Shared items listed under each agent | Each agent really can use them; sharing is shown separately |
+
+### Open questions
+
+1. **Runtime gap:** should built-in skills and account-level connectors, which aren't in local config, be documented as out of scope permanently, or added through `probe`?
+2. **Shared skill directories:** some skill directories sit outside any one agent's own config and may be read by several agents. Which of these directories exist, and which agents read each one? This decides which agents a skill is listed under: the output could otherwise claim an agent has a skill it never loads, or miss one it does. The answer is needed for each agent when its adapter is built. Until it is confirmed, skills from that directory aren't listed under that agent.