# Development

Internal engineering document. Build and validation rules live in [AGENTS.md](../../../AGENTS.md) and are binding for everyone with commit access.

## Setup

Byte Agent requires Node.js 22.8.0 or newer.

From a checkout of the Byte Agent repository:

```bash
cd zyte-agent
npm ci
```

Run from source:

```bash
/path/to/zyte-agent/zyte-agent.sh
```

The script can be called from any directory and preserves the caller's working directory. Use that behavior to run a source checkout against a separate test project.

## Product and Source Names

Byte Agent is the product name. The public npm package is `zyte-agent`, and its executable names are `zyte-agent` and `za`. The `@zyte-agent/*` workspace scope, `.zyte` paths, `ZYTE_AGENT_*` environment variables, and the `piConfig` manifest key are compatibility identifiers; do not present them as separate products.

Production releases publish the staged `zyte-agent` package to npm and publish versioned standalone artifacts to the stable distribution channel. Main-branch builds can also advance the beta standalone channel. `scripts/publish-npm.mjs` stages the public npm package; `scripts/pack-zyte-agent-release.mjs` stages the standalone artifacts. The `@zyte-agent/coding-agent` workspace package is source-only and is not the public install path.

## Local Configuration

User configuration lives under `~/.zyte/agent/`. Project-local settings, prompts, themes, extensions, skills, and system-prompt files live under `.zyte/agent/` in the project root. Override the user config directory with `ZYTE_AGENT_CODING_AGENT_DIR` and the session directory with `ZYTE_AGENT_SESSION_DIR`.

Use an isolated config directory when manually exercising daemon behavior so development sessions do not collide with normal sessions:

```bash
ZYTE_AGENT_CODING_AGENT_DIR=/tmp/zyte-agent-dev /path/to/zyte-agent/zyte-agent.sh
```

## Daemon Protocol Changes

Classify every daemon command, event, or response-shape change as backward-compatible, capability-gated, or incompatible. Optional behavior must be negotiated and degrade locally. Follow the protocol-version, schema-revision, compatibility-map, and cross-version test requirements in the root `AGENTS.md` before changing the wire contract.

## Package Asset Resolution

Byte Agent runs from source, Node.js package output, and standalone release artifacts. Always use `src/config.ts` helpers for package assets:

```typescript
import { getPackageDir, getThemeDir } from "./config.js";
```

Do not resolve packaged assets directly from `__dirname`.

## Debugging

The hidden `/debug` command writes `~/.zyte/agent/zyte-agent-debug.log` with rendered TUI lines, their visible widths, and the current agent messages. Daemon, worker, client, and provider diagnostic logs live under `~/.zyte/agent/logs/`.

Useful service commands:

```bash
zyte-agent status
zyte-agent doctor
zyte-agent doctor --fix
zyte-agent shutdown
```

## Validation

After code changes, run the repository check from the root:

```bash
npm run check
```

This performs formatting, linting, type checking, installer rendering checks, and the browser smoke check. It does not run the test suite.

Run focused tests from the package root. For example:

```bash
cd packages/coding-agent
npx tsx ../../node_modules/vitest/dist/cli.js --run test/specific.test.ts
```

If you create or modify a test file, run that file and iterate until it passes. Coding-agent suite regressions belong under `test/suite/regressions/` and use the suite harness and faux provider rather than live provider credentials.