GitHub - kannandreams/secchi: Opensource Package Intelligence tool

Open Source Package Intelligence

Secchi lets you explore, compare, monitor, and report on package health, adoption, dependencies, releases, and ecosystem signals from your terminal.

How to pronounce it: Secchi is pronounced “SEK-ee.” The name is inspired by the Secchi disk, an instrument used to measure water clarity—an apt metaphor for making package intelligence easier to see.

Try Secchi first

You can try the CLI and open the dashboard without installing Secchi as a permanent command. This uses uvx, which creates a temporary environment and removes it when you are done.

You only need uv installed:

# Print package intelligence in your terminal
uvx --from secchi secchi show duckdb

# Open the interactive dashboard
uvx --from secchi secchi dashboard duckdb

See the available commands before trying a package:

uvx --from secchi secchi --help

If you like what you see, install Secchi permanently with one of the options below. You do not need to run secchi init for direct package exploration; init is only needed when you want to create a workspace configuration for your own projects.

Supported Ecosystems

PyPI Python

npm JavaScript

crates.io Rust

Homebrew Formulae

Go Modules Go

CRAN R

Capabilities

Install

For regular use, install Secchi as a command-line tool:

Quick Start

After installation, scaffold a config file interactively:

Launch the dashboard for a project:

secchi -p duckdb
secchi --project opencode

Explore a package directly, without a configuration file:

secchi show duckdb
secchi dashboard duckdb
secchi search duckdb
secchi compare pypi:duckdb pypi:polars
secchi compare pypi:duckdb pypi:polars --format json
secchi report duckdb --format html --output duckdb-report.html
secchi report --config secchi.toml --project duckdb --format html
secchi check duckdb --min-health 80 --require-ci

Run the MCP server for local AI-agent integrations:

secchi mcp
# or
secchi-mcp

The server communicates over standard input/output and exposes tools for package inspection, cross-registry search, configured project reports, and health policy checks. It reuses the same cached intelligence pipeline as the CLI, dashboard, and report commands.

Use Secchi with MCP

Secchi can be added to an MCP-compatible coding agent or desktop client as a local stdio server. If secchi is installed as a tool, use:

{
  "mcpServers": {
    "secchi": {
      "command": "secchi-mcp"
    }
  }
}

When running from a source checkout with uv, point the client at the project:

{
  "mcpServers": {
    "secchi": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/secchi",
        "secchi-mcp"
      ]
    }
  }
}

The exact configuration file location depends on the MCP client. After the server is added, the agent can use these tools:

Package inspection uses Secchi's local cache by default. Ask the agent to refresh the data when current registry information is required. The MCP server is read-only: it does not modify packages, repositories, or configuration. Successful package results may include signal warnings when an optional source is unavailable; those warnings are preserved instead of turning the package into a failed result.

Reports are written to the current directory by default. Use --output to choose a file path, or --output - to print the report to stdout.

Package inspection includes a Security tab in the dashboard and advisory data in show, JSON, Markdown, HTML, and MCP results. Advisories are queried from OSV.dev for the latest published version. A failed advisory lookup is reported as a non-fatal signal warning; it does not change the health score or policy check result. Homebrew does not currently have a stable OSV ecosystem mapping in Secchi and is reported without advisory coverage.

Use --no-cache for a complete fresh fetch. It bypasses the local cache and re-fetches package metadata, registry signals, GitHub signals, and OSV security advisories.

Use --security-no-cache when only the OSV advisory data should be refreshed; the package, registry, and GitHub caches are reused.

See DuckDB report examples for package and project exports in JSON, Markdown, and HTML.

JSON reports declare a schema and schema_version so automation can reject or migrate incompatible output deliberately. Secchi's local package cache uses the same versioned-envelope approach and continues to read legacy unversioned cache entries while writing the current schema for new data.

The serialized boundaries are validated with Pydantic models while the internal application remains dataclass-based. This keeps the service and TUI lightweight while giving cache files, reports, and MCP responses explicit contracts. Future schema changes can be introduced as migrations instead of relying on every renderer and consumer to handle new fields independently.

search, show, dashboard, and report use the same data collection and scoring pipeline. Add --registry with pypi, crates.io, npm, homebrew, go, or cran when a package name needs an explicit ecosystem.

For registry troubleshooting, add --verbose to show readable SUCCESS, WARN, and FAILURE events, including HTTP response statuses. Use --log-file PATH to save the current run's diagnostics. In the dashboard, press l for the process log; f remains the favorites-only filter.

compare is an advisory decision aid for agents and engineers choosing between dependencies. It reports Recommended, Acceptable, Use with caution, or Avoid, along with the evidence and unknown signals behind the result. Use explicit registry:name references when comparing packages across ecosystems. Secchi does not install, upgrade, remove, or approve a dependency automatically.

See the Dashboard metrics and health score guide for the meaning of the dashboard cards, overview panels, health categories, grades, and practical ways to improve a package's signals.

List available projects:

Config

Secchi looks for config in this order:

1. --config / -c path
2. ./secchi.toml
3. ./.secchi.toml
4. ~/.config/secchi/config.toml

Example secchi.toml:

[projects.duckdb]
title = "DuckDB"
description = "DuckDB — embeddable analytical database"
favorite = true
repository = "https://github.com/duckdb/duckdb"
packages = [
    { name = "duckdb", registry = "pypi" },
    { name = "duckdb", registry = "npm" },
]

favorite belongs to the project, which makes workspace navigation clear when one project contains several registry variants of the same package. Existing package-level favorite entries remain supported for compatibility.

Optional Spotlight Feed

The dashboard can show a small, curated Spotlight card from Secchi's public feed. Spotlight is cached locally and can be disabled completely when you do not want Secchi to request the feed.

SECCHI_DISABLE_SPOTLIGHT=1 secchi dashboard duckdb

When this variable is set to 1, true, yes, or on, Secchi does not read or fetch Spotlight data and removes the card from the dashboard.

CLI Options

secchi dashboard [package]              Launch the TUI (workspace when omitted)
secchi show <package>                   Print a concise intelligence summary
secchi search <package>                 Search packages across supported registries
secchi report <package> --format <type> Generate json, html, or md output
secchi compare <package> <package>      Rank package choices; add --format json for agents
secchi check <package>                 Evaluate health and CI policies for automation
secchi --project <name>                 Backwards-compatible project dashboard
secchi --list                           List projects in config
secchi init                             Interactively create secchi.toml

Development

Live reload during development:

uv run textual run --dev src/secchi/dev.py -- -p duckdb

Press ctrl+r to manually reload the dashboard without exiting.

Coverage Reports

The latest main coverage report is published at kannandreams.github.io/secchi/coverage/ after GitHub Pages is enabled for the repository.

Project Information

• Contributing
• Changelog

License

Apache 2.0