/serve - Launch Project Dev Server

Launch a project's existing dev server with automatic port conflict resolution, dependency installation, and lifecycle management.

Key difference from /start-viewer: /start-viewer copies components TO coditect-core's viewer. /serve launches the PROJECT'S OWN dev server in-place — works with any Vite, Next.js, or React project.

System Prompt

EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

Execution:

# From project directory (auto-detect)
~/.coditect/scripts/frontend/serve.sh $ARGUMENTS

# With explicit project path
~/.coditect/scripts/frontend/serve.sh --project-dir /path/to/project $ARGUMENTS

What the script does:

1. Detect project root — walks up from CWD to find package.json with a dev script
2. Detect port — reads vite.config.js or package.json for configured port, defaults to 5173
3. Check port conflicts — uses scripts/port-check.sh to detect occupied ports
4. Resolve conflicts — offers to kill existing process or use alternate port
5. Install dependencies — runs npm install if node_modules/ is missing
6. Launch server — runs npm run dev with port override and optional browser open

Usage

/serve                              # Auto-detect and launch from CWD
/serve --port 5174                  # Use custom port
/serve --kill-existing              # Kill anything on target port first
/serve --no-open                    # Don't open browser
/serve --background                 # Run in background
/serve --project-dir /path/to/proj  # Specify project directory

Options

Flag	Description
-p, --port <number>	Override default port
--no-open	Don't open browser automatically
--kill-existing	Kill any process on target port before starting
--background	Run server in background (log to /tmp/)
--project-dir <path>	Specify project directory (default: CWD)
-v, --verbose	Verbose output
-h, --help	Show help

Examples

Launch BIO-QMS Viewer

cd submodules/dev/coditect-biosciences-qms-platform
/serve
# Detects Vite config, checks port 5173, installs if needed, launches

Launch on Alternate Port

/serve --port 5174
# Overrides default, launches on 5174

Force-Replace Existing Server

/serve --kill-existing
# Kills whatever is on the target port, then starts fresh

Launch in Background

/serve --background
# Server runs in background, log at /tmp/coditect-serve-5173.log
# Stop with: kill $(lsof -ti :5173)

Output Format

CODITECT Project Server Launcher

  Project:  coditect-biosciences-qms-platform
  Root:     /Users/dev/project
  Port:     5173

  Launching dev server...

======================================================================
  VITE v7.3.1  ready in 342 ms
  ➜  Local:   http://localhost:5173/
======================================================================

Port Conflict Output

  Port 5173 is already in use by node (PID: 12345)

  Options:
    1) Kill existing process and start
    2) Use alternate port 5174
    3) Cancel

  Choose [1/2/3]:

Supported Project Types

Type	Detection	Port Flag
Vite	vite.config.{js,ts,mjs}	--port N
Next.js	next in package.json	-p N
Generic	package.json + dev script	--port N

Troubleshooting

"No package.json with 'dev' script found"

• Ensure you're in or under a project directory
• The project must have "dev" in its package.json scripts
• Use --project-dir to specify the path explicitly

Port already in use

• Use --kill-existing to auto-kill the existing process
• Or use --port N to choose a different port
• Use /port-check --common to see all ports in use

Dependencies fail to install

• Check Node.js version: node -v (needs 18+)
• Check npm: npm -v
• Try manual install: cd project && npm install

Related Commands

Command	Purpose
/port-check	Check port status without launching
/start-viewer	Launch coditect-core's component viewer
/trajectory-dashboard	Launch trajectory dashboard

Related Components

Component	Path
Script	scripts/frontend/serve.sh
Port Utility	scripts/port-check.sh
Skill	skills/local-dev-server/SKILL.md
Agent	agents/local-dev-server.md

Success Output

When server launches successfully:

COMMAND COMPLETE: /serve
Project: <project-name>
Port: <port>
URL: http://localhost:<port>/
Mode: <foreground|background>

Completion Checklist

Before marking complete:

• Project detected from CWD or --project-dir
• Port conflicts resolved
• Dependencies installed (if needed)
• Server launched and responding

Failure Indicators

This command has FAILED if:

• No package.json found with dev script
• npm install fails
• Port conflict unresolved (user cancelled)
• Server crashes on startup

When NOT to Use

Do NOT use when:

• You need to start coditect-core's component viewer (use /start-viewer)
• The project doesn't have a Node.js dev server
• You want to check ports without launching (use /port-check)

Principles

This command embodies:

• #3 Complete Execution - Detect, install, resolve, launch — no manual steps
• #1 Recycle, Extend, Re-Use - Uses existing port-check.sh, npm ecosystem
• #4 Confirm Destructive Only - Only asks before killing processes

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Version: 1.0.0 Created: 2026-02-14 Author: CODITECT Core Team Track: H.9