typer-agentic 0.1.1__tar.gz

typer_agentic-0.1.1/.claude/hooks/session-start.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -euo pipefail
+
+CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$CLAUDE_PROJECT_DIR"
+
+# Report venv status for the user's outer shell.
+# Affects both user-typed `! cmd` and Claude's Bash subprocesses (which inherit the parent shell's env).
+# When unactivated, prefer `uv run <tool>` for venv binaries.
+project_venv="$CLAUDE_PROJECT_DIR/.venv"
+if [ -z "${VIRTUAL_ENV:-}" ]; then
+  echo "venv not activated in the user's outer shell — \`! cmd\` will not see .venv/bin. Suggest activating: fish \`source .venv/bin/activate.fish\`, bash/zsh \`source .venv/bin/activate\`."
+elif [ "$VIRTUAL_ENV" != "$project_venv" ]; then
+  echo "VIRTUAL_ENV is '$VIRTUAL_ENV' but project venv is '$project_venv'."
+fi
+
+# Remote-only setup (Claude Code on the web)
+if [ "${CLAUDE_CODE_REMOTE:-}" = "true" ]; then
+  uv sync --quiet
+  bash scripts/install-hooks.sh
+fi

typer_agentic-0.1.1/.claude/settings.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run tyf:*)",
+      "Bash(uv run biston:*)",
+      "Bash(uv run poe:*)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

typer_agentic-0.1.1/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "python"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "dependencies"
+      - "ci"

