/setup-project

Configure project-level automation by creating a .agnt.kdl configuration file. The agnt plugin's SessionStart hook will read this file and auto-start your configured services.

Steps

1. Detect Project Type

First, detect the project to find available scripts:

detect {path: "."}

2. Ask About Scripts to Auto-Start

Based on the detected scripts, use AskUserQuestion to ask:

Question: "Which scripts should auto-start when you open this project?"

• Present available scripts (dev, start, serve, watch, etc.)
• Allow multiple selections (multiSelect: true)
• Common choices: dev server, watch mode

3. Ask About Proxy Configuration

Use AskUserQuestion to ask:

Question: "Do you want to auto-start a debugging proxy?"

If yes, ask:

• Proxy ID: A short name (e.g., "dev", "app")
• Port detection: "auto" to detect from script output, or a specific port number
• Which script: Which script's port to monitor (usually the dev server)

4. Write .agnt.kdl Configuration

Create or update .agnt.kdl in the project root with KDL format:

// .agnt.kdl - agnt project configuration
// Auto-generated by /setup-project command

// Scripts to auto-start on session open
scripts {
    // script-name auto-start=true|false
    dev auto-start=true
}

// Proxy configuration
proxy "dev" {
    // Which script to watch for port detection
    script "dev"

    // Port detection: "auto" or specific port number
    port-detect "auto"

    // Fallback port if auto-detection fails
    fallback-port 3000

    // Optional: specific target host (default: localhost)
    // host "localhost"
}

5. Explain What Happens

After creating the config, inform the user:

1. Starting your dev environment: Run agnt run claude to start your AI coding session. This will:

   • Load your .agnt.kdl configuration
   • Auto-start all scripts with autostart: true in the background
   • Auto-start all proxies with autostart: true
   • Display running services in the status bar at the bottom of your terminal

2. Status bar information: The bottom status bar shows:

   • Running processes count (e.g., "⚙ 2 proc")
   • Proxy URLs for browser access (e.g., "frontend:3000 → proxy:18080")
   • Use CTRL+Y to toggle the overlay menu for more options

3. Overlay menu (CTRL+Y): Press CTRL+Y to access:

   • List of running processes and proxies
   • Quick actions (restart, stop, view output)
   • Browser access links
   • System status

4. Port visibility for OAuth: The status bar shows both your dev server port AND proxy port (e.g., "dev:3000 → proxy:18080"). Add BOTH to your OAuth redirect URLs:

   • Dev server: http://localhost:3000
   • Proxy: http://localhost:18080 (for browser debugging)

5. To modify: Edit .agnt.kdl directly or re-run /setup-project

6. To skip autostart: Run agnt run claude --no-autostart to start without auto-starting configured services

7. To restart a service: Use the MCP tool proc {action: "restart", process_id: "dev"} or access via CTRL+Y menu

Example Configuration

For a typical Node.js project:

scripts {
    dev auto-start=true
}

proxy "dev" {
    script "dev"
    port-detect "auto"
    fallback-port 3000
}

For a project with multiple services:

scripts {
    dev auto-start=true
    api auto-start=true
}

proxy "frontend" {
    script "dev"
    port-detect "auto"
    fallback-port 3000
}

proxy "backend" {
    script "api"
    port-detect "auto"
    fallback-port 8080
}