Skip to main content

panopticas

Discover insights into the types of data and functions used in your code.

Inspired by tools like enry and linguist

Features: language detector and metadata identifiers, based on the filename extension, filename details and the shebang line. Detects build configurations, dependency manifests, CI pipeline files, AI coding agent artifacts, and binary file types.

The official documentation can be found at panopticas.io

Installation

pip install panopticas

Requires Python 3.12 or later.

Usage

The examples below cover the common cases. For every command, every option and the JSON shape each one emits, see the CLI reference.

Change into the directory you want to check the file types of and then run:

panopticas assess

assess respects .gitignore. Two options change what it reports:

panopticas assess -unknown        # only files whose language could not be identified
panopticas assess --lines         # include a line count for each file

To check a single file and get some metadata:

panopticas file FILENAME

To find URLs in files:

panopticas urls /path/to/directory
panopticas urls /path/to/directory -all-files   # include gitignored files

AI coding agent detection

Panopticas identifies the file and directory artifacts left by AI coding agents, and tags each one with three tags: AI, the product brand, and the kind of artifact.

CLAUDE.md                       -> AI, Claude, instructions
.cursor/rules/style.mdc         -> AI, Cursor, rules
.github/copilot-instructions.md -> GitHub, Git, AI, Copilot, instructions

Detection is path-based only — no file is opened to determine AI metadata.

panopticas ai
panopticas ai /path/to/directory
panopticas ai --all-files   # include gitignored files and bare AI directories

The command lists each artifact with its product and kind, then summarises which AI products the repository uses. See the AI detection rules reference for the full inventory, the source that confirms each convention, and the candidates that were investigated and rejected.

Vocabularies

Three commands print the vocabularies panopticas works with. The tag list is derived from the detection rules themselves, so it cannot drift from what the tool actually assigns.

panopticas tags        # every tag panopticas can assign to a file
panopticas languages   # every language it recognises
panopticas filetypes   # every file type, languages or not

JSON output

Every command accepts --json (also spelled -json). In JSON mode stdout carries only the document — progress messages go to stderr — so output can be piped safely:

panopticas assess --json | jq '.files[] | select(.language == "Python")'
panopticas ai --json | jq '.products'

Development

If you want to check out the panopticas repo and work on bug fixes, use the pip "editable" install:

pip install -e .

Running Tests

pytest -v

Relationship to kospex

Panopticas is a dependency of kospex, which uses it for file type detection and metadata extraction during repository sync. Tags are stored in the kospex database, so adding a tag is safe but renaming or removing one is a breaking change.

Changelog

See CHANGELOG.md for version history.

License

MIT

Metadata

Release files for panopticas 0.0.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for panopticas 0.0.22
File Size Uploaded Provenance Actions
panopticas-0.0.22.tar.gz 64.4 kB Without provenance Details for panopticas-0.0.22.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for panopticas 0.0.22
File Interpreter ABI Platform Actions
panopticas-0.0.22-py3-none-any.whl Python 3 none any Details for panopticas-0.0.22-py3-none-any.whl

Total release size: 93.5 kB

Release files / panopticas-0.0.22.tar.gz

Download URL panopticas-0.0.22.tar.gz
Size 64.4 kB
Tags Source
SHA-256 checksum
How to use checksums
66e360e615e636e4f367afc557b23402abc8803205c4d9a1415061e5ae6f76e5
BLAKE2b-256 checksum
How to use checksums
10e041423f2ab9e6318f7be5b9815c0fd516a03087cda0bd9ad98cdbc12a2204
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / panopticas-0.0.22-py3-none-any.whl

Download URL panopticas-0.0.22-py3-none-any.whl
Size 29.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3736456967b68d4d0205cb2329f76a57d2ec7c87ccf8da1412250064e2591630
BLAKE2b-256 checksum
How to use checksums
789a4be5c9eaf07fd7f8098c1cc91434ef3b9f7c3ee9c0f6e9c908c72144d9e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for panopticas 0.0.22

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page