# Development Guide

This guide is for contributors working on Voxcode locally.

## Prerequisites

- Node.js `>= 22.19.0`
- npm `>= 10`
- Git

## Clone and Install

```bash
git clone https://github.com/voxcode-dev/voxcode.git
cd voxcode
npm install --ignore-scripts
```

## Repository Layout

| Path | Purpose |
| --- | --- |
| `packages/voxcode` | CLI and product-facing runtime |
| `packages/voxcode-ai` | Providers and model integrations |
| `packages/voxcode-agent` | Agent runtime loop and orchestration |
| `packages/voxcode-tui` | Terminal UI components |

## Build and Validate

```bash
npm run build
npm run check
npm run test
```

## Local Run

```bash
node packages/voxcode/dist/cli.js --help
node packages/voxcode/dist/cli.js
```

## Recommended Contribution Workflow

1. Create a focused branch
2. Implement small, reviewable changes
3. Run build/check/test locally
4. Update docs when behavior changes
5. Open PR with clear verification notes

## Code Quality Expectations

- Keep changes scoped
- Preserve existing architecture conventions
- Avoid speculative refactors
- Include verification evidence in PR description

See top-level `CONTRIBUTING.md` for contribution policy details.
