/setup-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](https://github.com/gillkyle/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 DevTools`
• Common Next.js excludes: `[Fast Refresh]`, `compiled successfully`

**Service muting**: Hide specific services from terminal output while preserving log files:

• Useful for noisy frontend dev servers when focused on backend work

**Browser log capture**: Capture `console.*`, unhandled errors, and unhandled promise rejections from the browser

**Log format**: All logs use timestamp + level + message format: `[10:30:00.123] [LOG ] Message here`

**Gitignore warning**: Agent-tail warns on startup if `tmp/` is not gitignored. Disable with `warnOnMissingGitignore: false` in plugin options. </configuration_options>

<anti_patterns> <pitfall name="forgetting-browser-setup"> For Vite/Next.js projects, the CLI alone does not capture browser console logs. The framework plugin is required for browser log capture. </pitfall>

<pitfall name="monorepo-without-init"> In monorepos using Turborepo/Nx, you must run `agent-tail-core init` before `turbo dev` (or equivalent). Without init, `agent-