# 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](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 docs
```

## Features 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/setter

### Adding Commands
```python
BaseSheet.addCommand('', 'command-name', 'code', 'help text')
```

### Adding to Global Namespace
```python
vd.addGlobals(MyClass=MyClass)  # Use keyword args, not dict
```

### Adding Menu Items
```python
vd.addMenuItems('''
    Menu > Submenu > Item Name > command-name
''')
```

### Example Feature Structure
```python
from visidata import vd, Sheet, Column

# rowdef: 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](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](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](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](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](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](docs/README.md) to identify which documentation files need to be updated.


## README.md

# VisiData v3.3

[![Tests](https://github.com/saulpw/visidata/workflows/visidata-ci-build/badge.svg)](https://github.com/saulpw/visidata/actions/workflows/main.yml)
[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/saulpw/visidata)

[![discord](https://img.shields.io/discord/880915750007750737?label=discord)](https://visidata.org/chat)
[![Mastodon](https://img.shields.io/mastodon/follow/110136431814047095?domain=https%3A%2F%2Ffosstodon.org)](https://fosstodon.org/@saulpw)

A terminal interface for exploring and arranging tabular data.

![Frequency table](http://visidata.org/videos/freq-move-row.gif)

VisiData supports tsv, csv, sqlite, json, xlsx (Excel), hdf5, and [many other formats](https://visidata.org/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](https://pipx.pypa.io/) or [uv](https://docs.astral.sh/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](https://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](https://visidata.org/docs)
* [Plugin Author's Guide and API Reference](https://visidata.org/docs/api)
* [Quick reference](https://visidata.org/man) (available within `vd` with `Ctrl+H`), which has a list of commands and options.
* [Intro to VisiData Tutorial](https://jsvine.github.io/intro-to-visidata/) by [Jeremy Singer-Vine](https://www.jsvine.com/)

### Help and Support

If you have a question, issue, or suggestion regarding VisiData, please [create an issue on Github](https://github.com/saulpw/visidata/issues) or chat with us at #visidata on [irc.libera.chat](https://libera.chat/).

If you use VisiData regularly, please [support me on Patreon](https://www.patreon.com/saulpw)!

## 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 `<vd@saul.pw>`.

Anja Kefala `<anja.kefala@gmail.com>` maintains the documentation and packages for all platforms.

Many thanks to numerous other [contributors](https://visidata.org/credits/), and to those wonderful users who provide feedback, for helping to make VisiData the awesome tool that it is.