# Usage Guide

This guide covers day-to-day Voxcode usage in interactive and scripted modes.

## Interactive Mode

Start the TUI:

```bash
vox
```

Use interactive mode when you want to:

- iterate on complex changes
- inspect and edit multiple files
- run validation commands in loop
- preserve context over time

## One-Shot Prompt Mode

Run a single instruction and exit:

```bash
vox -p "Generate unit tests for src/parser.ts"
```

Use this for quick automation and shell scripts.

## JSON / Machine-Friendly Output

```bash
vox --json -p "Summarize current git diff"
```

Useful for CI pipelines and tool integrations.

## Typical Workflow Pattern

1. Ask Voxcode to inspect relevant files
2. Request a small safe change
3. Run tests/lint/build
4. Review output and iterate
5. Commit once verified

## Prompting Tips

- Be explicit about **scope** (which files, which feature)
- Include **constraints** (no API break, keep backward compatibility)
- Request **verification** (tests, typecheck, lint)
- Ask for **summary with file paths**

Example:

```text
Refactor `src/session.ts` to reduce duplicated logic, keep API unchanged, run tests, and summarize all modified files.
```

## Working with Existing Repositories

- Start from repo root
- Mention target package/path in your prompt
- Prefer incremental changes over broad rewrites

## Continuing Work

Resume previous context:

```bash
vox --continue
```

See [sessions.md](sessions.md) for branching and compaction.
