---

Latest News 🔥

• [2026/01] Released v0.1.2 with colored output and search functionality
• [2026/01] Released v0.1.1 with -l flag support and npm package
• [2026/01] Published to crates.io - now installable via cargo install claude-list
• [2026/01] Added Homebrew support with cargo-dist multi-platform builds

---

Why claude-list?

A Rust CLI tool that follows Unix philosophy—do one thing well. It reads your Claude Code .claude directory and presents key information in a clean, minimal format with modern aesthetics.

• 🎨 Clean Output - Human-readable compact format by default
• 🔍 Detailed Views - Version, source, and path information on demand
• 🤖 Scriptable - JSON output for automation and integration
• ⚡ Fast - Sub-second execution (< 0.03s)
• 🔒 Safe - Handles missing files and partial data gracefully
• 📦 Multi-Platform - Pre-built binaries for Linux and macOS

---

Quick Start

# Install via Homebrew (macOS)
brew tap elliotxx/tap && brew install elliotxx/tap/claude-list

# OR via shell script (Linux/macOS)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elliotxx/claude-list/releases/latest/download/claude-list-installer.sh | sh

# View your Claude Code environment
claude-list

Need more details? See Installation below for all installation options.

---

Features

Output Modes

Mode	Command	Description
Compact	claude-list	Summary with counts (colored by type)
Detailed	claude-list -l	Full info with version, source, path
JSON	claude-list --json	Machine-readable output

Colored Output

Components are displayed with distinct colors for easy identification:

Component Type	Color
Plugins	Blue
Skills	Green
MCP Servers	Yellow
Hooks	Magenta
Agents	Red
Commands	Orange

Colors are automatically disabled when:

• Using --no-color flag
• NO_COLOR environment variable is set
• Output is piped or redirected

Search

Search for components by name with flexible matching:

# Single keyword (case-insensitive)
claude-list --search context

# Multiple keywords (AND logic - all must match)
claude-list --search "context plugin"

# Combine with filters
claude-list --search api --plugins

Filtering

Filter to show specific component types:

claude-list --plugins    # Only plugins
claude-list --skills     # Only skills
claude-list --sessions   # Only sessions
claude-list --mcp        # Only MCP servers
claude-list --hooks      # Only hooks
claude-list --agents     # Only agents
claude-list --commands   # Only commands

# Combine filters
claude-list --plugins --skills

Custom Configuration Directory

claude-list --config /path/to/.claude

---

Demo

Command-line Output

Here's what claude-list looks like in action:

Output Examples

Compact Mode (Default)

CLAUDE-LIST v0.1.2

CONFIG: /Users/user/.claude

PLUGINS    3 installed
  context7
  plugin_playwright
  plugin_example

SKILLS     12 available
  brainstorming
  claude-code-guide
  ...

SESSIONS   47 recorded
MCP        2 servers
  test-mcp
  another-mcp

Detailed Mode (-l)

CLAUDE-LIST v0.1.2

CONFIG: /Users/user/.claude

PLUGINS    3 installed
  NAME                 VERSION  SOURCE     PATH
  -------------------  -------  ---------  ---------------------------------
  context7             2.1.0    official   /Users/user/.claude/settings.json
  plugin_playwright    1.0.0    third-party /Users/user/.claude/settings.json
  plugin_example       0.5.0    community  /Users/user/.claude/settings.json

JSON Mode (--json)

{
  "version": "0.1.2",
  "config_dir": "/Users/user/.claude",
  "plugins": [...],
  "skills": [...],
  "sessions": {...},
  "mcp_servers": [...],
  "hooks": [...],
  "agents": [...],
  "commands": [...]
}

---

Installation

Option 1: From Homebrew (macOS)

brew tap elliotxx/tap && brew install elliotxx/tap/claude-list

Option 2: From Shell Script (Linux/macOS)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elliotxx/claude-list/releases/latest/download/claude-list-installer.sh | sh

Option 3: From npm

npm install -g @elliotxx/claude-list

Option 4: From crates.io

cargo install claude-list

Option 5: From GitHub Releases

Download pre-built binaries from GitHub Releases:

# Linux (x86_64)
wget https://github.com/elliotxx/claude-list/releases/latest/download/claude-list-x86_64-unknown-linux-gnu.tar.gz
tar -xzf claude-list-x86_64-unknown-linux-gnu.tar.gz
./claude-list

