How to Do JSON to CSV Conversion on Claude Code

March 13, 2026

The fastest way to convert JSON to CSV on Claude Code is to paste a sample of your JSON and ask Claude to write the conversion script in your language of choice. Claude handles flat and nested structures, infers headers from your keys, and writes runnable code in one pass. It works best for developers who want to stay in flow without leaving their editor to find a converter tool.

Works with Python (csv, pandas), Node.js (json2csv), or shell (jq)
Claude can flatten nested JSON objects into dot-notation columns automatically
The /usage command or Usagebar lets you track how much of your session budget you've spent before running longer batch jobs

What JSON to CSV conversion looks like in a Claude Code session

Open a terminal with Claude Code active in your project directory. You don't need any special slash commands for this task. Simply describe what you have and what you want:

> I have a file called data.json with an array of objects. Each object has user_id, name, email, and a nested address field with city and country. Write a Python script that converts it to a flat CSV with headers: user_id, name, email, address_city, address_country.

Claude will generate a working script immediately. If your JSON schema is complex, paste 2-3 representative rows directly into the prompt so Claude can infer edge cases (missing keys, null values, arrays within objects).

How to handle flat JSON arrays

For a simple flat structure like [{"id": 1, "name": "Alice", "score": 99}], the shortest approach is a one-liner using Python's standard library:

import json, csv

with open('data.json') as f:
    data = json.load(f)

with open('output.csv', 'w', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=data[0].keys())
    writer.writeheader()
    writer.writerows(data)

Ask Claude Code to generate this and it will also add error handling for empty files, encoding issues, and mismatched keys across rows. Tell Claude to "handle rows with missing keys gracefully" and it will add extrasaction='ignore' or fill blanks with empty strings depending on what makes sense for your use case.

How to flatten nested JSON for CSV output

Nested objects are the main friction point in JSON-to-CSV conversion. Claude Code handles this well when you are explicit about your desired output shape. There are two approaches:

Option 1: Use pandas with json_normalize

This is the most readable approach for Python developers and handles arbitrary nesting depth:

import pandas as pd

df = pd.json_normalize(data, sep='_')
df.to_csv('output.csv', index=False)

pandas json_normalize flattens nested dicts using a separator you choose (_ or .). Columns become address_city, address_country, and so on. This is the recommended approach for one-off data work.

Option 2: Use jq in the shell

If you prefer staying in the shell without a Python environment, jq can flatten and format to CSV directly:

jq -r '.[] | [.user_id, .name, .email, .address.city, .address.country] | @csv' data.json

Ask Claude to write the jq filter for your specific schema. It will get the field paths right without you having to memorize jq syntax. According to the jq manual, the @csv format automatically handles quoting and commas inside values.

Option 3: Node.js with json2csv

For Node.js projects, the json2csv npm package supports transforms and streaming for large files:

import { Parser } from 'json2csv';
const parser = new Parser({ fields: ['id', 'name', 'address.city'] });
const csv = parser.parse(data);

Claude Code can scaffold this, add the npm install step, and wire it into an existing script in your project. Just describe the context and it handles the plumbing.

How to use Claude Code slash commands during conversion work

A few built-in Claude Code behaviors are useful during data conversion tasks:

Inline file reading: Claude Code can read your actual data.json file if it is in the project directory. Ask it to "read data.json and write the converter script based on what you see" rather than pasting the whole file into the prompt.
/usage command: Run /usage to check your remaining session budget before kicking off a large batch conversion task. Large files and multi-step data pipelines can burn through tokens faster than single-file tasks. As noted in Anthropic's usage limit best practices, being aware of your limits before long tasks prevents mid-task interruptions.
Iterative refinement: After Claude generates the script, run it and paste error output back into the session. Claude will fix it in context without you having to re-explain the schema.

For more on the available slash commands, see the best Claude Code commands for developers.

Handling edge cases Claude Code deals with well

Real-world JSON is messy. Here are the edge cases Claude handles reliably when you mention them in your prompt:

Arrays within objects: e.g., tags: ["a", "b"]. Claude will either join them as a semicolon-delimited string or explode them into multiple rows, depending on what you ask for.
Inconsistent keys across rows: Claude will collect all unique keys across the dataset and fill missing values with empty strings.
Large files: For files over a few hundred MB, ask Claude to write a streaming version using Python's ijson library or Node.js streams instead of loading everything into memory.
Date formatting: Mention your target date format (ISO 8601, US locale, etc.) so Claude standardizes timestamps in the output.
Unicode and encoding: Ask Claude to add encoding='utf-8-sig' if the CSV will be opened in Excel, which requires the BOM marker to display non-ASCII characters correctly.

Staying aware of your usage while working on data tasks

Data pipeline work in Claude Code can be iterative, especially when debugging schema issues or handling large files. Each back-and-forth pass within a session counts toward your Claude Pro or Max plan usage window. If you hit a limit mid-task, you face a multi-hour wait before your session resets.

Usagebar sits in your macOS menu bar and shows your current usage at a glance, with alerts at 50%, 75%, and 90% consumption. That means you know to wrap up or save progress before getting locked out, instead of discovering the limit when you try to send the next message. Credentials are stored in macOS Keychain. Pricing is pay-what-you-want, with a free option for students.

You can also check usage via /usage in the Claude Code terminal or at claude.ai/settings/usage. See also: how to check your Claude Code usage limits and when your Claude Code usage resets.

Get Usagebar to keep an eye on your usage while working through multi-step data tasks.

Key takeaways

Paste a sample of your JSON directly into the Claude Code prompt so it infers the exact schema.
Specify your language (Python, Node.js, shell) and whether you want a one-off script or something reusable.
For nested JSON, ask for pandas.json_normalize (Python) or dot-notation field paths (jq, json2csv).
Mention edge cases up front: missing keys, arrays in values, large file sizes, date formatting.
Run /usage or check Usagebar before long iterative sessions to avoid mid-task lockouts.

Sources

Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar