Setup Agent TailSAFE

Professional slash commands for Claude Code that provide structured workflows for software development tasks including code review, feature creation, security auditing, and architectural analysis.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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**

```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-

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

Gates applied: no_behavioural_pass, no_license.