qdhenry/setup-agent-tail

<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

bash
# 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:

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

If user specified excludes or muting, add flags:

json
{
  "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-tail-core wrap in child packages has no session to join. </pitfall>

<pitfall name="using-agent-tail-cli-instead-of-agent-tail-core"> The agent-tail umbrella package has a broken bin field — it references a nested path that package managers don't resolve correctly. Always use agent-tail-core as the CLI command in scripts, and always install agent-tail-core as an explicit devDependency alongside agent-tail. </pitfall>

<pitfall name="overwriting-existing-scripts"> When modifying package.json scripts, preserve the original command inside the agent-tail runner. Do not replace the command, wrap it. </pitfall> </anti_patterns>

<success_criteria> Setup is complete when:

• agent-tail is installed as a dev dependency
• Framework plugin configured (if Vite or Next.js)
• package.json dev script wraps services with agent-tail
• tmp/ is in .gitignore
• User has been told how to verify the setup works

</success_criteria>

<reference_guides> Framework-specific configuration code: See references/framework-configs.md </reference_guides>