# Local Development

> Start, reuse, inspect, or browser-test local apps and services in this monorepo. Use for local service status, generated endpoint configuration, worktree ports, fake-user login, restarts, and logs.

- Skill: `kilo-org/local-development` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kilo-org/local-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kilo-org/local-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Kilo-Org (https://skillmd.com/u/kilo-org)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kilo-org/local-development

---


# Local development

Read `DEVELOPMENT.md` for human setup and service procedures. Read `ENVIRONMENT.md` for the environment-variable inventory. Shared web environment mutations are governed by `apps/web/AGENTS.md`; do not use this skill for that workflow.

## Start or reuse services

Before accessing local app or service endpoints, inspect this worktree's services:

```bash
pnpm dev:status --json
```

Reuse an active session and its reported ports. Do not start a competing stack.
`dev:start` cannot add services to an existing session. If the active session
does not include required services, stop it with `pnpm dev:stop`, then recreate
it with the complete needed group or named-service selection:

```bash
KILO_PORT_OFFSET=auto pnpm dev:start <needed-group-or-services>
```

When no session is active, start only the needed group or named services. If
generated local endpoint configuration is needed first, run the matching
selector, then start that same selection with the same automatic offset:

```bash
KILO_PORT_OFFSET=auto pnpm dev:env <needed-group-or-service>
KILO_PORT_OFFSET=auto pnpm dev:start <needed-group-or-service>
```

After startup or reuse, obtain actual ports from `.dev-port`, `pnpm dev:status --json`, or `dev/logs/manifest.json`. Never assume defaults. Open web at `http://localhost:<reported-port>/`.

A worktree on a port offset runs its own database container and starts empty. Run `pnpm test:db` for migrations, then seed the data the task needs. Read the connection string from this worktree's `.env.local`; never assume port 5432.

Run `pnpm test:db` before `pnpm test` in a worktree. It writes this worktree's database to `apps/web/.env.test.local`, which is the only file the Jest setup loads that can hold it. Without that file, Jest runs against port 5432 and drops a sibling worktree's test databases.

## Fake login

Use:

```text
http://localhost:<reported-port>/users/sign_in?fakeUser=<fake-email>&callbackPath=<path>
```

Always set `callbackPath` to destination page. Build `<fake-email>` as `kilo-<username>-<time including seconds>@example.com`, where username comes from home directory. For admin access, email must end in `@admin.example.com`. Wait for account-creation spinner to finish. Open admin panel from top-right account menu.

## Service management

| Command or path | Use |
|---|---|
| `dev/logs/manifest.json` | Static service and port snapshot written by `dev:start`. |
| `pnpm dev:status` | Live service status and ports. |
| `pnpm dev:status --json` | Machine-readable session, offset, service, port, status, and group data. |
| `pnpm dev:restart <service>` | Restarts a running service. |
| `dev/logs/<service>.log` | Service log file. |

Use `tail -f dev/logs/<service>.log` to follow a service log.