# Start Chartsmith locally

This is the complete local edition of Chartsmith, not a simulated demo. It
shows ten finished journeys immediately and can run the genuine autonomous
redesign workflow on a chart image you upload.

The web app, workflow process, and generated artifacts run on your computer.
Model inference uses your signed-in Codex account over the internet, so this is
not an offline application.

## Before you start

You need:

- Windows 10 or 11 for the verified one-command path
- [Python 3.11 or newer](https://www.python.org/downloads/)
- [Node.js 22.13 or newer, including npm](https://nodejs.org/en/download)
- an internet connection
- a ChatGPT account that can sign in to Codex

You do not need to create or paste an OpenAI API key. On Windows, the setup
downloads an isolated current Codex executable if one is not already
available. Chartsmith then uses Codex's normal browser sign-in.

## First launch

1. Extract the ZIP to a normal writable folder.
2. Open PowerShell or another terminal inside that extracted folder.
3. Run:

```powershell
python scripts/setup_and_start.py
```

The first launch creates a local Python environment, installs the exact Python
and web requirements, validates the packaged product, checks Codex sign-in, and
starts both local services. This can take a few minutes.

If Codex is not signed in, setup stops before launching anything and prints the
exact `codex login` command to run. Complete the browser sign-in and run the
setup command again.

When the terminal prints:

```text
Chartsmith is ready at http://localhost:3000/
```

open [http://localhost:3000/](http://localhost:3000/) in your browser. Keep the
terminal open while using Chartsmith. Press `Ctrl+C` there to stop it.

Later launches reuse the installed requirements unless their lock files have
changed.

## What happens during a real redesign

Upload one PNG, JPEG, or WebP chart image. Chartsmith reconstructs its message,
develops multiple design directions, selects one, renders it, and inspects and
repairs visible defects. Intermediate reasoning and artifacts appear in the
studio as each stage completes. A full run can take tens of minutes.

The goal is persuasive visual communication from minimal input. It is not a
pixel-perfect data-extraction tool for high-stakes reporting; review the final
chart before using it as evidence.

## Troubleshooting

### `python` is not recognized or is too old

Install [Python 3.11+](https://www.python.org/downloads/) and enable
**Add Python to PATH** in the Windows installer. Open a new terminal and check:

```powershell
python --version
```

### Node.js or npm is missing or too old

Install [Node.js 22.13+](https://nodejs.org/en/download), open a new terminal,
and check:

```powershell
node --version
npm --version
```

### Codex sign-in is required

Run the exact login command printed by Chartsmith, complete the browser flow,
then rerun the setup command. If `codex` is installed globally, the command is:

```powershell
codex login
```

You can confirm the session with `codex login status`. See OpenAI's
[Codex authentication guide](https://learn.chatgpt.com/docs/auth).

### Port 3000 or 8765 is already in use

Stop the other local Chartsmith or development process using that port, then
run setup again. Chartsmith does not silently replace another service.

### Installation fails during a download

Check the internet connection, close the terminal, and run the same setup
command again. Completed requirements are cached, so a retry does not normally
start from zero.

### Check the ZIP without installing anything

```powershell
python scripts/setup_and_start.py --check
```

This verifies that the workflow, ten example journeys, assets, validation
images, and local design-reference index are all present.

For implementation details and non-Windows notes, continue to [README.md](README.md).