typer_agentic-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,103 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+
+  format:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --frozen
+      - run: uv run ruff format --check .
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --frozen
+      - run: uv run ty check
+
+  vulns:
+    name: Dependency Vulnerabilities
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --frozen
+      - run: uvx pysentry-rs .
+        continue-on-error: true
+
+  dead-code:
+    name: Dead Code Detection
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --frozen
+      - run: uv run vulture src
+
+  unused-deps:
+    name: Unused Dependencies
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --frozen
+      - run: uv run deptry .
+
+  clones:
+    name: Clone Detection
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --frozen
+      - run: uv run biston scan .
+        continue-on-error: true
+
+  test:
+    name: Test (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --frozen
+      - run: uv run pytest -q --tb=short
+
+  test-compat:
+    name: Test (typer 0.25, external click)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv run --no-project --with "typer==0.25.*" --with pytest --with . pytest tests -q -o addopts= -p no:cacheprovider

typer_agentic-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/typer-agentic
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true

typer_agentic-0.1.1/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+*.so
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# workflow scratch dirs
+cf/
+cml/
+di/

typer_agentic-0.1.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- `agent_errors(app)` wrapper: structured, retry-oriented usage errors when an agent drives the CLI; Typer's own output for humans.
+- Auto-detection via `CLAUDECODE` and friends, `AGENT_ERRORS` env toggle, `--agent-errors` / `--human-errors` sentinel flags.
+- Markdown (default) and JSON renderers; `typer-agentic/v1` schema.
+- Parameter inventory with normalised types and choices, ranked suggestions, one synthesised corrected example.
+- De-escalation copy in `copy.py`.
+- `compat.py`: works with vendored (`typer._click`, Typer >= 0.26) and external Click; transparent passthrough if neither resolves.
+- Optional repeat-failure escalation (`repeat_detection=True`).
+- `--agent-skill` / `render_skill()` SKILL.md emitter.

typer_agentic-0.1.1/CLAUDE.md

@@ -0,0 +1,53 @@
+# typer-agentic
+
+Typer extension that makes CLIs friendly to coding agents. Package: `src/typer_agentic/`, published to PyPI as `typer-agentic`.
+
+Design and build prompts live in `docs/plans/`. Read the current plan before starting non-trivial work.
+
+## Commands
+
+- `uv run poe check` — lint, typecheck, dead code, unused deps, clones, then fail-fast tests
+- `uv run poe check-fast` — lint + typecheck only
+- `uv run poe fix` — auto-format and fix lint issues
+- `uv run poe test` — tests with coverage (parallel)
+- `uv run poe check-all` — every check, report all failures
+- `uv run poe release` — bump patch version, tag, push (`level=minor|major` to override)
+
+## Code Search (`tyf`)
+
+This project has `tyf` (ty-find) — type-aware code search that gives LSP-quality results by symbol name. Prefer it over grep for Python symbols. Reserve grep for string literals, config values, TODOs, non-Python files.
+
+- `uv run tyf show <name>` — definition + signature + usages (flags: `-d` docs, `-r` refs, `-t` test refs, `--all`)
+- `uv run tyf find <Symbol>` — locate definition
+- `uv run tyf refs <name>` — find all usages
+- `uv run tyf members <Class>` — view class API
+- `uv run tyf calls <name>` — call tree (`--in` for callers)
+- `uv run tyf list <file.py>` — file outline
+
+All commands accept multiple symbols — batch to save tool calls.
+
+## Clone Detection (`biston`)
+
+Structural clone detector for Python — finds functions that are structurally similar even when names/literals/argument order differ. Run after producing multiple similar functions, or when refactoring, to spot extraction opportunities.
+
+- `uv run biston scan --suggest .` — find clones with anti-unified template proposals
+- `uv run biston scan --tests-only .` — test-duplication scan
+- `uv run biston overview .` — condensed file-centric summary
+- `uv run biston guide triage` — what to do with findings
+
+## Stack
+
+uv, ruff (lint/format), ty (type check), tyf (code search), biston (clone detection), pytest (+xdist, randomly), poethepoet (task runner), hatchling (build)
+
+## Development Workflow
+
+- TDD: failing test first, then implementation. Bug fixes include a regression test.
+- All public behavior must have tests in `tests/`.
+- When a test fails, diagnose before changing it. Default assumption: the test is right. Never weaken an assertion just to make it pass.
+- **IMPORTANT**: After completing any task, run the `/python-review` skill. Apply all 🔴 Must Fix and 🟡 Should Fix findings before marking work complete.
+
+## Notes
+
+- ty is in beta — may produce false positives. Prefer `# ty: ignore[rule]` over blanket suppression.
+- Pre-commit hook auto-fixes and restages files. Only blocks on unfixable issues.
+- Keep `typer` the only runtime dependency unless a plan explicitly adds one.

typer_agentic-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mojzis
+
+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.

typer_agentic-0.1.1/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: typer-agentic
+Version: 0.1.1
+Summary: Typer extension that makes CLIs friendly to coding agents
+Project-URL: homepage, https://github.com/mojzis/typer-agentic
+Project-URL: repository, https://github.com/mojzis/typer-agentic
+Project-URL: documentation, https://github.com/mojzis/typer-agentic#readme
+Author-email: mojzis <mojzisek@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,claude-code,cli,llm,typer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.24
+Description-Content-Type: text/markdown
+
+# typer-agentic
+
+A [Typer](https://typer.tiangolo.com/) extension that makes CLIs friendly to coding agents.
+
+When an LLM agent misspells a flag or omits an argument, Typer prints a Rich panel and exits 2. The agent then either burns turns re-reading `--help`, or, worse, gives up on the tool and starts editing files by hand. `typer-agentic` intercepts usage errors and, **only when an agent is driving**, replaces the panel with a compact block: what went wrong, the valid parameters with types and choices, exactly one corrected example, and calm instructions that keep the agent on the retry path. Humans keep Typer's stock output, byte for byte.
+
+## Quickstart
+
+```python
+from typer_agentic import agent_errors
+
+app = typer.Typer()
+...
+main = agent_errors(app)  # use `main` as your [project.scripts] entry point
+```
+
+Nothing else changes. `agent_errors(app)` returns a zero-argument callable, never mutates the app, and never monkeypatches Typer or Click.
+
+## Before / after
+
+`myapp sync --verbos`, Typer 0.27 (stock):
+
+```
+Usage: myapp sync [OPTIONS] {path}
+Try 'myapp sync --help' for help.
+╭─ Error ────────────────────────────────────────────────────────────╮
+│ No such option: --verbos (Possible options: --verbose)             │
+╰────────────────────────────────────────────────────────────────────╯
+```
+
+Same command with `CLAUDECODE=1` in the environment (Claude Code sets it for you):
+
+```
+✗ Usage error in `myapp sync`: No such option: --verbos
+
+This is a recoverable input mistake, not a bug in the tool. Do not switch tools, edit files or state to work around it, or invent flags; apply the one change below and re-run the command.
+
+Did you mean: --verbose
+
+Fix and retry (one change): Replace '--verbos' with '--verbose'. Run the corrected example.
+
+```
+myapp sync ./PATH --verbose
+```
+
+Valid options:
+  --verbose, -v  flag              Enable verbose output.
+  --count        INTEGER           How many.
+  --env          CHOICE[dev|prod]  Target environment.
+
+Required arguments: PATH
+
+Full reference: myapp sync --help
+```
+
+Honest note: Typer already prints a did-you-mean hint. What this adds is the typed inventory, the runnable example, and the de-escalation copy. If you only want the box-drawing gone, `TYPER_USE_RICH=0` does that with no dependency.
+
+## Mode resolution
+
+`mode="auto"` (the default) picks agent or human output per invocation. Highest precedence first:
+
+| # | Signal | Result |
+|---|---|---|
+| 1 | `AgentErrorsConfig(mode="agent" \| "human")` | forced |
+| 2 | `--agent-errors` / `--human-errors` on the command line | agent / human |
+| 3 | `AGENT_ERRORS` env var (`1/true/yes/on` vs `0/false/no/off/empty`) | agent / human |
+| 4 | Any of `CLAUDECODE`, `CLAUDE_CODE`, `CLAUDE_CODE_ENTRYPOINT`, `CODEX`, `CODEX_CLI`, `CURSOR`, `CURSOR_SESSION_ID`, `OPENCODE`, `AGENT` set and non-empty | agent |
+| 5 | `tty_heuristic=True` and stderr is not a TTY | agent |
+| 6 | default | human |
+
+The sentinel flags are consumed by the wrapper before Typer parses anything, so they work even when the rest of the command line is broken. They do not appear in `--help`.
+
+## Format
+
+Markdown (default) is written for a model to read: stable first line `✗ Usage error in \`<command>\`: …`, fixed section order, no ANSI. JSON is for harnesses that parse stderr and retry automatically: select it with `AgentErrorsConfig(format="json")` or `AGENT_ERRORS_FORMAT=json`. The JSON document is the only thing written to the stream. See [SCHEMA.md](SCHEMA.md).
+
+For agent-harness authors: grep the first line for `✗ Usage error`, or set `AGENT_ERRORS_FORMAT=json` and `json.loads(stderr)`.
+
+## Configuration
+
+```python
+from typer_agentic import AgentErrorsConfig
+
+main = agent_errors(
+    app,
+    config=AgentErrorsConfig(
+        mode="auto",  # "agent" | "human" to force
+        format="markdown",  # or "json"
+        stream="stderr",  # or "stdout"
+        env_var="AGENT_ERRORS",
+        format_env_var="AGENT_ERRORS_FORMAT",
+        flag="--agent-errors",  # None disables
+        human_flag="--human-errors",  # None disables
+        skill_flag="--agent-skill",  # None disables
+        max_suggestions=3,
+        include_hidden=False,  # list hidden params too
+        tty_heuristic=False,
+        agent_detect_env_vars=(...),  # see table above
+        intercept_click_exceptions=False,
+        repeat_detection=False,  # see below
+        repeat_state_dir=None,  # defaults to $TMPDIR
+    ),
+)
+```
+
+## SKILL.md for your CLI
+
+Errors are the reactive channel. `myapp --agent-skill` prints an [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) describing every visible command, argument, option and one example per command, so the agent has the inventory before it guesses:
+
+```
+myapp --agent-skill > .claude/skills/myapp/SKILL.md
+```
+
+`render_skill(app)` returns the same text as a string. The library never writes files itself.
+
+## Repeat-failure escalation (opt-in)
+
+Each CLI run is a fresh process, so "the agent is looping" needs a little state. With `repeat_detection=True` the wrapper writes a small JSON record (`$TMPDIR/typer-agentic-<uid>/<prog>.json`, 10-minute TTL, atomic replace) and on the second identical failure adds: *stop retrying variations, read `--help`, rebuild from the example*. On the third it adds: *if that does not resolve it, report the exact error to the user instead of working around it*. Any I/O problem silently disables the feature.
+
+## The copy
+
+All agent-facing text lives in `typer_agentic/wording.py`. If you customise it, keep the rules the defaults follow: one sentence classifying the failure as a recoverable input mistake; one sentence forbidding the panic behaviours (switching tools, editing state around the CLI, inventing flags); exactly one next action; calm, imperative, no exclamation marks, no apologies, no "please"; identical wording across error types.
+
+## Compatibility
+
+- Python 3.11+, `typer>=0.24`, no other runtime dependency. `click` is never imported unconditionally.
+- Typer 0.26+ bundles its own Click under `typer._click`; its exception classes are unrelated to `click.exceptions`. `typer_agentic.compat` resolves whichever hierarchies are present and catches all of them.
+- If resolution fails on some future Typer, `agent_errors(app)` becomes a transparent passthrough and emits one `RuntimeWarning` per process (only in agent mode). Your CLI keeps working; only the feature degrades.
+- Agent mode drives Click's `make_context` / `invoke` loop directly (not `main(standalone_mode=False)`, whose return value cannot distinguish `typer.Exit(n)` from a command returning `n`), so exit codes match stock Typer: `Exit(n)` → `n`, normal return → 0, `Abort` → 1, Ctrl-C → 130. Shell completion is delegated to Typer untouched.
+- Not intercepted, by design: runtime exceptions inside command bodies (they propagate with Typer's pretty-exception hook applied), `NoArgsIsHelpError` (help is printed as usual), `--help` / `--version` / completion.
+- The built-in `--help`, `--install-completion` and `--show-completion` options are omitted from the inventory.
+
+The test suite runs against Typer 0.25 (external Click) and the current release: `uv run poe test-compat`.
+
+## Development
+
+```
+uv sync
+uv run poe setup      # install git hooks
+uv run poe check      # lint, typecheck, dead code, deps, clones, tests
+uv run poe fix        # auto-format + fix lint
+uv run poe test       # tests with coverage
+uv run poe test-compat
+```
+
+Golden files under `tests/golden/` are regenerated with `UPDATE_GOLDEN=1 uv run pytest`.
+
+Release: `uv run poe release` (or `level=minor uv run poe release`) bumps the version, tags, and pushes. The tag triggers the PyPI publish workflow.
+
+## License
+
+MIT

typer_agentic-0.1.1/README.md

@@ -0,0 +1,152 @@
+# typer-agentic
+
+A [Typer](https://typer.tiangolo.com/) extension that makes CLIs friendly to coding agents.
+
+When an LLM agent misspells a flag or omits an argument, Typer prints a Rich panel and exits 2. The agent then either burns turns re-reading `--help`, or, worse, gives up on the tool and starts editing files by hand. `typer-agentic` intercepts usage errors and, **only when an agent is driving**, replaces the panel with a compact block: what went wrong, the valid parameters with types and choices, exactly one corrected example, and calm instructions that keep the agent on the retry path. Humans keep Typer's stock output, byte for byte.
+
+## Quickstart
+
+```python
+from typer_agentic import agent_errors
+
+app = typer.Typer()
+...
+main = agent_errors(app)  # use `main` as your [project.scripts] entry point
+```
+
+Nothing else changes. `agent_errors(app)` returns a zero-argument callable, never mutates the app, and never monkeypatches Typer or Click.
+
+## Before / after
+
+`myapp sync --verbos`, Typer 0.27 (stock):
+
+```
+Usage: myapp sync [OPTIONS] {path}
+Try 'myapp sync --help' for help.
+╭─ Error ────────────────────────────────────────────────────────────╮
+│ No such option: --verbos (Possible options: --verbose)             │
+╰────────────────────────────────────────────────────────────────────╯
+```
+
+Same command with `CLAUDECODE=1` in the environment (Claude Code sets it for you):
+
+```
+✗ Usage error in `myapp sync`: No such option: --verbos
+
+This is a recoverable input mistake, not a bug in the tool. Do not switch tools, edit files or state to work around it, or invent flags; apply the one change below and re-run the command.
+
+Did you mean: --verbose
+
+Fix and retry (one change): Replace '--verbos' with '--verbose'. Run the corrected example.
+
+```
+myapp sync ./PATH --verbose
+```
+
+Valid options:
+  --verbose, -v  flag              Enable verbose output.
+  --count        INTEGER           How many.
+  --env          CHOICE[dev|prod]  Target environment.
+
+Required arguments: PATH
+
+Full reference: myapp sync --help
+```
+
+Honest note: Typer already prints a did-you-mean hint. What this adds is the typed inventory, the runnable example, and the de-escalation copy. If you only want the box-drawing gone, `TYPER_USE_RICH=0` does that with no dependency.
+
+## Mode resolution
+
+`mode="auto"` (the default) picks agent or human output per invocation. Highest precedence first:
+
+| # | Signal | Result |
+|---|---|---|
+| 1 | `AgentErrorsConfig(mode="agent" \| "human")` | forced |
+| 2 | `--agent-errors` / `--human-errors` on the command line | agent / human |
+| 3 | `AGENT_ERRORS` env var (`1/true/yes/on` vs `0/false/no/off/empty`) | agent / human |
+| 4 | Any of `CLAUDECODE`, `CLAUDE_CODE`, `CLAUDE_CODE_ENTRYPOINT`, `CODEX`, `CODEX_CLI`, `CURSOR`, `CURSOR_SESSION_ID`, `OPENCODE`, `AGENT` set and non-empty | agent |
+| 5 | `tty_heuristic=True` and stderr is not a TTY | agent |
+| 6 | default | human |
+
+The sentinel flags are consumed by the wrapper before Typer parses anything, so they work even when the rest of the command line is broken. They do not appear in `--help`.
+
+## Format
+
+Markdown (default) is written for a model to read: stable first line `✗ Usage error in \`<command>\`: …`, fixed section order, no ANSI. JSON is for harnesses that parse stderr and retry automatically: select it with `AgentErrorsConfig(format="json")` or `AGENT_ERRORS_FORMAT=json`. The JSON document is the only thing written to the stream. See [SCHEMA.md](SCHEMA.md).
+
+For agent-harness authors: grep the first line for `✗ Usage error`, or set `AGENT_ERRORS_FORMAT=json` and `json.loads(stderr)`.
+
+## Configuration
+
+```python
+from typer_agentic import AgentErrorsConfig
+
+main = agent_errors(
+    app,
+    config=AgentErrorsConfig(
+        mode="auto",  # "agent" | "human" to force
+        format="markdown",  # or "json"
+        stream="stderr",  # or "stdout"
+        env_var="AGENT_ERRORS",
+        format_env_var="AGENT_ERRORS_FORMAT",
+        flag="--agent-errors",  # None disables
+        human_flag="--human-errors",  # None disables
+        skill_flag="--agent-skill",  # None disables
+        max_suggestions=3,
+        include_hidden=False,  # list hidden params too
+        tty_heuristic=False,
+        agent_detect_env_vars=(...),  # see table above
+        intercept_click_exceptions=False,
+        repeat_detection=False,  # see below
+        repeat_state_dir=None,  # defaults to $TMPDIR
+    ),
+)
+```
+
+## SKILL.md for your CLI
+
+Errors are the reactive channel. `myapp --agent-skill` prints an [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) describing every visible command, argument, option and one example per command, so the agent has the inventory before it guesses:
+
+```
+myapp --agent-skill > .claude/skills/myapp/SKILL.md
+```
+
+`render_skill(app)` returns the same text as a string. The library never writes files itself.
+
+## Repeat-failure escalation (opt-in)
+
+Each CLI run is a fresh process, so "the agent is looping" needs a little state. With `repeat_detection=True` the wrapper writes a small JSON record (`$TMPDIR/typer-agentic-<uid>/<prog>.json`, 10-minute TTL, atomic replace) and on the second identical failure adds: *stop retrying variations, read `--help`, rebuild from the example*. On the third it adds: *if that does not resolve it, report the exact error to the user instead of working around it*. Any I/O problem silently disables the feature.
+
+## The copy
+
+All agent-facing text lives in `typer_agentic/wording.py`. If you customise it, keep the rules the defaults follow: one sentence classifying the failure as a recoverable input mistake; one sentence forbidding the panic behaviours (switching tools, editing state around the CLI, inventing flags); exactly one next action; calm, imperative, no exclamation marks, no apologies, no "please"; identical wording across error types.
+
+## Compatibility
+
+- Python 3.11+, `typer>=0.24`, no other runtime dependency. `click` is never imported unconditionally.
+- Typer 0.26+ bundles its own Click under `typer._click`; its exception classes are unrelated to `click.exceptions`. `typer_agentic.compat` resolves whichever hierarchies are present and catches all of them.
+- If resolution fails on some future Typer, `agent_errors(app)` becomes a transparent passthrough and emits one `RuntimeWarning` per process (only in agent mode). Your CLI keeps working; only the feature degrades.
+- Agent mode drives Click's `make_context` / `invoke` loop directly (not `main(standalone_mode=False)`, whose return value cannot distinguish `typer.Exit(n)` from a command returning `n`), so exit codes match stock Typer: `Exit(n)` → `n`, normal return → 0, `Abort` → 1, Ctrl-C → 130. Shell completion is delegated to Typer untouched.
+- Not intercepted, by design: runtime exceptions inside command bodies (they propagate with Typer's pretty-exception hook applied), `NoArgsIsHelpError` (help is printed as usual), `--help` / `--version` / completion.
+- The built-in `--help`, `--install-completion` and `--show-completion` options are omitted from the inventory.
+
+The test suite runs against Typer 0.25 (external Click) and the current release: `uv run poe test-compat`.
+
+## Development
+
+```
+uv sync
+uv run poe setup      # install git hooks
+uv run poe check      # lint, typecheck, dead code, deps, clones, tests
+uv run poe fix        # auto-format + fix lint
+uv run poe test       # tests with coverage
+uv run poe test-compat
+```
+
+Golden files under `tests/golden/` are regenerated with `UPDATE_GOLDEN=1 uv run pytest`.
+
+Release: `uv run poe release` (or `level=minor uv run poe release`) bumps the version, tags, and pushes. The tag triggers the PyPI publish workflow.
+
+## License
+
+MIT