Repository: saulpw/visidata
Stars: 9029
CLAUDE.md
VisiData Development Guide
Quick reference for VisiData development. For detailed coding patterns, conventions, and best practices, see dev/STYLE.md.
CLAUDE.md and AGENTS.md are complementary: use this file for primary contributor workflow and architecture context, and use AGENTS.md for concise agent-oriented repository guidance.
Important Note About AI Usage
VisiData (created in 2016) is 99% written by humans and is NOT a vibe-coded AI project. This file is meant to allow AI-assisted development of features and bugfixes. All code must be reviewed and approved and tested by a human before being merged into the codebase or submitted as a PR.
Repository Structure
visidata/
├── visidata/ # Main package
│ ├── *.py # Core modules (sheet.py, column.py, etc.)
│ ├── features/ # Auto-loaded feature plugins
│ ├── loaders/ # File format loaders
│ ├── apps/ # Standalone applications
│ └── experimental/ # Experimental features (load/install with 'import visidata.experimental.foo')
├── tests/ # Test files
├── docs/ # Documentation
└── dev/ # Development utilities and docsFeatures Directory (visidata/features/)
- All .py files in this directory are automatically imported when VisiData starts
- Each feature file should be self-contained
- Features extend VisiData functionality without modifying core files
Quick Reference
Core Classes
-
BaseSheet - Minimal sheet functionality-
Sheet / TableSheet - Sheet with columns and rows (most common)-
Column - Column definition with getter/setterAdding Commands
BaseSheet.addCommand('', 'command-name', 'code', 'help text')Adding to Global Namespace
vd.addGlobals(MyClass=MyClass) # Use keyword args, not dictAdding Menu Items
vd.addMenuItems('''
Menu > Submenu > Item Name > command-name
''')Example Feature Structure
from visidata import vd, Sheet, Columnrowdef: description of what a row represents
class MySheet(Sheet):
rowtype = 'items'
columns = [
Column('name', getter=lambda c,r: r.attribute),
] def reload(self):
self.rows = [...]
BaseSheet.addCommand('', 'my-command', 'code', 'help')
vd.addGlobals(MySheet=MySheet)
Development Workflow
1. Add .py file to visidata/features/
2. Run vd and test interactively
3. Iterate and refine
4. Document with docstrings and comments
Make Targets
- make test — run all tests
- make help — list all targets
Documentation
For comprehensive development documentation, see the dev/ directory:
dev/STYLE.md - Coding Style and Patterns
Use this when writing code, creating features, or defining sheets and columns.
- Naming conventions (camelCaps, under_score, etc.)
- Feature file structure and patterns
- Sheet and Column class patterns
- Command and menu integration
- API decorators
- Best practices and examples
dev/GIT.md - Version Control Practices
Use this when making commits or preparing pull requests.
- Commit message format and conventions
- Issue tracking in code
- Branch and merge workflow
- Patch-safe commit marking
dev/DOCS.md - Documentation Writing
Use this when writing user-facing documentation, help text, or in-app guides.
- VisiData's markdown syntax
- Display attribute syntax (colors, clickable links)
- Option and command reference format
- Technical writing guidelines
dev/PERFORMANCE.md - Performance Analysis
Use this when investigating or optimizing performance issues.
- Finding reproducible performance issues
- Profiling techniques and tools
- Analyzing profiling results
- Optimization workflow
dev/OPTIONS.md - Options System
Use this when working with options, adding new options, or understanding how configuration resolves.
- Resolution chain (instance → class → global → default)
- How sheets and paths participate in options
- Setting and reading options at different levels
Updating Documentation
When making user-facing changes (new commands, changed behavior, new options, new/changed loaders, UI changes), check docs/README.md to identify which documentation files need to be updated.
README.md
VisiData v3.3
A terminal interface for exploring and arranging tabular data.
VisiData supports tsv, csv, sqlite, json, xlsx (Excel), hdf5, and many other formats.
Platform requirements
- Linux, OS/X, or Windows (with WSL)
- Python 3.8+
- additional Python modules are required for certain formats and sources
Install
To install the latest release from PyPi:
pip3 install visidata
To try VisiData without installing, use pipx or uv:
pipx run visidata # or: uvx visidata
To install permanently (adds vd to your PATH):
pipx install visidata # or: uv tool install visidata
Additional Python packages are needed for some formats:
pipx install visidata --preinstall openpyxl --preinstall lxml
# or: uv tool install visidata --with openpyxl --with lxml
To add format packages to an existing pipx install:
pipx inject visidata openpyxl lxml
To install the cutting edge develop branch (no warranty expressed or implied):
pip3 install git+https://github.com/saulpw/visidata.git@develop
See visidata.org/install for detailed instructions for all available platforms and package managers.
Usage
$ vd <input>
$ <command> | vd
Press Ctrl+Q to quit at any time.
Hundreds of other commands and options are also available; see the documentation.
Documentation
* VisiData documentation
* Plugin Author's Guide and API Reference
* Quick reference (available within vd with Ctrl+H), which has a list of commands and options.
* Intro to VisiData Tutorial by Jeremy Singer-Vine
Help and Support
If you have a question, issue, or suggestion regarding VisiData, please create an issue on Github or chat with us at #visidata on irc.libera.chat.
If you use VisiData regularly, please support me on Patreon!
License
Code in the stable branch of this repository, including the main vd application, loaders, and plugins, is available for use and redistribution under GPLv3.
Credits
VisiData is conceived and developed by Saul Pwanson <[email protected]>.
Anja Kefala <[email protected]> maintains the documentation and packages for all platforms.
Many thanks to numerous other contributors, and to those wonderful users who provide feedback, for helping to make VisiData the awesome tool that it is.