Logs unifiés dev (agent-tail)

name: setup-agent-tail

description: Configure agent-tail log aggregation for the current project. Auto-detects framework (Vite, Next.js, plain Node, monorepo) and sets up CLI runner, browser log plugins, and output destinations. Use when setting up agent-tail, configuring dev server logging, or piping logs for AI agent consumption.

<objective>

Configure agent-tail for the current project. Agent-tail pipes logs from dev servers and browser consoles into unified log files that AI coding agents can read and grep. This skill auto-detects the project type, proposes a configuration, and sets everything up after user confirmation.

</objective>

<quick_start>

Run the auto-detect workflow below. The skill will:

1. Detect project framework and structure
2. Propose a configuration
3. Install agent-tail after user confirms
4. Configure framework plugins, CLI scripts, and gitignore

</quick_start>

<essential_principles>

• Logs are written to tmp/logs/latest/ — this is agent-tail's standard output directory
• The tmp/ directory must be gitignored
• Browser log capture requires a framework plugin (Vite or Next.js) in addition to the CLI
• For monorepos, use agent-tail-core init at root and agent-tail-core wrap in each package
• Always confirm the proposed configuration with the user before making changes

</essential_principles>

<process>

Step 1: Detect project type

Read these files to determine the project setup:

• package.json — check for framework dependencies (vite, next, react, etc.) and existing scripts
• vite.config.ts / vite.config.js — Vite project indicator
• next.config.ts / next.config.js / next.config.mjs — Next.js project indicator
• turbo.json / nx.json / pnpm-workspace.yaml / lerna.json — monorepo indicators
• .gitignore — check if tmp/ is already ignored

Classify the project as one of:

• vite — Vite-based project (React, Vue, Svelte, etc.)
• nextjs — Next.js project
• monorepo — Turborepo, Nx, pnpm workspaces, or Lerna
• node-cli — Plain Node.js / any other project (CLI-only setup)

Step 2: Gather user preferences

Use AskUserQuestion to confirm detection and gather preferences:

Question 1: "I detected a [framework] project. Is this correct?"
  - Yes, proceed
  - No, it's actually [other options]

Question 2: "Which services should agent-tail manage?"
  - Based on detected scripts in package.json (e.g., "dev", "api", "worker")
  - Let user add custom service names and commands

Question 3: "Configure output destinations?"
  - Default (tmp/logs/latest/) (Recommended)
  - Custom directory
  - Custom directory with combined.log disabled

Question 4: "Set up browser console log capture?"
  - Yes (Recommended) — if Vite or Next.js detected
  - No, server logs only
  - [Skip this question for node-cli projects]

Step 3: Install agent-tail

# Detect package manager from lockfile
# bun.lock → bun
# pnpm-lock.yaml → pnpm
# yarn.lock → yarn
# package-lock.json → npm

<pkg-manager> add -D agent-tail agent-tail-core

Important: The agent-tail umbrella package has a broken bin field that prevents the CLI from being linked. You must also install agent-tail-core explicitly — this is the package that provides the actual agent-tail-core CLI binary. Use agent-tail-core (not agent-tail) as the command name in all scripts.

Step 4: Configure framework plugin

For each detected framework, apply the appropriate configuration. See references/framework-configs.md for exact code.

• Vite: Add agentTail() plugin to vite.config
• Next.js: Wrap config with withAgentTail(), add AgentTailScript to layout, create browser log API route
• Monorepo: Add agent-tail init to root dev script, wrap each package with agent-tail wrap
• Node CLI: No plugin needed, just CLI configuration

Step 5: Configure package.json scripts

Update package.json scripts to use agent-tail-core CLI. Transform existing dev scripts:

{
  "scripts": {
    "dev": "agent-tail-core run '<service1>: <original-command>' '<service2>: <original-command>'"
  }
}

If user specified excludes or muting, add flags:

{
  "scripts": {
    "dev": "agent-tail-core run --exclude '[HMR]' --mute worker '<services>'"
  }
}

Step 6: Update .gitignore

Add tmp/ to .gitignore if not already present.

Step 7: Verify setup

After configuration, tell the user:

• Run their dev script to verify logs appear in tmp/logs/latest/
• Check that individual service logs and combined.log are created
• If browser logging was enabled, verify console output appears in the browser log file

</process>

<configuration_options>

These options can be presented to the user during setup:

Output directory: Where logs are written (default: tmp/logs/latest/)

Excludes: Filter noisy log lines by substring or regex:

• Common Vite excludes: [HMR], [vite], `Download the React DevToo