> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibetunnel.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

# Claude Development Notes

## Build Process

* **Never run build commands**
* the user has `pnpm run dev` running which handles automatic rebuilds, either directly or via the mac app
* Never manually run the server. The user does that
* Changes to TypeScript files are automatically compiled and watched
* Do not run `pnpm run build` or similar build commands

## Development Workflow

* Make changes to source files in `src/`
* **ALWAYS run code quality checks before committing:**
  * `pnpm run check` - Run all checks (format, lint, typecheck) in parallel
  * This is the ONLY command you need to run for checking
  * It runs everything concurrently for maximum speed
* **If there are issues to fix:**
  * `pnpm run check:fix` - Auto-fix formatting and linting issues (runs sequentially to avoid conflicts)
* **Individual commands (rarely needed):**
  * `pnpm run format` / `pnpm run format:check`
  * `pnpm run lint` / `pnpm run lint:fix`
  * `pnpm run typecheck`
* Always fix all linting and type checking errors, including in unrelated code
* Never run the tests, unless explicitly asked to. `pnpm run test`

## Code References

**THIS IS OF UTTER IMPORTANCE THE USERS HAPPINESS DEPENDS ON IT!**
When referencing code locations, you MUST use clickable format that VS Code recognizes:

* `path/to/file.ts:123` format (file:line)
* `path/to/file.ts:123-456` (ranges)
* Always use relative paths from the project root
* Examples:
  * `src/cli.ts:92` - single line reference
  * `src/server/pty/pty-manager.ts:274-280` - line range
  * `web/src/client/app.ts:15` - when in parent directory

NEVER give a code reference or location in any other format.

## Git Commands

When asked to "commit and push", "commit + push", "/cp", or "c+p", use a single command:

```bash theme={null}
git add -A && git commit -m "commit message" && git push
```

Do NOT use three separate commands (add, commit, push) as this is slow.

## Refactoring Philosophy

* We do not care about deprecation - remove old code completely
* Always prefer clean refactoring over gradual migration
* Delete unused functions and code paths immediately
* **We do not care about backwards compatibility** - Everything is shipped together
* No need to support "older UI versions" - the web UI and server are always deployed as a unit

## Best Practices

* ALWAYS use `Z_INDEX` constants in `src/client/utils/constants.ts` instead of setting z-index properties using primitives / magic numbers
* Add ids to web elements whenever needed to make testing simpler. This helps avoid complex selectors that search by text content or traverse the DOM
  * Use descriptive IDs like `session-kill-button`, `show-exited-button`, `file-picker-choose-button`
  * Prefer ID selectors (`#element-id`) over complex queries in tests
  * When adding interactive elements (buttons, inputs), always consider adding an ID for testability

## CRITICAL: Package Installation Policy

**NEVER install packages without explicit user approval!**

* Do NOT run `pnpm add`, `npm install`, or any package installation commands
* Do NOT modify `package.json` or `pnpm-lock.yaml` unless explicitly requested
* Always ask for permission before suggesting new dependencies
* Understand and work with the existing codebase architecture first
* This project has custom implementations - don't assume we need standard packages

## CRITICAL: vt Command in package.json

**IMPORTANT: DO NOT add "vt": "./bin/vt" to the bin section of package.json or package.npm.json!**

* The vt command must NOT be registered as a global binary in package.json
* This is because it conflicts with other tools that use 'vt' (there are many)
* Instead, vt is conditionally installed via postinstall script only if available
* The postinstall script checks if vt already exists before creating a symlink

## CRITICAL: Playwright Test UI Changes

**IMPORTANT: When tests fail looking for UI elements, investigate the actual UI structure!**

### Best Practices for Test Stability

1. **Always use semantic IDs and data-testid attributes** - These are more stable than CSS selectors
2. **Understand the UI structure** - Don't just increase timeouts, investigate why elements aren't found
3. **Check for collapsible/expandable sections** - Many elements are now hidden by default
4. **Wait for animations** - After expanding sections, wait briefly for animations to complete
5. **Use proper element states** - Wait for 'visible' not just 'attached' for interactive elements