Service management for the AI era

Install in Seconds

pnpm

pnpm add -D @chriscode/devmux

npm

npm install -D @chriscode/devmux

npx

npx @chriscode/devmux status

Why devmux?

Shared Awareness

Both humans and AI agents use the same tmux session naming convention (omo-{project}-{service}). One starts a server, the other reuses it.

Idempotent by Design

devmux ensure is safe to run multiple times. If the service is already running, it reuses it. No port conflicts. No duplicate processes.

Zero Config for Turbo

Auto-discovers services from your turbo.json. Just run devmux discover turbo and you’re set.

Built for AI Agents

Includes AGENTS.md template with exact instructions for Claude Code, OpenCode, and other AI coding assistants.

The Problem

When AI coding assistants work on your project, they often need to start dev servers:

• Port conflicts: Agent tries to start API on :8787, but you’re already running it
• Duplicate processes: Agent starts its own server, now you have two
• No cleanup: Agent’s server keeps running after the session ends
• No visibility: You can’t see what the agent started, agent can’t see what you started

The Solution

devmux creates shared awareness through tmux session naming:

# Human starts the API
devmux ensure api
# -> Creates tmux session: omo-myproject-api

# Later, AI agent needs the API
devmux ensure api
# -> Sees omo-myproject-api already running
# -> Reuses it (no restart!)

# Check what's running
devmux status
# Service    Status    Port    Session
# api        running   8787    omo-myproject-api

Both human and agent see the same services. Both can start, stop, or reuse them.

Quick Example

# Initialize config (auto-detects from turbo.json)
devmux init

# Start your API (idempotent - safe to run multiple times)
devmux ensure api

# Check status
devmux status

# View logs
devmux attach api

# Run a command with services, cleanup on exit
devmux run --with api -- npm test

# Stop when done
devmux stop api

For AI Agents

Add this to your AGENTS.md file so AI assistants know how to use devmux:

## Service Management

Before starting dev servers, check if they're already running:

\`\`\`bash
devmux status
\`\`\`

To start a service (idempotent):

\`\`\`bash
devmux ensure api
\`\`\`

NEVER start servers with raw commands like `pnpm dev`.
Always use devmux to prevent port conflicts.

See the AI Agent Integration guide for the full template.