# macOS (Apple Silicon)
wget https://github.com/elliotxx/claude-list/releases/latest/download/claude-list-aarch64-apple-darwin.tar.gz
tar -xzf claude-list-aarch64-apple-darwin.tar.gz
./claude-list

Option 6: From Source

git clone https://github.com/elliotxx/claude-list.git
cd claude-list
cargo build --release
cargo install --path .

---

Architecture

Component Architecture

┌─────────────────────────────────────────────────────────┐
│                      User Input                          │
│                    (CLI Arguments)                       │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  Main Entry Point (src/main.rs)                         │
│  • Parse CLI arguments                                  │
│  • Dispatch to formatters                               │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  Parser Layer (src/parsers/)                            │
│  • plugins.rs    → Parse installed plugins              │
│  • skills.rs     → Parse skills                         │
│  • sessions.rs   → Parse session history                │
│  • mcp.rs        → Parse MCP servers                    │
│  • hooks.rs      → Parse hooks                          │
│  • agents.rs     → Parse agents                         │
│  • commands.rs   → Parse commands                       │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  Formatter Layer (src/formatters/)                      │
│  • compact.rs    → Human-readable summary               │
│  • detailed.rs   → Full info with version/source/path   │
│  • json.rs       → Machine-readable JSON output         │
└─────────────────────────────────────────────────────────┘

Key Design Decisions

• Pattern Used: Unix philosophy—single responsibility, compose simple tools
• Technology Stack: Rust 1.75+, clap (CLI), serde (JSON), anyhow (error handling), anstyle (colors), unicode-width (ANSI width)
• Scalability: Each parser is independent, easy to extend
• Error Handling: Graceful degradation for missing files

Supported Data Sources

Component	Format	Location
Plugins	JSON	.claude/plugins/installed_plugins.json
Skills	YAML	.claude/skills/*/skill.yaml
MCP Servers	Directory/YAML	.claude/mcp-servers/*/
Sessions	JSON Lines	.claude/history.jsonl
Commands	Markdown	.claude/commands/*.md
Agents	Markdown	.claude/agents/*.md
Hooks	Markdown	.claude/hooks/*.md

---

Development

Prerequisites

• Rust 1.75+
• Cargo

Quick Start

# Run all checks
cargo fmt && cargo clippy && cargo test

# Run tests only
cargo test

# Run integration tests
cargo test --test cli_test

Building

# Debug build
cargo build

# Release build
cargo build --release

# Check format
cargo fmt --check

# Run clippy
cargo clippy --all-features -- -D warnings

Testing

# Run all tests
cargo test --all-features

# Run with verbose output
cargo test --all-features --verbose

# Run specific test
cargo test test_name

---

Publishing

Releases are automated via cargo-dist:

1. Push a git tag matching x.y.z (e.g., 0.1.1)
2. CI pipeline triggers automatically:
   • Plan: Generate build manifest
   • Build: Multi-platform builds (x86_64 Linux, x86_64/aarch64 macOS)
   • Publish: GitHub Release + Homebrew

Release Process

# 1. Update version in Cargo.toml
# Edit Cargo.toml: version = "0.1.2" → "0.1.3"

# 2. Commit version change
git add -A && git commit -m "chore: bump version to 0.1.3"

# 3. Create git tag
git tag 0.1.3

# 4. Push to GitHub (including tags)
git push && git push --tags

# 5. After CI completes, manually publish to crates.io
cargo publish

Note: Publishing to crates.io requires manual cargo publish as cargo-dist does not support automatic crates.io publishing.

CI Tokens Required

Secret	Purpose	Location
CARGO_REGISTRY_TOKEN	Publish to crates.io	crates.io/settings/tokens
HOMEBREW_TAP_TOKEN	Publish to Homebrew	GitHub Settings
NPM_TOKEN	Publish to npm (requires 2FA bypass)	npmjs.com/settings/tokens

---

Contributing

We welcome contributions! Feel free to submit issues and pull requests.

Contribution Areas

• Feature Development: Add new parsers or formatters
• Bug Fixes: Fix issues and improve stability
• Documentation: Improve guides and examples
• Testing: Add tests and improve coverage

Quick Start for Contributors

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/elliotxx/claude-list.git
cd claude-list

# Follow installation steps above

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes, test, then commit and push
git add .
git commit -m "feat: description"
git push origin feature/your-feature-name

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• Claude Code for the inspiration
• clap for CLI argument parsing
• cargo-dist for automated releases

---