Metadata-Version: 2.4
Name: agentpeek
Version: 0.12.1
Summary: TUI inspector for agent CLI configuration directories like ~/.claude/.
Project-URL: Homepage, https://github.com/rattle99/agentpeek
Project-URL: Repository, https://github.com/rattle99/agentpeek
Project-URL: Issues, https://github.com/rattle99/agentpeek/issues
Author-email: rattle99 <24495512+rattle99@users.noreply.github.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: agent-cli,claude,claude-code,config,inspector,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
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
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: textual>=0.80.0
Description-Content-Type: text/markdown

# agentpeek

[![PyPI](https://img.shields.io/pypi/v/agentpeek?style=for-the-badge&logo=pypi&logoColor=white&color=e68e6e)](https://pypi.org/project/agentpeek/)
[![Python](https://img.shields.io/pypi/pyversions/agentpeek?style=for-the-badge&logo=python&logoColor=white&color=e68e6e)](https://pypi.org/project/agentpeek/)
[![License](https://img.shields.io/badge/license-GPL--3.0-e68e6e?style=for-the-badge)](LICENSE)

A TUI for inspecting agent CLI configurations: what's installed, what's enabled, what's broken.

agentpeek scans your Claude Code config (`~/.claude/` and any project-level `.claude/` directory it finds by walking up from `cwd`) and surfaces every loose file the agent depends on: settings, hooks, slash commands, memory files, MCP servers, installed plugins (with their full contents: manifest, skills, agents, commands, hooks, MCPs), and any health warnings detected during the scan.

## Install

    pipx install agentpeek

Then:

    agentpeek                      # scan ~/.claude and the nearest project .claude
    agentpeek --root /path/to/dir  # scan a specific directory
    agentpeek --version

Requires Python ≥ 3.11. Linux and macOS only.

## What you get

- **Three-zone TUI**: sidebar of 9 categories on the left, items list in the middle, detail pane on the right. Drill-down on every category.
- **Multi-scope**: user-scoped (`~/.claude/`) and project-scoped (`.claude/` found by walking up from cwd) configurations shown side by side with `[U]` / `[P]` badges. Health checks compare the two and flag conflicts.
- **Plugin contents**: every installed plugin is opened up - manifest, skills, agents, slash commands, hooks, MCP servers, and the marketplace's auto-update state. Plugin-contributed commands / hooks / MCPs also merge into the top-level categories with a `[plug:<id>]` provenance tag.
- **Auto-memory**: Claude Code project memories (under `~/.claude/projects/<encoded>/memory/`) are scanned and labelled with their actual project path (resolved from session logs, not the lossy directory encoding).
- **Health checks**: orphan hook scripts, missing plugin install paths, conflicting key bindings, scope override conflicts, cross-scope layered memory, hooks referencing dynamic env vars (`${CLAUDE_PROJECT_DIR}`, `$HOME`, …) flagged so you know which won't resolve at scan time, and more. Severity-coloured warning cards in the detail pane.
- **Write actions**: update, enable/disable, uninstall a plugin or refresh a marketplace without leaving the TUI. Calls shell out to `claude plugin …`; agentpeek never edits Claude state files directly. Re-scan is automatic after every action. Pass `--read-only` to disable.

## Keybindings

| Key | Action |
|---|---|
| `↑` / `↓` | Move within the focused list |
| `Tab` / `Shift+Tab` | Move focus between sidebar / items / detail |
| `Enter` | Drill into the highlighted item; on a Skills or Agents row inside a plugin, opens a detail modal |
| `r` | Re-scan disk |
| `o` | Open the highlighted item's file in `$EDITOR` (TUI suspends + resumes) |
| `y` | Yank the highlighted item's path to the clipboard (OSC 52) |
| `b` | Yank the rendered body. Works on memory entries, slash commands, skills, agents, hooks |
| `u` | Update the highlighted plugin |
| `U` | Update all installed plugins (progress in the title bar) |
| `t` | Toggle enable / disable for the highlighted plugin |
| `x` | Uninstall the highlighted plugin (confirms first) |
| `M` | Refresh the highlighted marketplace |
| `/` | Show + focus the filter input (live-filters the items list) |
| `Esc` | Clear filter and refocus items |
| `?` | Help overlay listing every binding |
| `q` | Quit |

The filter shows `(filtered: N / M)` in the title while active. Press Enter inside the filter to keep the filter and jump back to the items list; press Esc to clear.

## Theming

Built on Textual: the theme follows `Ctrl+P` (palette) and reflows colours across cards, borders, badges, and severity indicators. Default theme is `textual-dark`.

## Supported agent CLIs

- **Claude Code**: full support today.
- Support for other agents (Codex, Gemini CLI, Cursor) coming.

## License

GPL-3.0-only. See `LICENSE`.
